A COBOL table with OCCURS 50 TIMES will not protect itself when a bad subscript tries to read occurrence 51. The SSRANGE compiler option tells Enterprise COBOL to generate runtime checks for table references and reference modification, so these errors are found before they quietly damage nearby storage.
What is the COBOL SSRANGE compiler option?
SSRANGE generates code that checks whether subscripts, indexes, ALL subscripts, variable-length references, and reference modification expressions point outside the valid storage area. IBM documents the default as NOSSRANGE.
If SSRANGE is coded without suboptions, IBM treats it as SSRANGE(NOZLEN,ABD). That means zero-length reference modification is treated as an error, and the first detected range problem causes a runtime error and abend.
SSRANGE vs NOSSRANGE
| Option | Runtime behavior | Good fit |
|---|---|---|
NOSSRANGE |
No generated range-check code for the covered references. | Production programs where performance matters and range logic has already been tested. |
SSRANGE |
Generated code checks covered table, index, and reference modification use. | Unit test, system test, migration test, and programs with suspected storage overlay. |
Table range example
This table allows 50 entries. If WS-SUB becomes 51, the program is trying to address storage outside the table. With SSRANGE, Enterprise COBOL can catch that bad reference at run time.
01 WS-CUSTOMER-TABLE.
05 WS-CUSTOMER-ENTRY OCCURS 50 TIMES.
10 WS-CUSTOMER-ID PIC X(10).
10 WS-CUSTOMER-BAL PIC S9(7)V99 COMP-3.
01 WS-SUB PIC S9(4) COMP.
MOVE 51 TO WS-SUB
DISPLAY WS-CUSTOMER-ID(WS-SUB)Without a range check, the display might read some unrelated field after the table. That kind of failure is painful because the abend may happen much later than the bad reference.
Reference modification checks
SSRANGE also checks reference modification for non-UTF-8 data items and function values. IBM documents checks for starting position, current length, ending position, and length value.
01 WS-NAME PIC X(20).
01 WS-START PIC S9(4) COMP.
01 WS-LEN PIC S9(4) COMP.
MOVE 18 TO WS-START
MOVE 5 TO WS-LEN
DISPLAY WS-NAME(WS-START:WS-LEN)In this example, positions 18 through 22 are requested from a 20-byte field. That should be fixed in logic, not hidden by hoping the next bytes happen to be harmless.
MSG and ABD suboptions
The MSG and ABD suboptions control what happens after a range check fails. Use ABD when the first bad reference should stop the program. Use MSG during migration or wider testing when you want warning messages and continued execution so more range problems can be found in one run.
CBL SSRANGE(MSG)
* or
CBL SSRANGE(ABD)MSG is useful for discovery, but do not treat a warning-only run as clean production behavior. A bad subscript still needs a code fix.
ZLEN and NOZLEN suboptions
ZLEN and NOZLEN control zero-length reference modification. With ZLEN, a zero length is allowed. With NOZLEN, a zero length gets an SSRANGE error. IBM documents NOZLEN as the compatible behavior with older SSRANGE handling.
CBL SSRANGE(ZLEN,MSG)
CBL SSRANGE(NOZLEN,ABD)Pick the setting that matches your compiler level and site migration rule. The point is not to make the compile option look tidy; it is to catch the reference rules your application must obey.
Performance impact
SSRANGE adds generated checks to many references. IBM performance guidance recommends NOSSRANGE for best performance and notes that range checking can slow programs that use subscripts, indexes, and reference modification in performance-sensitive paths.
IBM also documents that in COBOL 6 the compiled-in checks are always conducted at run time. You cannot compile with SSRANGE and then turn those checks off later by specifying CHECK(OFF).
When to use SSRANGE
- Use it during unit test for programs with new or changed tables.
- Use it when a storage overlay points to bad subscript logic.
- Use it during compiler migration testing.
- Use it for a focused diagnostic compile when production data exposes a rare table problem.
When to avoid SSRANGE
Avoid leaving SSRANGE on blindly for call-heavy, table-heavy, or high-volume batch programs unless the site has chosen that tradeoff. If only a few references need checking, a local bounds check around those references can be faster and easier to explain.
IF WS-SUB >= 1 AND WS-SUB <= 50
DISPLAY WS-CUSTOMER-ID(WS-SUB)
ELSE
DISPLAY 'BAD CUSTOMER SUBSCRIPT: ' WS-SUB
END-IFLocal checks are also useful when the program should handle bad input gracefully instead of abending on the first bad table reference.
Common mistakes
Thinking SSRANGE checks the subscript value itself
IBM explains that each subscript or index is not individually checked for validity. The effective address is checked to make sure it does not reference outside the table area.
Expecting CHECK(OFF) to disable COBOL 6 SSRANGE checks
For COBOL 6, compiled-in SSRANGE checks remain active at run time. Plan the compile option deliberately.
Using NOSSRANGE to hide a real bug
NOSSRANGE can reduce overhead, but it does not make bad table logic correct. Fix the subscript or reference modification rule first.
Related Mainframe Forum guides
For nearby topics, read COBOL USAGE clause, COBOL ARITH compiler option, COBOL TRUNC compiler option, COBOL fixed vs variable-length records, and COBOL performance tuning.
External references
IBM documents the SSRANGE compiler option, SSRANGE performance guidance, and the related MSG and ABD suboption APAR.
FAQ
What does SSRANGE do in COBOL?
SSRANGE generates runtime checks for out-of-range table references, indexes, subscripts, variable-length references, and reference modification expressions.
What is the default for SSRANGE?
IBM documents the default as NOSSRANGE.
Should SSRANGE be used in production?
Many sites use SSRANGE mainly in test because it adds runtime checks. Production use depends on the program risk, performance cost, and site standards.
Can CHECK(OFF) disable SSRANGE in COBOL 6?
No. IBM documents that COBOL 6 compiled-in SSRANGE checks are always conducted at run time.
