action.skip

STRING Statement

The STRING statement concatenates separate literals and data items into a single data string.

General Format:

       STRING { {src-string-1} ... [DELIMITED BY {delimiter-1}] } ... 
                                                 {SIZE         } 
              INTO target-string-1 
              [ WITH POINTER pointer-variable-1 ] 
              [ ON OVERFLOW statement-1     ] 
              [ NOT ON OVERFLOW statement-2 ] 
              [ END-STRING ]

Syntax:

  1. Src-string-n is a alphanumeric data element, literal, or data returned from a function call.
  2. pointer-variable-n is a numeric data element with a positive integer value.
  3. delimiter-n is a character string.
  4. target-string-1 is an alphanumeric data item.
  5. statement-n is an imperative statement.

General Rules:

  1. The STRING statement concatenates consecutive src-string-n, and stores the result in the targe-string data item that follows the INTO phrase.
  2. There is no limit to the number of src-string-n identifiers that may be listed.
  3. The DELIMITED BY clause provides a way to identify a substring of a src-identifier, for purposes of the STRING operation.
  4. The DELIMITED BY delimiter-1 clause causes the STRING operation to stop copying data from the src-string when the delimiter-1 is encountered in the src-string. Delimiter-1 is not copied to the target string.
  5. The DELIMITED BY SIZE clause causes the entire src-string to be copied into the target string.
  6. If there is no DELIMITED BY phrase, then DELIMITED BY SIZE is assumed.
  7. The WITH POINTER clause provides a way to set a position in the target-string where the STRING statement will copy the selected source using a pointer-variable.
  8. The WITH POINTER clause causes an explicit pointer-variable to be referenced by the STRING operation when it begins to copy data from a src-string to a target-string. The value of the pointer-variable is used as the position in the target-string at which to copy the data.
  9. When the WITH POINTER clause is used, pointer-variable-n must be set to a positive integer value before the STRING statement is executed. Most commonly, the pointer-variable is initialized to 1, indicating that the STRING statement should begin copying into the target-string at the first byte of the target-string.
  10. The pointer-variable is automatically incremented by 1 for each character that is copied into the target-string.
  11. If there is no WITH POINTER clause, the position at which the src-string is copied into the target-string is the next character position after the last character position occupied by the previous src-string.
  12. The ON OVERFLOW condition is triggered when the pointer-variable does not contain a positive value, or when the length of target-string is less than the combined length of the src-strings named in the STRING statement.
  13. When an ON OVERFLOW condition exists, the STRING is terminated, and the ON OVERFLOW statement-1 is executed.
  14. The NOT ON OVERFLOW condition exists when the STRING statement has completed, an the ON OVERFLOW condition does not exist.
  15. When a NOT ON OVERFLOW condition exists, statement-2 is executed.

Code Sample:

       IDENTIFICATION DIVISION. 
       PROGRAM-ID. STRING-1. 
       ENVIRONMENT DIVISION. 
       DATA DIVISION. 
       WORKING-STORAGE SECTION. 
       01 ADDRESS-1 
              PIC X(40) VALUE"231/RUE SAINT-HONORE/75001 PARIS/FRANCE". 
       01 ADDRESS-2. 
              05 ADDRESS-NUM       PIC X(5)      VALUE SPACES. 
              05 ADDRESS-NAME      PIC X(20)     VALUE SPACES. 
              05 ADDRESS-CITY      PIC X(20)     VALUE SPACES. 
              05 ADDRESS-COUNTRY   PIC X(20)     VALUE SPACES. 
       01 ADDRESS-3         PIC X(60)            VALUE SPACES. 
       01 DUMMY PIC X. 
       PROCEDURE DIVISION. 
       MAIN. 
              UNSTRING ADDRESS-1 DELIMITED BY "/" 
                     INTO   ADDRESS-NUM 
                            ADDRESS-NAME 
                            ADDRESS-CITY 
                            ADDRESS-COUNTRY. 

              DISPLAY "THE STREET #:      " ADDRESS-NUM LINE 4 COL 10. 
              DISPLAY "THE STREET NAME:   " ADDRESS-NAME LINE 5 COL 10. 
              DISPLAY "THE CITY:          " ADDRESS-CITY LINE 6 COL 10. 
              DISPLAY "THE COUNTRY:       " ADDRESS-COUNTRY LINE 7 COL 10. 

              ACCEPT DUMMY LINE 7 COL 33. 
              STRING ADDRESS-NUM          DELIMITED BY " " 
                            " "           DELIMITED BY SIZE 
                     ADDRESS-NAME         DELIMITED BY " " 
                            ", "          DELIMITED BY SIZE 
                     ADDRESS-CITY         DELIMITED BY " " 
                            ", "          DELIMITED BY SIZE 
                     ADDRESS-COUNTRY DELIMITED BY SIZE INTO ADDRESS-3 
              ON OVERFLOW 
                     DISPLAY "STRING FAILED ON OVERFLOW" LINE 10 COL 10 
              NOT ON OVERFLOW DISPLAY "THE ADDRESS IS " ADDRESS-3 LINE 10 COL 10 
       END-STRING. 

       DISPLAY "STRING-1 FINISHED!" LINE 12 COL 10. 
       ACCEPT DUMMY LINE 12 COL 30. 
       STOP RUN.