STRING statement

Function

The STRING statement moves and juxtaposes the partial or complete contents of two or more data items into a single data item.

Format

---

STRING {{identifier-1 | literal-1}... [DELIMITED BY {identifier-2 | literal-2 | SIZE}]}...

INTO identifier-3 [WITH POINTER identifier-4]

[ON OVERFLOW imperative-statement-1]

[NOT ON OVERFLOW imperative-statement-2]

[END-STRING]

---

Syntax rules

1. Each literal may be any figurative constant, but it may not begin with ALL.

2. All literals must be described as non-numeric literals, and all identifiers, except identifier-4, must be described implicitly or explicitly as USAGE DISPLAY or USAGE NATIONAL. If the class of literal-1, literal-2, identifier-1, identifier-2 or identifier-3 is national, the class of all must be national.

3. Where identifier-1... are elementary numeric data items, they must be described as integers without the symbol P in their PICTURE character-strings.

4. If DELIMITED BY is not explicitly specified, DELIMITED BY SIZE is applied.

5. identifier-1..., literal-1... represent the sending items; identifier-3 represents the receiving item.

6. identifier-3 must not represent an edited data item and must not be described with the JUSTIFIED clause. identifier-3 must not represent a strongly typed data item.

7. identifier-4 is a counter item and must be described as an elementary numeric integer data item of sufficient size to accommodate the size of the data item referenced by identifier-3 plus the value 1.
   The symbol P is prohibited in the PICTURE character-string of identifier-4.

8. identifier-3 must not be subjected to reference modification.

General rules

1. identifier-2, literal-2 represent delimiters, i.e. they mark a character string up to which the contents of a sending item should be moved. If the SIZE phrase is used, the contents of the complete data item defined by identifier-1, literal-1 are moved.

2. If a figurative constant is specified as literal-1 or literal-2, it is regarded as a data item with the length 1 with the same USAGE as identifier-3.

3. When the STRING statement is executed, the transfer of data is governed by the following rules:

   1. The sending items literal-1 or the contents of identifier-1 are transferred to the receiving item referenced by identifier-3. The rules for the MOVE statement from national to national apply here if identifier-3 is of the national class, otherwise from alphanumeric to alphanumeric. In both cases no space filling will be provided. If identifier-1 is a zero-length item, it will not be moved.

   2. If the DELIMITED BY phrase is specified without the SIZE phrase, the content of identifier-1... or the value of literal-1 is transferred character-by-character to the receiving data item, beginning with the leftmost character and continuing from left to right until the end of the sending data item is reached or until the character(s) specified by the delimiter referenced by literal-2, or the contents of identifier-2, are encountered. The delimiter is not transferred.

   3. If the DELIMITED BY phrase is specified with the SIZE phrase or identifier-2 is a zero-length item, the entire contents of the sending items referenced by literal-1 or identifier-1 are transferred to the receiving item referenced by identifier-3 until all data has been transferred or the end of identifier-3 has been reached. The transfer takes place in the sequence specified in the STRING statement.

4. If the POINTER phrase is specified, the counter item referenced by identifier-4 is explicitly available to the user, i.e. an initial value greater than 0, and of adequate size to contain a value of the length of identifier-3 plus one byte, must be set by the user.

5. The subscripts of an identifier in the POINTER phrase are evaluated before the STRING statement is executed.

6. If the POINTER phrase is not specified, the following general rules apply as if the user had specified identifier-4 referencing a data item with an initial value of 1.

7. When moved to the receiving item identifier-3, each character is transferred separately from the sending item to the character position of identifier-3 which is determined by the value of the counter item identifier-4. Each time a character is moved, identifier-4 is incremented by 1. This is the only manner in which the value of identifier-4 changes during execution of the STRING statement.

8. At the end of execution of the STRING statement, only the portion of the receiving item referenced by identifier-3 into which characters were moved is changed. The rest of identifier-3 remains the same.

9. If at any time during or after the initialization of the STRING statement, but before processing is completed, the value associated with the counter item referenced by identifier-4 is either less than one or exceeds the number of character positions in the receiving item referenced by identifier-3, no (further) data is transferred to identifier-3, and the imperative statement in the ON OVERFLOW phrase, if specified, is executed.

10. If the ON OVERFLOW phrase is not specified when one of the conditions described above is encountered, control is transferred to the end of the STRING statement.

11. The imperative statement in the NOT ON OVERFLOW phrase is executed if the STRING statement ends without one of the conditions described above having been encountered.

Example 8-77

IDENTIFICATION DIVISION.
PROGRAM-ID. STRNG.
ENVIRONMENT DIVISION.
     CONFIGURATION SECTION.
     SPECIAL-NAMES.
         TERMINAL IS T.
DATA DIVISION.
WORKING-STORAGE SECTION. 
77  FIELD1   PIC X(16)  VALUE "ANFANGSBEDINGUNG".
77  FIELD2   PIC X(12)  VALUE "WERTEBEREICH".
77  FIELD3   PIC X(25)  VALUE SPACES.
77  FIELD4   PIC 99     VALUE 3.
PROCEDURE DIVISION.
PROC SECTION.
MAIN.
    DISPLAY "Before STRING: " UPON T.
    PERFORM DISPLAY-FIELDS.
    STRING FIELD1, FIELD2 DELIMITED BY "B",
           " INVALID" DELIMITED BY SIZE
      INTO FIELD3 WITH POINTER FIELD4
    ON OVERFLOW
      DISPLAY "Error" UPON T
    END-STRING
    DISPLAY "After STRING" UPON T.
    PERFORM DISPLAY-FIELDS.
    STOP RUN.
DISPLAY-FIELDS.
    DISPLAY "Field1 = *" FIELD1 "*" UPON T.
    DISPLAY "Field2 = *" FIELD2 "*" UPON T.
    DISPLAY "Field3 = *" FIELD3 "*" UPON T.
    DISPLAY "Field4 = *" FIELD4 "*" UPON T. 

Result:

Before STRING	After STRING
FIELD1 = *ANFANGSBEDINGUNG*	FIELD1 = *ANFANGSBEDINGUNG*
FIELD2 = *WERTEBEREICH*	FIELD2 = *WERTEBEREICH*
FIELD3 = *                         *	FIELD3 = *  ANFANGSWERTE SETZEN    *
FIELD4 = *03*	FIELD4 = *22*