Referring to substrings of data items
Refer to a substring of a data
item that
has USAGE DISPLAY
, DISPLAY-1
, or NATIONAL
by
using a reference modifier. You can also refer to a
substring of an alphanumeric or national character string that is
returned by an intrinsic function by using a reference modifier.
USUBSTR
function
as described in Using intrinsic functions to process UTF-8 encoded data.The following
example shows how to use a reference modifier to refer to a twenty-character
substring of a data item called Customer-Record
:
Move Customer-Record(1:20) to Orig-Customer-Name
You code a reference modifier in parentheses immediately after the data item. As the example shows, a reference modifier can contain two values that are separated by a colon, in this order:
- Ordinal position (from the left) of the character that you want the substring to start with
- (Optional) Length of the required substring in character positions
The reference-modifier
position and length
for an item that has USAGE DISPLAY
are expressed
in terms of single-byte characters. The reference-modifier position
and length for items that have USAGE DISPLAY-1
or NATIONAL
are
expressed in terms of DBCS character positions and national character
positions, respectively.
If you omit the length in a reference modifier (coding only the ordinal position of the first character, followed by a colon), the substring extends to the end of the item. Omit the length where possible as a simpler and less error-prone coding technique.
You can refer
to substrings of USAGE DISPLAY
data items, including
alphanumeric groups, alphanumeric-edited data items, numeric-edited
data items, display floating-point data items, and zoned decimal data
items, by using reference modifiers. When you reference-modify any
of these data items, the result is of category alphanumeric. When
you reference-modify an alphabetic data item, the result is of category
alphabetic.
You can refer
to substrings of USAGE NATIONAL
data items, including
national groups, national-edited data items, numeric-edited data items,
national floating-point data items, and national decimal data items,
by using reference modifiers. When you reference-modify any of these
data items, the result is of category national. For example, suppose
that you define a national decimal data item as follows:
01 NATL-DEC-ITEM Usage National Pic 999 Value 123.
You can use NATL-DEC-ITEM
in
an arithmetic expression because NATL-DEC-ITEM
is
of category numeric. But you cannot use NATL-DEC-ITEM(2:1)
(the
national character 2
, which in hexadecimal notation
is NX"0032"
) in an arithmetic expression, because
it is of category national.
You can refer to substrings
of table entries, including variable-length entries, by using reference
modifiers. To refer to a substring of a table entry, code the subscript
expression before the reference modifier. For example, assume that PRODUCT-TABLE
is
a properly coded table of character strings. To move D
to
the fourth character in the second string in the table, you can code
this statement:
MOVE 'D' to PRODUCT-TABLE (2), (4:1)
You can code either or both of the two values in a reference modifier as a variable or as an arithmetic expression.
Example: arithmetic expressions as reference modifiers
Because numeric function identifiers can be used anywhere that arithmetic expressions can be used, you can code a numeric function identifier in a reference modifier as the leftmost character position or as the length, or both.
Example: intrinsic functions as reference modifiers
Each number in the reference modifier must have a value of at least 1. The sum of the two numbers must not exceed the total length of the data item by more than 1 character position so that you do not reference beyond the end of the substring.
If the leftmost character position or the length value is a fixed-point noninteger, truncation occurs to create an integer. If either is a floating-point noninteger, rounding occurs to create an integer.
The SSRANGE
compiler
option detects out-of-range reference modifiers, and flags violations
with a runtime message.
SSRANGE
Reference modification (Enterprise COBOL for z/OS® Language Reference)
Function definitions (Enterprise COBOL for z/OS Language Reference)