The STRING Statement

The STRING statement provides concatenation of the partial or complete contents of two or more data items into a single data item.

General Format

STRING Statement

Syntax Rules

  1. Each literal can be any figurative constant without the optional word ALL.
  2. All literals must be described as nonnumeric literals, and all identifiers, except identifier-4, must be described implicitly or explicitly as USAGE IS DISPLAY.
  3. ENTMF  Identifier-1 ... Identifier-3 may also be USAGE NATIONAL or UTF-8, as long as all three match.
  4. Identifier-2 cannot be a dynamic-length item.
  5. Identifier-3 must represent an elementary alphanumeric data item without editing symbols or the JUSTIFIED clause.
  6. Identifier-4 must represent an elementary numeric integer data item of sufficient size to contain a value equal to the size plus 1 of the area referenced by identifier-3. The symbol "P" cannot be used in the PICTURE character-string of identifier-4.
  7. Where identifier-1 or identifier-2 is an elementary numeric data item, it must be described as an integer without the symbol "P" in its PICTURE character-string.
  8. ANS85 Identifier-3 must not be reference modified.
  9. MFOS390 Identifier-3 can be reference modified.

General Rules

  1. Identifier-1, or literal-1, represents the sending item. Identifier-3 represents the receiving item.
  2. Literal-2, identifier-2, indicate the character(s) delimiting the move. If the SIZE phrase is used, the complete data item defined by identifier-1, or literal-1, is moved. When a figurative constant is used as the delimiter, it stands for a single-character nonnumeric literal.
  3. When a figurative constant is specified as literal-1, or literal-2, it refers to an implicit one-character data item whose usage is DISPLAY.
  4. When the STRING statement is executed, the transfer of data is governed by the following rules:
    1. Those characters from literal-1, or from the contents of the data item referenced by identifier-1, are transferred to the contents of identifier-3 in accordance with the rules for alphanumeric to alphanumeric moves, except that no space filling is provided. (See the topic The MOVE Statement.)
    2. If the DELIMITED phrase is specified without the SIZE phrase, the contents of the data item referenced by identifier-1, or the value of literal-1, is transferred to the receiving data item in the sequence specified in the STRING statement beginning with the leftmost character and continuing from left to right until the end of the data item is reached, or until the character(s) specified by literal-2, or by the contents of identifier-2 are encountered. The character(s) specified by literal-2, or by the data item referenced by identifier-2, are not transferred.
    3. If the DELIMITED phrase is specified with the SIZE phrase, the entire contents of literal-1, or the contents of the data item referenced by identifier-1, are transferred, in the sequence specified in the STRING statement, to the data item referenced by identifier-3 until all data has been transferred or the end of the data item referenced by identifier-3 has been reached.
  5. If the POINTER phrase is specified, identifier-4 is explicitly available to you, and you are then responsible for setting its initial value. The initial value must not be less than one.
  6. ENTMF  For fixed-length data items, initial value of the pointer must less than or equal to the character position count of the receiving field. For dynamic-length elementary items, the initial value of the pointer must less than or equal to the LIMIT phrase's specified value on the item's data description entry, or if no LIMIT is specified, the default limit.
  7. ENTMF  When the POINTER phrase is specified and the receiving field is a dynamic-length elementary item, the POINTER field value can be greater than the length of the receiver. If the POINTER field value 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 are padded with spaces.
  8. If the POINTER phrase is not specified, the following General Rules apply as if you had specified identifier-4 with an initial value of 1.
  9. When characters are transferred to the data item referenced by identifier-3, the moves behave as though the characters were moved one at a time from the source into the character position of the data item referenced by identifier-3 designated by the value associated with identifier-4, and then identifier-4 was increased by one prior to the move of the next character. The value associated with identifier-4 is changed during execution of the STRING statement only by the behavior specified above.
  10. At the end of execution of the STRING statement, only the portion of the data item referenced by identifier-3 that was referenced during the execution of the STRING statement is changed. All other portions of the data item referenced by identifier-3 contains data that was present before this execution of the STRING statement.
  11. Before each move of a character to the data item referenced by identifier-3, if the value associated with the data item referenced by identifier-4 is either less than one or exceeds the number of character positions in the data item referenced by identifier-3, no (further) data is transferred to the data item referenced by identifier-3,

    ANS85 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 which causes explicit transfer of control is executed, control is transferred in accordance with 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.

  12. ANS85 If, at the time of execution of a STRING statement with the NOT ON OVERFLOW phrase, the conditions described in General Rule 9 are not encountered, after completion of the transfer of data according to the other general rules, the ON OVERFLOW phrase, if specified, is ignored and control is 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 which causes explicit transfer of control is executed, control is transferred in accordance with 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.
  13. ANS85 The END-STRING phrase delimits the scope of the STRING statement.
  14. ENTMF No identifiers in the STRING statement must be dynamic-length group items.
Parent topic: Statements
Related concepts
Explicit and Implicit Scope Terminators