STRING statement
The STRING statement strings together the partial or complete contents of two or more data items or literals into one single data item.
One STRING statement can be written instead of a series of MOVE statements.
- 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, 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.
The following rules apply:
- All identifiers except identifier-4 must reference data items described explicitly or implicitly as usage DISPLAY, DISPLAY-1, or NATIONAL.
- All identifiers cannot be dynamic-length group items.
- literal-1 or literal-2 must be of category alphanumeric, DBCS, or national 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-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.
See Data flow for details of STRING statement processing.
ON OVERFLOW phrases
- imperative-statement-1
- Executed when the pointer value (explicit or implicit):
- Is less than 1
- Exceeds a value equal to the length of the receiving field
When either of the above conditions occurs, an overflow condition exists, and no more data is transferred. Then the STRING operation is terminated, the NOT ON OVERFLOW phrase, if specified, is ignored, and control is transferred to the end of the STRING statement or, if the ON OVERFLOW phrase is specified, to imperative-statement-1.
If control is transferred to imperative-statement-1, execution continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement that causes explicit transfer of control is executed, control is transferred according to the rules for that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the STRING statement.
If at the time of execution of a STRING statement, conditions that would cause an overflow condition are not encountered, then after completion of the transfer of data, the ON OVERFLOW phrase, if specified, is ignored. Control is then transferred to the end of the STRING statement, or if the NOT ON OVERFLOW phrase is specified, to imperative-statement-2.
If control is transferred to imperative-statement-2, execution continues according to the rules for each statement specified in imperative-statement-2. If a procedure branching or conditional statement that causes explicit transfer of control is executed, control is transferred according to the rules for that statement. Otherwise, upon completion of the execution of imperative-statement-2, control is transferred to the end of the STRING statement.
END-STRING phrase
This explicit scope terminator serves to delimit the scope of the STRING statement. END-STRING permits a conditional STRING statement to be nested in another conditional statement. END-STRING can also be used with an imperative STRING statement.
For more information, see Delimited scope statements.