The UNSTRING statement causes contiguous data in a sending field to be separated and placed into multiple receiving fields.
Format >>-UNSTRING--identifier-1---------------------------------------> >--+-------------------------------------------------------------------------------------+--> '-DELIMITED--+----+--+-----+--+-identifier-2-+--+-----------------------------------+-' '-BY-' '-ALL-' '-literal-1----' | .-------------------------------. | | V | | '---OR--+-----+--+-identifier-3-+-+-' '-ALL-' '-literal-2----' >--INTO---------------------------------------------------------> .------------------------------------------------------------------------------------. V | >----identifier-4--+---------------------------------+--+-----------------------------+-+--> '-DELIMITER--+----+--identifier-5-' '-COUNT--+----+--identifier-6-' '-IN-' '-IN-' >--+---------------------------------+--------------------------> '-+------+--POINTER--identifier-7-' '-WITH-' >--+--------------------------------+---------------------------> '-TALLYING--+----+--identifier-8-' '-IN-' >--+------------------------------------------+-----------------> '-+----+--OVERFLOW--imperative-statement-1-' '-ON-' >--+-----------------------------------------------+------------> '-NOT--+----+--OVERFLOW--imperative-statement-2-' '-ON-' >--+--------------+-------------------------------------------->< '-END-UNSTRING-'
identifier-1 must reference a data item of category alphabetic, alphanumeric, alphanumeric-edited, DBCS, national, or national-edited.
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 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 must reference a data item of category alphabetic, alphanumeric, DBCS, or national.
identifier-6 must be an integer data item defined without the symbol P in its PICTURE character-string.
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 must be an integer data item defined without the symbol P in its PICTURE character-string.
The following rules apply
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.
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.
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.
A delimiter that contains two or more characters is recognized as a delimiter only if the delimiting characters are both of the following:
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.
This phrase specifies the fields where the data is to be moved.
identifier-4 represents the data receiving fields.
identifier-5 represents the delimiter receiving fields.
The DELIMITER IN phrase must not be specified if the DELIMITED BY phrase is not specified.
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.
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.
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.
An overflow condition exists when:
An overflow condition results in the following actions:
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, during execution of an UNSTRING statement, conditions that would cause an overflow condition are not encountered, then:
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.
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.
When the UNSTRING statement is initiated, data is transferred from the sending field to the current data receiving field, according to the following rules:
Stage 1: Examine
If the POINTER phrase is not specified, the sending field character-string is examined, beginning with the leftmost character position.
If the DELIMITED BY phrase is not specified, the number of character positions examined is equal to the size of the current data receiving field, as described in the table below. The size depends on the category treatment of the receiving field, as shown in Table 1.
| If the receiving field is ... | The number of character positions examined is ... |
|---|---|
| Alphanumeric or alphabetic | Equal to the number of alphanumeric character positions in the current receiving field |
| DBCS | Equal to the number of DBCS character positions in the current receiving field |
| National | Equal to the number of national character positions in the current receiving field |
| Numeric | Equal to the number of character positions in the integer portion of the current receiving field |
| Described with the SIGN IS SEPARATE clause | 1 less than the size of the current receiving field |
| Described as a variable-length data item | Determined by the size of the current receiving field at the beginning of the UNSTRING operation |
Stage 2: Move
| Category of identifier-1 (sending-field) | Category of elementary data item |
|---|---|
| Alphanumeric-edited | Alphanumeric |
| National-edited | National |
Stage 3: Successive iterations
If the DELIMITED BY phrase is not specified, the sending field is further examined, beginning with the first character position to the right of the last character position examined.
The following operations are performed only once, at the beginning of the execution of the UNSTRING statement:
Therefore, if identifier-4, identifier-5, identifier-6, identifier-7, or identifier-8 is used as a subscript, reference-modifier, or function argument in the UNSTRING statement, or affects the length or location of any of the identifiers in the UNSTRING statement, these values are determined at the beginning of the UNSTRING statement, and are not affected by any results of the UNSTRING statement.