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.
Format >>-STRING-------------------------------------------------------> .-----------------------------------------------------------. | .------------------. | V V | | >------+-identifier-1-+-+--DELIMITED--+----+--+-identifier-2-+-+--> '-literal-1----' '-BY-' +-literal-2----+ '-SIZE---------' >--INTO--identifier-3--+---------------------------------+------> '-+------+--POINTER--identifier-4-' '-WITH-' >--+------------------------------------------+-----------------> '-+----+--OVERFLOW--imperative-statement-1-' '-ON-' >--+-----------------------------------------------+------------> '-NOT--+----+--OVERFLOW--imperative-statement-2-' '-ON-' >--+------------+---------------------------------------------->< '-END-STRING-'
The following rules apply:
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 below for details of STRING statement processing.
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.
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.
When the STRING statement is executed, characters are transferred from the sending fields to the receiving field. The order in which sending fields are processed is the order in which they are specified. The following rules apply:
Usage note: The pointer field must be defined as a field large enough to contain a value equal to the length of the receiving field plus 1; this precludes arithmetic overflow when the system updates the pointer at the end of the transfer.
After STRING statement execution is completed, only that part of the receiving field into which data was transferred is changed. The rest of the receiving field contains the data that was present before this execution of the STRING statement.
When the following STRING statement is executed, the results obtained will be like those illustrated in the figure after the statement.
STRING ID-1 ID-2 DELIMITED BY ID-3
ID-4 ID-5 DELIMITED BY SIZE
INTO ID-7 WITH POINTER ID-8
END-STRING
