The UNSTRING statement causes contiguous data in a sending field to be separated
and placed into multiple receiving fields.
- 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:
- 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.
- 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.
- 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.)
- 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.
- 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 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.
- 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:
- 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.
- 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:
- 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.
- 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.
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.