UNSTRING Statement COBOL

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

UNSTRING Statement

literal-1 and literal-2 must be nonnumeric literals and may be any figurative constant except those that begin with the word ALL.

identifier-1, identifier-2, identifier-3 and identifier-5 must reference data items described implicitly or explicitly as category alphanumeric.

identifier-1 must not be reference modified.

identifier-4 may be described as alphabetic, alphanumeric, or numeric (except that the symbol “P” may not be used in the PICTURE character-string), and must be described as usage is DISPLAY.

identifier-6, identifier-7 and identifier-8 must be described as elementary numeric integer data items (except that the symbol “P” may not be used in the PICTURE character-string).

The DELIMITER IN phrase and the COUNT IN phrase may be specified only if the DELIMITED BY phrase is specified.

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 they were only one occurrence, and one occurrence of literal-1 or the data item referenced by identifier-2 is moved to the receiving data item.

When the ALL phrase is not specified and any examination encounters two contiguous delimiters, the current receiving area is space filled if it is described as alphabetic or alphanumeric, or zero filled if it is described as numeric.

literal-1 or the contents of the data item referenced by identifier-2 can contain any character in the character set of the computer.

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 (or characters) in the sending field is considered to be a single delimiter. No character (or characters) 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. 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 characters, 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.
  4. If the DELIMITER IN phrase is specified, the delimiting character (or characters) are treated as an elementary alphanumeric data item, and are moved in to the data item referenced by identifier-5 according to the rules for the MOVE statement. If the delimiting condition is the end of the data item referenced by identifier-1, 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 characters, if there are 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 in the INTO phrase, the current receiving area is the data item referenced by the next recurrence of identifier-4. Steps 2 through 6 above are then repeated until 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 the responsibility of the user.

The contents of the data item referenced by identifier-7 are 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 completed, the contents of the data item referenced by identifier-7 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, 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 statement 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 the 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.

If an overflow condition arises, the UNSTRING operation is terminated, the NOT ON OVERFLOW phrase, if present, is ignored, and control is transferred either to the end of the UNSTRING statement, or, if the ON OVERFLOW phrase is present, to imperative-statement-1. In the latter case, execution continues according to the rules for each statement specified in imperative-statement-1. If a procedure branching or conditional statement that causes explicit transfer of control is encountered, 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.

If the UNSTRING operation completes without an overflow condition arising, the ON OVERFLOW phrase, if present, is ignored and control is transferred either to the end of the UN STRING statement, or, if the NOT ON OVERFLOW phrase is present, to imperative-statement-2.In the latter case, execution continues according to the rules for each statement specified in imperative-statement-2. If a procedure branching or conditional statement that causes explicit transfer of control is encountered, 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.

UNSTRING Statement Example


All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

COBOL Topics