Function
The UNSTRING statement causes contiguous data in a sending item to be separated and placed into multiple receiving items.
Format
UNSTRING identifier-1
[DELIMITED BY [ALL] {identifier-1 | literal-1} [OR [ALL] {identifier-3 | literal-2}]...]
INTO {identifier-4 [DELIMITER IN identifier-5] [COUNT IN identifier-6]}...
[WITH POINTER identifier-7] [TALLYING IN identifier-8]
[ON OVERFLOW imperative-statement-1]
[NOT ON OVERFLOW imperative-statement-2]
[END-UNSTRING]
Syntax rules
literal-1 and literal-2 must be literals of the category alphanumeric or national. However, they may not be figurative constants which begin with ALL.
identifier-1, identifier-2, identifier-3, identifier-5 must reference data items described as alphanumeric or national.
If the category of any literal-1, literal-2, identifier-1, identifier-2, ..., identifier-5 is national, the category of all must be national.
identifier-4 may be described as either
the category national
the category alphabetic, alphanumeric or numeric. It must be described, implicitly or explicitly, as USAGE DISPLAY. A numeric data item must not be contain the character "P" in the PICTURE character-string.
identifier-6, identifier-7, identifier-8 must reference integer data items.The character "P" must not be used in the PICTURE character-string.
identifier-1 represents the sending area.
identifier-4 represents the receiving area, identifier-5 the receiving area for delimiters.
identifier-1 must not be subjected to reference modification.
DELIMITER IN and COUNT IN can be used only in conjunction with DELIMITED BY.
No identifier may be defined with the level number 88.
General rules
All references to identifier-2 and literal-1apply to identifier-3 and literal-2 and analogously to all recursions thereof.
If identifier-1 is a zero-length item:
The content of the identifier-4 to identifier-8 remain unchanged.
Neither imperative-statement-1 nor imperative-statement-2 is executed.
The runtime control passes immediately to the end of the UNSTRING statement.
If a figurative constant is specified as literal-1, it stands for a 1-character long national data item if identifier-1 is a national data item, otherwise for a 1-character long alphanumeric data item.
When the ALL phrase is specified, contiguous occurrences of literal-1 or identifier-2 are treated as if they were only one occurrence, and one occurrence of literal-1 or identifier-2 is moved to the data item referenced by identifier-5.
When two contiguous delimiters are encountered, the current receiving area is spacefilled if it is described as alphabetic, alphanumeric or national, or zero-filled if it is described as numeric.
literal-1, identifier-2 represent delimiters. When a delimiter contains two or more characters, all of the characters must be present in contiguous positions of the sending item, and in the order given, to be recognized as a delimiter.
If identifier-2 is a zero-length item, it is not recognized as a delimiter.When two or more delimiters are specified in the DELIMITED BY phrase, an OR condition exists between them. Each delimiter is compared with the sending item. If a match occurs, the character(s) in the sending item is (are) considered to be a single delimiter. No character(s) in the sending item can be considered as part of more than one delimiter. Delimiters cannot overlap.
Each delimiter is applied to the sending item in the sequence specified in the UNSTRING statement.When the UNSTRING statement is initiated, identifier-4 represents the current receiving area. Data is transferred from identifier-1 to identifier-4 according to the following rules:
If the POINTER phrase is specified, the string of characters referenced by identifier-1 is examined beginning with the relative character position indicated by identifier-7.
If the POINTER phrase is not specified, the string of characters is examined beginning with the leftmost character position of identifier-1.If the DELIMITED BY phrase is specified, the examination proceeds left to right until either a delimiter specified by literal-1 or the value of the data item referenced by identifier-2 is encountered.
If the DELIMITED BY phrase is not specified, the number of characters examined is equal to the size of the current receiving area. However, if the sign of the receiving item is defined as occupying a separate character position, the number of characters examined is one less than the size of the current receiving area. If the end of identifier-1 is reached before a delimiter is encountered, the examination terminates with the character examined last.The characters thus examined (excluding the delimiting character(s), if any) are treated as an elementary national data item if identifier-1 is ntional. In all the other cases this characters are treated as an elementary alphanumeric data item.The characters are moved into the current receiving area according to the rules for the MOVE statement (see section "MOVE statement"), but a decimal point is ignored.
If the DELIMITER IN phrase is specified, the delimiting character(s) are treated as an elementary national data item if identifier-1 is ntional. In all the other cases this characters are treated as an elementary alphanumeric data item.
The characters are moved into the current receiving area according to the rules for the MOVE statement (see section "MOVE statement").
If the end of identifier-1 was reached without finding a delimiter, blanks are moved to identifier-5.If the COUNT IN phrase is specified, a value equal to the number of characters thus examined (excluding the delimiter character(s), if any) is moved into the area referenced by identifier-6 according to the rules for an elementary move.
If the DELIMITED BY phrase is specified, the string of characters referenced by identifier-1 is further examined beginning with the first character to the right of the delimiter.
If the DELIMITED BY phrase is not specified, the examination will continue from the character immediately following the last character to be moved.After the data is transferred to identifier-4, the current receiving area is represented by the next recurrence of identifier-4.
The behavior described above is repeated until either all the characters in identifier-1 are exhausted or until there are no more receiving areas.
The initialization of the contents of the data items associated with the POINTER or TALLYING phrase is the responsibility of the user.
The contents of the data item referenced by identifier-7 will be incremented by 1 for each character examined in the data item referenced by identifier-1.
When the execution of an UNSTRING statement with a POINTER phrase is completed, identifier-7 will contain a value equal to the initial value plus the number of characters examined in the data item referenced by identifier-1.
When the execution of an UNSTRING statement with a TALLYING phrase is completed, identifier-8 contains a value equal to its initial value plus the number of receiving data items accessed.
Either of the following situations causes an overflow condition:
If an UNSTRING is initiated, and the value in the data item referenced by identifier-7 is less than 1 or greater than the size of the data item referenced by identifier-1.
If, during execution of an UNSTRING statement, all receiving areas have been acted upon, and the data item referenced by identifier-1 contains characters that have not been examined.
When an OVERFLOW condition exists, the UNSTRING operation is terminated. If an ON OVERFLOW phrase has been specified, the imperative statement given in this phrase is executed. If the ON OVERFLOW phrase is not specified, control is transferred to the next statement to be executed.
The imperative statement specified in the NOT ON OVERFLOW phrase is executed if the UNSTRING statement is terminated and none of the conditions described above has been encountered.
Subscripts and indexes for the identifiers are analyzed as follows:
If the items identifier-1, identifier-7, identifier-8 are subscripted or indexed, the index value for these items is calculated once only, immediately before the UNSTRING statement is executed.
Any subscripting of identifiers in the DELIMITED BY, INTO, DELIMITER IN, and COUNT phrases is evaluated immediately before the data is transferred to the respective data item.
Example 8-81
IDENTIFICATION DIVISION.
PROGRAM-ID. UNSTRING.
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
TERMINAL IS T.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 FIELD PIC X(12) VALUE "ABCDEFGHIJKL".
01 AREA1.
02 PART1 PIC X VALUE SPACES.
02 PART2 PIC XX VALUE SPACES.
02 PART3 PIC XXX VALUE SPACES.
01 NUMB PIC 99 VALUE ZERO.
PROCEDURE DIVISION.
PROC SECTION.
MAIN.
DISPLAY "Before UNSTRING" UPON T.
PERFORM DISPLAY-FIELDS.
*
UNSTRING FIELD DELIMITED BY "E" OR "H" OR "K" OR "L"
INTO PART3, PART2, PART1
TALLYING IN NUMB.
END-UNSTRING
*
DISPLAY "After UNSTRING" UPON T.
PERFORM DISPLAY-FIELDS.
STOP RUN.
DISPLAY-FIELDS.
DISPLAY "Field = *" FIELD "*" UPON T.
DISPLAY "Part1 = *" PART1 "*" UPON T.
DISPLAY "Part2 = *" PART2 "*" UPON T.
DISPLAY "Part3 = *" PART3 "*" UPON T.
DISPLAY "Numb = *" NUMB "*" UPON T.
Result:
Before UNSTRING | After UNSTRING |
FIELD = | FIELD = |
PART1 = | PART1 = |
PART2 = | PART2 = |
PART3 = | PART3 = |
NUMB = | NUMB = |