action.skip

UNSTRING Statement

The UNSTRING statement separates parts of an existing string that share known delimiters into different data items.

General Format:

       UNSTRING identifier-1 
              [ DELIMITED BY [ALL] delimiter-1 
              [ OR [ALL] delimiter-2 ] ... ]
              INTO { identifier-2 [ DELIMITER in delimiter-2 ] 
              [ COUNT IN integer-data-1 ] } ... 
              [ WITH POINTER integer-data-2 ] 
              [ TALLYING IN integer-data-3 ] 
              [ ON OVERFLOW statement-1 ] 
              [ NOTON OVERFLOW statement-2 ] 
              [ END-UNSTRING ]

Syntax:

  1. identifier-n is a literal or data item that is not numeric.
  2. delimiter-n is an alphanumeric literal.
  3. integer-data-n is a numeric data item designed to hold an integer.
  4. statement-n is an imperative statement.

General Rules:

  1. There is no limit to the number of target identifiers that may be listed.
  2. The DELIMITED BY clause provides a way to identify a substring of an identifier-1, for purposes of the UNSTRING operation.
  3. The DELIMITED BY delimiter-1 clause causes the UNSTRING operation to stop copying data from identifier-1 when delimiter-1 is encountered. Delimiter-1 is not copied to the target-string.
  4. The COUNT phrase counts the number of characters in a substring.
  5. The WITH POINTER clause provides a way to set a position in the source string from which the UNSTRING statement will copy the selected source using a pointer-variable.
  6. The WITH POINTER clause causes an explicit pointer-variable to be referenced by the UNSTRING operation when it begins to copy data from a source 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.
  7. When the WITH POINTER clause is used, the pointer-variable must be set to a positive integer value before the UNSTRING statement is executed. Most commonly, the pointer-variable is initialized to 1, indicating that the UNSTRING statement should begin parsing the source string from the first byte.
  8. The pointer-variable is automatically incremented by 1 for each character that is parsed in the source string.
  9. If there is no WITH POINTER clause, the position at which the source string is copied into the next target-string is the first character, or, the next character position after the last delimiter character encountered in the original source string.
  10. The TALLY phrase counts the number of substrings that have been created by the UNSTRING statement.
  11. 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 length of the substring identified in the UNSTRING statement.
  12. When an ON OVERFLOW condition exists, the UNSTRING is terminated, and the ON OVERFLOW statement-1 is executed.
  13. The NOT ON OVERFLOW condition exists when the UNSTRING statement has completed, and the ON OVERFLOW condition does not exist.
  14. When a NOT ON OVERFLOW condition exists, statement-2 is executed.
  15. The ALL phrase indicates that a sequence of delimiters should be treated as a singled delimiter.

Code Sample:

       IDENTIFICATION DIVISION. 
       PROGRAM-ID. UNSTRING-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. 
       77 COUNTER-1  PIC 99 VALUE 0. 
       77 COUNTER-2  PIC 99 VALUE 0. 
       77 COUNTER-3  PIC 99 VALUE 0. 
       77 COUNTER-4  PIC 99 VALUE 0. 
       77 TALLY-1    PIC 99 VALUE 0. 
       01 DUMMY PIC X. 
       PROCEDURE DIVISION. 
       MAIN. 
              UNSTRING ADDRESS-1 DELIMITED BY "/" 
                     INTO ADDRESS-NUM, COUNT IN COUNTER-1, 
                            ADDRESS-NAME, COUNT IN COUNTER-2, 
                            ADDRESS-CITY, COUNT IN COUNTER-3, 
                            ADDRESS-COUNTRY, COUNT IN COUNTER-4 
                            TALLYING IN TALLY-1. 

              DISPLAY "THE STREET #: " LINE 4 COL 10. 
              DISPLAY ADDRESS-NUM LINE 4 COL 28. 
              DISPLAY COUNTER-1 LINE 4 COL 50. 
      * 
              DISPLAY "THE STREET NAME: " LINE 5 COL 10. 
              DISPLAY ADDRESS-NAME LINE 5 COL 28. 
              DISPLAY COUNTER-2 LINE 5 COL 50. 

              DISPLAY "THE CITY: " LINE 6 COL 10. 
              DISPLAY ADDRESS-CITY LINE 6 COL 28. 
              DISPLAY COUNTER-3 LINE 6 COL 50. 

              DISPLAY "THE COUNTRY: " LINE 7 COL 10. 
              DISPLAY ADDRESS-COUNTRY LINE 7 COL 28. 
              DISPLAY COUNTER-4 LINE 7 COL 50. 

              DISPLAY "TALLY: " LINE 9 COL 10. 
              DISPLAY TALLY-1 LINE 9 COL 28. 

              DISPLAY "UNSTRING-1 FINISHED!" LINE 12 COL 10. 

              ACCEPT DUMMY LINE 12 COL 30. 

              STOP RUN.