UNSTRING statement

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

Format

Read syntax diagramSkip visual syntax diagramUNSTRINGidentifier-1DELIMITEDBYALLidentifier-2literal-1ORALLidentifier-3literal-2INTOidentifier-4DELIMITERINidentifier-5COUNTINidentifier-6WITHPOINTERidentifier-7TALLYINGINidentifier-8ONOVERFLOWimperative-statement-1NOTONOVERFLOWimperative-statement-2END-UNSTRING

identifier-1
Represents the sending field. Data is transferred from this field to the data receiving fields (identifier-4).

identifier-1 must reference a data item of category alphabetic, alphanumeric, alphanumeric-edited, DBCS, national, or national-edited.

identifier-2, literal-1, identifier-3, literal-2
Specifies one or more delimiters.

identifier-2 and identifier-3 must reference data items of category alphabetic, alphanumeric, alphanumeric-edited, DBCS, national, or national-edited.

literal-1 or literal-2 must be of category alphanumeric, DBCS, or national and must not be a figurative constant that begins with the word ALL.

identifier-4
Specifies one or more receiving fields.

identifier-4 must reference a data item of category alphabetic, alphanumeric, numeric, DBCS, or national. If the referenced data item is of category numeric, its picture character-string must not contain the picture symbol P, and its usage must be DISPLAY or NATIONAL.

identifier-5
Specifies a field to receive the delimiter associated with identifier-4.

Identifier-5 must reference a data item of category alphabetic, alphanumeric, DBCS, or national.

identifier-6
Specifies a field to hold the count of characters that are transferred to identifier-4.

identifier-6 must be an integer data item defined without the symbol P in its PICTURE character-string.

identifier-7
Specifies a field to hold a relative character position during UNSTRING processing.

identifier-7 must be an integer data item defined without the symbol P in the PICTURE string.

identifier-7 must be described as a data item of sufficient size to contain a value equal to 1 plus the number of character positions in the data item referenced by identifier-1.
identifier-8
Specifies a field that is incremented by the number of delimited fields processed.

identifier-8 must be an integer data item defined without the symbol P in its PICTURE character-string.

The following rules apply:

  • If identifier-4 references a data item of usage DISPLAY, identifier-1, identifier-2, identifier-3, and identifier-5 must also reference data items of usage DISPLAY and all literals must be alphanumeric literals. Any figurative constant can be specified except NULL or one that begins with the word ALL. Each figurative constant represents a 1-character alphanumeric literal.
  • If identifier-4 references a data item of usage DISPLAY-1, identifier-1, identifier-2, identifier-3, and identifier-5 must also reference data items of usage DISPLAY-1 and all literals must be DBCS literals. Figurative constant SPACE is the only figurative constant that can be specified. Each figurative constant represents a 1-character DBCS literal.
  • If identifier-4 references a data item of usage NATIONAL, identifier-1, identifier-2, identifier-3, and identifier-5 must also reference data items of usage NATIONAL and all literals must be national literals. Any figurative constant can be specified except NULL or one that begins with the word ALL. Each figurative constant represents a 1-character national literal.

Count fields (identifier-6) and pointer fields (identifier-7) are incremented by number of character positions (alphanumeric, DBCS, or national), not by number of bytes.

One UNSTRING statement can take the place of a series of MOVE statements, except that evaluation or calculation of certain elements is performed only once, at the beginning of the execution of the UNSTRING statement. For more information, see Values at the end of execution of the UNSTRING statement.

The rules for moving are the same as those for a MOVE statement for an elementary sending item of the category of identifier-1, with the appropriate identifier-4 as the receiving item (see MOVE statement). For example, rules for moving a DBCS item are used when identifier-1 is a DBCS item.

DELIMITED BY phrase

This phrase specifies delimiters within the data that control the data transfer.

Each identifier-2, identifier-3, literal-1, or literal-2 represents one delimiter.

If the DELIMITED BY phrase is not specified, the DELIMITER IN and COUNT IN phrases must not be specified.

ALL
Multiple contiguous occurrences of any delimiters are treated as if there were only one occurrence; this one occurrence is moved to the delimiter receiving field (identifier-5), if specified. The delimiting characters in the sending field are treated as an elementary item of the same usage and category as identifier-1 and are moved into the current delimiter receiving field according to the rules of the MOVE statement.

When DELIMITED BY ALL is not specified, and two or more contiguous occurrences of any delimiter are encountered, the current data receiving field (identifier-4) is filled with spaces or zeros, according to the description of the data receiving field.

Delimiter with two or more characters

A delimiter that contains two or more characters is recognized as a delimiter only if the delimiting characters are in both of the following cases:

  • Contiguous
  • In the sequence specified in the sending field
Two or more delimiters

When two or more delimiters are specified, an OR condition exists, and each nonoverlapping occurrence of any one of the delimiters is recognized in the sending field in the sequence specified.

For example:


DELIMITED BY "AB" or "BC"

An occurrence of either AB or BC in the sending field is considered a delimiter. An occurrence of ABC is considered an occurrence of AB.

INTO phrase

This phrase specifies the fields where the data is to be moved.

identifier-4 represents the data receiving fields.

DELIMITER IN
This phrase specifies the fields where the delimiters are to be moved.

identifier-5 represents the delimiter receiving fields.

The DELIMITER IN phrase must not be specified if the DELIMITED BY phrase is not specified.

COUNT IN
This phrase specifies the field where the count of examined character positions is held.

identifier-6 is the data count field for each data transfer. Each field holds the count of examined character positions in the sending field, terminated by the delimiters or the end of the sending field, for the move to this receiving field. The delimiters are not included in this count.

The COUNT IN phrase must not be specified if the DELIMITED BY phrase is not specified.

POINTER phrase

When the POINTER phrase is specified, the value of the pointer field, identifier-7, behaves as if it were increased by 1 for each examined character position in the sending field. When execution of the UNSTRING statement is completed, the pointer field contains a value equal to its initial value plus the number of character positions examined in the sending field.

When this phrase is specified, the user must initialize the pointer field before execution of the UNSTRING statement begins.

TALLYING IN phrase

When the TALLYING phrase is specified, the area count field, identifier-8, contains (at the end of execution of the UNSTRING statement) a value equal to the initial value plus the number of data receiving areas acted upon.

When this phrase is specified, the user must initialize the area count field before execution of the UNSTRING statement begins.

ON OVERFLOW phrases

An overflow condition exists when:

  • The pointer value (explicit or implicit) is less than 1.
  • The pointer value (explicit or implicit) exceeds a value equal to the length of the sending field.
  • All data receiving fields have been acted upon and the sending field still contains unexamined character positions.
When an overflow condition occurs

An overflow condition results in the following actions:

  1. No more data is transferred.
  2. The UNSTRING operation is terminated.
  3. The NOT ON OVERFLOW phrase, if specified, is ignored.
  4. Control is transferred to the end of the UNSTRING statement or, if the ON OVERFLOW phrase is specified, to imperative-statement-1.

imperative-statement-1
Statement or statements for dealing with an overflow condition.

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 that causes explicit transfer of control is executed, control is transferred according to 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.

When an overflow condition does not occur

When, during execution of an UNSTRING statement, conditions that would cause an overflow condition are not encountered, then:

  1. The transfer of data is completed.
  2. The ON OVERFLOW phrase, if specified, is ignored.
  3. Control is transferred to the end of the UNSTRING statement or, if the NOT ON OVERFLOW phrase is specified, to imperative-statement-2.
imperative-statement-2
Statement or statements for dealing with an overflow condition that does not occur.

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 that causes explicit transfer of control is executed, control is transferred according to 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.

Start of changeThe ON OVERFLOW phrase can be used for examining the sending field whereas the NOT ON OVERFLOW phrase is for normal execution when an overflow condition does not occur. You must include NOT ON OVERFLOW if you want to specify procedures to be executed only when an overflow condition does not occur. For example:
UNSTRING COLOR-LIST
   ...
   ON OVERFLOW
      DISPLAY 'Error: The string is too large'
   NOT ON OVERFLOW      *> Execute when the UNSTRING is successful
      PERFORM SORT-COLORS
END-UNSTRING
End of change

END-UNSTRING phrase

This explicit scope terminator serves to delimit the scope of the UNSTRING statement. END-UNSTRING permits a conditional UNSTRING statement to be nested in another conditional statement. END-UNSTRING can also be used with an imperative UNSTRING statement.

For more information, see Delimited scope statements.