STRING statement

One STRING statement can be written instead of a series of MOVE statements.

Format

identifier-1, literal-1

Represents the sending fields.

DELIMITED BY phrase

Sets the limits of the string.

identifier-2, literal-2

Are delimiters; that is, characters that delimit the data to be transferred.

SIZE

Transfers the complete sending area.

INTO phrase

Identifies the receiving field.

identifier-3

Represents the receiving field.

POINTER phrase

Points to a character position in the receiving field. The pointer field indicates a relative alphanumeric character position, DBCS character position, or national character position when the receiving field is of usage DISPLAY, DISPLAY-1, or NATIONAL, respectively.

identifier-4

Represents the pointer field. identifier-4 must be large enough to contain a value equal to the length of the receiving field plus 1. You must initialize identifier-4 to a nonzero value before execution of the STRING statement begins.

When the POINTER phrase is specified, an explicit pointer field is available to control placement of data in the receiving field. It is required to set the explicit pointer's initial value, which must greater than or equal to 1. For fixed-length data items, the pointer's initial value must less than or equal to the character position count of the receiving field. For dynamic-length elementary items, the pointer's initial value must less than or equal to the specified value of the LIMIT phrase on the item's data description entry, or the default limit if no LIMIT is specified.

When the POINTER phrase is specified and the receiving field is a dynamic-length elementary item, the value of the POINTER field may be greater than the length of the receiver. When the value of the POINTER field is equal to the length of the receiver plus one, the STRING statement will effectively concatenate the sending fields to the receiver. When the value of the POINTER field is equal to the length of the receiver plus two, or more:

• For alphanumeric (PIC X) dynamic-length elementary item receivers, the intermediate character positions between the end of the receiver and the beginning of the POINTER field will be padded with spaces, and the sending fields will be concatenated starting at the POINTER field position as usual.
• For UTF-8 (PIC U) dynamic-length elementary item receivers, this is not allowed.

The following rules apply:

• All identifiers except identifier-4 must reference data items described explicitly or implicitly as usage DISPLAY, DISPLAY-1, NATIONAL, or UTF-8.
• All identifiers cannot be dynamic-length group items.
• literal-1 or literal-2 must be of category alphanumeric, DBCS, national, or UTF-8 and can be any figurative constant that does not begin with the word ALL (except NULL).
• If identifier-1 or identifer-2 references a data item of category numeric, each numeric item must be described as an integer without the symbol 'P' in its PICTURE character-string.
• identifier-3 must not reference a data item of category numeric-edited, alphanumeric-edited, or national-edited; an external floating-point data item of usage DISPLAY, or an external floating-point data item of usage NATIONAL.
• identifier-3 must not be described with the JUSTIFIED clause.
• If identifier-3 is of usage DISPLAY, identifier-1 and identifier-2 must be of usage DISPLAY and all literals must be alphanumeric literals. Any figurative constant can be specified except one that begins with the word ALL. Each figurative constant represents a 1-character alphanumeric literal.
• If identifier-3 is of usage DISPLAY-1, identifier-1 and identifier-2 must be of usage DISPLAY-1 and all literals must be DBCS literals. The only figurative constant that can be specified is SPACE, which represents a 1-character DBCS literal. ALL DBCS-literal must not be specified.
• If identifier-3 is of usage NATIONAL, identifier-1 and identifier-2 must be of usage NATIONAL and all literals must be national literals. Any figurative constant can be specified except symbolic-character and one that begins with the word ALL. Each figurative constant represents a 1-character national literal.
• If identifier-3 is of usage UTF-8, identifier-1 and identifier-2 must be of usage UTF-8 and all literals must be UTF-8 literals. Any figurative constant can be specified except symbolic-character and one that begins with the word ALL. Each figurative constant represents a 1-character UTF-8 literal.
• If identifier-1 or identifier-2 references an elementary data item of usage DISPLAY that is described as category numeric, numeric-edited, or alphanumeric-edited, the item is treated as if it were redefined as category alphanumeric.
• If identifier-1 or identifier-2 references an elementary data item of usage NATIONAL that is described as category numeric, numeric-edited, or national-edited item, the item is treated as if it were redefined as category national.
• identifier-4 must not be described with the symbol P in its PICTURE character-string.

Evaluation of subscripts, reference modification, variable-lengths, variable locations, and function-identifiers is performed only once, at the beginning of the execution of the STRING statement. Therefore, if identifier-3 or identifier-4 is used as a subscript, reference-modifier, or function argument in the STRING statement, or affects the length or location of any of the identifiers in the STRING statement, the values calculated for those subscripts, reference-modifiers, variable lengths, variable locations, and functions are not affected by any results of the STRING statement.

If identifier-3 and identifier-4 occupy the same storage area, undefined results will occur, even if the identifiers are defined by the same data description entry.

If identifier-1 or identifier-2 occupies the same storage area as identifier-3 or identifier-4, undefined results will occur, even if the identifiers are defined by the same data description entry.

Note: If a UTF-8 receiver is specified, the STRING statement might produce invalid UTF-8 byte sequences if the receiver contained 2-, 3-, or 4-byte encodings prior to STRING statement processing. To avoid this, initialize UTF-8 receivers with a single byte character encoding, such as SPACES.

See Data flow for details of STRING statement processing.