Micro Focus Studio Enterprise Edition Test Server > General Reference > COBOL Language Reference > Part 2. Program Definition > Procedure Division > Statements > The UNSTRING Statement

The UNSTRING Statement

The UNSTRING statement causes contiguous data in a sending field to be separated and placed into multiple receiving fields.

General Format

Syntax Rules

Each literal must be a nonnumeric literal. In addition, each literal can be any figurative constant without the optional word ALL.
Identifier-1, identifier-2, identifier-3, and identifier-5 must be described, implicitly or explicitly, as alphanumeric data items.
Identifier-4 can be described as either alphabetic (except that the symbol "B" cannot be used in the PICTURE character-string), alphanumeric, or numeric (except that the symbol "P" cannot be used in the PICTURE character-string), and must be described as USAGE IS DISPLAY.
Syntax Rules 2 and 3 do not apply. Instead, the following rules apply:
1. Identifier-1 must be alphanumeric
2. Identifier-2 and identifier-3 must be USAGE DISPLAY and must not be edited
3. Identifier-5 must be USAGE DISPLAY
4. Identifier-4 can be USAGE DISPLAY
5. Identifier-4 can have any USAGE that defines a numeric data item as long as the data results in a valid MOVE operation.
Identifier-4 must not be defined as a floating-point item.
Identifier-6 and identifier-8 must reference integer data items (except that the symbol " P" cannot be used in the PICTURE character-string).
Identifier-7 must be described as an elementary numeric integer data item of sufficient size to contain a value equal to 1 plus the size of the data item referenced by identifier-1. The symbol "P" cannot be used in the PICTURE character string of identifier-7.
No identifier can name a level 88 entry.
The DELIMITER IN phrase and the COUNT IN phrase can be specified only if the DELIMITED BY phrase is specified.
Identifier-1 must not be reference modified.
Identifier-1 can be reference modified.

General Rules

All references to identifier-2, literal-1, apply equally to identifier-3, literal-2, respectively and all recursions thereof.
Identifier-1 represents the sending area.
Identifier-4 represents the data receiving area. Identifier-5 represents the receiving area for delimiters.
Literal-1 or the data item referenced by identifier-2 specifies a delimiter.
The data item referenced by identifier-6 represents the count of the number of characters within the data item referenced by identifier-1 isolated by the delimiters for the move to the data item referenced by identifier-4. This value does not include a count of the delimiter character(s).
The data item referenced by identifier-7 contains a value that indicates a relative character position within the area defined by identifier-1.
The data item referenced by identifier-8 is a counter that records the number of data items acted upon during the execution of an UNSTRING statement.
When a figurative constant is used as the delimiter, it stands for a single character nonnumeric literal.
When the ALL phrase is specified, one occurrence or two or more contiguous occurrences of literal-1 (figurative constant or not) or the contents of the data item referenced by identifier-2 are treated as if it were only one occurrence, and this occurrence is moved to the receiving data item according to the rules in General Rule 13d.
When any examination encounters two contiguous delimiters, the current receiving area is either space- or zero-filled according to the description of the receiving area.
Literal-1 or the contents of the data item referenced by identifier-2 can contain any character in the computer's character set.
Each literal-1 or the data item referenced by identifier-2 represents one delimiter. 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.
When two or more delimiters are specified in the DELIMITED BY phrase, an "OR" condition exists between them. Each delimiter is compared to the sending field. If a match occurs, the character(s) in the sending field is considered to be a single delimiter. No character(s) in the sending field can be considered a part of more than one delimiter.
Each delimiter is applied to the sending field in the sequence specified in the UNSTRING statement.
When the UNSTRING statement is initiated, the current receiving area is the data item referenced by identifier-4. Data is transferred from the data item referenced by identifier-1 to the data item referenced by identifier-4 according to the following rules:
1. If the POINTER phrase is specified, the string of characters referenced by identifier-1 is examined beginning with the relative character position indicated by the contents of the data item referenced by identifier-7. If the POINTER phrase is not specified, the string of characters is examined beginning with the leftmost character position.
2. If the DELIMITED BY phrase is specified, the examination proceeds left to right until either a delimiter specified by the value of literal-1 or the data item referenced by identifier-2 is encountered. (See General Rule 11.) 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 the data item referenced by identifier-1 is encountered before the delimiting condition is met, the examination terminates with the last character examined.
3. The characters thus examined (excluding the delimiting character(s), if any) are treated as an elementary alphanumeric data item, and are moved into the current receiving area according to the rules for the MOVE statement. (See the section The MOVE Statement.)
4. If the DELIMITER IN phrase is specified, the delimiting character(s) are treated as an elementary alphanumeric data item and are moved into the data item referenced by identifier-5 according to the rules for the MOVE statement. (See the topic The MOVE Statement.) If the delimiting condition is the end of the data item referenced by identifier-1, then the data item referenced by identifier-5 is space-filled.
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.
6. If the DELIMITED BY phrase is specified, the string of characters is further examined beginning with the first character to the right of the delimiter. If the DELIMITED BY phrase is not specified, the string of characters is further examined beginning with the character to the right of the last character transferred.
7. After data is transferred to the data item referenced by identifier-4, the current receiving area is the data item referenced by the next recurrence of identifier-4. The behavior described in paragraphs 13b through 13f is repeated until either all the characters are exhausted in the data item referenced by identifier-1, or until there are no more receiving areas.
The initialization of the contents of the data items associated with the POINTER phrase or the TALLYING phrase is your responsibility.
The contents of the data item referenced by identifier-7 is incremented by one for each character examined in the data item referenced by identifier-1. When the execution of an UNSTRING statement with a POINTER phrase is complete, the data item referenced by identifier-7 contains 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, the contents of the data item referenced by identifier-8 contains a value equal to its initial value plus the number of data receiving items acted upon.
Either of the following situations causes an overflow condition:
1. 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.
2. During execution of an UNSTRING statement, all data 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,
the NOT ON OVERFLOW phrase, if specified, is ignored,

and control is transferred to the end of the UNSTRING 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 UNSTRING statement.
The END-UNSTRING phrase delimits the scope of the UNSTRING statement. (See the section Explicit and Implicit Scope Terminators in the chapter Concepts of the COBOL Language.)
If, at the time of execution of an UNSTRING statement, the conditions described in General Rule 17 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 UNSTRING 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 UNSTRING statement.
The evaluation of subscripting and indexing for the identifiers is as follows:
1. Any subscripting or indexing associated with identifier-1, identifier-7, or identifier-8 is evaluated only once, immediately before any data is transferred as the result of the execution of the UNSTRING statement.
2. Any subscripting or indexing associated with identifier-2, -3, -4, -5, or -6 is evaluated immediately before the transfer of data into the respective data item.
3. 22..Any subscripting associated with the DELIMITED BY identifier, the INTO identifier, the DELIMITER IN identifier, or the COUNT IN identifier is evaluated once, immediately before the examination of the sending fields for the delimiter.
If identifier-1, -2 or -3 occupies the same storage area as identifier-4, -5, -6, -7 or -8, or if identifier-4, -5 or -6 occupies the same storage area as identifier-7 or -8, or if identifier-7 and identifier-8 occupy the same storage area, the result of the execution of this statement is undefined, even if they are defined by the same data description entry.