Rational Developer for System z
Enterprise COBOL for z/OS, Version 4.1, Language Reference


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.

Read syntax diagramSkip visual syntax diagram
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-'   

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.

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.

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.

Data flow

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:

  • Characters from the sending fields are transferred to the receiving fields in the following manner:
    • For national sending fields, data is transferred using the rules of the MOVE statement for elementary national-to-national moves, except that no space filling takes place.
    • For DBCS sending fields, data is transferred using the rules of the MOVE statement for elementary DBCS-to-DBCS moves, except that no space filling takes place.
    • Otherwise, data is transferred to the receiving fields using the rules of the MOVE statement for elementary alphanumeric-to-alphanumeric moves, except that no space filling takes place (see MOVE statement).
  • When DELIMITED BY identifier-2 or literal-2 is specified, the contents of each sending item are transferred, character-by-character, beginning with the leftmost character position and continuing until either:
    • A delimiter for this sending field is reached (the delimiter itself is not transferred).
    • The rightmost character of this sending field has been transferred.
  • When DELIMITED BY SIZE is specified, each entire sending field is transferred to the receiving field.
  • When the receiving field is filled, or when all the sending fields have been processed, the operation is ended.
  • When the POINTER phrase is specified, an explicit pointer field is available to the COBOL user to control placement of data in the receiving field. The user must set the explicit pointer's initial value, which must not be less than 1 and not more than the character position count of the receiving field.

    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.

  • When the POINTER phrase is not specified, no pointer is available to the user. However, a conceptual implicit pointer with an initial value of 1 is used by the system.
  • Conceptually, when the STRING statement is executed, the initial pointer value (explicit or implicit) is the first character position within the receiving field into which data is to be transferred. Beginning at that position, data is then positioned, character-by-character, from left to right. After each character is positioned, the explicit or implicit pointer is increased by 1. The value in the pointer field is changed only in this manner. At the end of processing, the pointer value always indicates a value equal to one character position beyond the last character transferred into the receiving field.

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

This figure shows STRING statement processing.
Link to detail.


Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)