ILE COBOL Language Reference
When the UNSTRING statement is initiated, data is transferred from the
sending field to the current data receiving field, according to the following
rules (the current data receiving field is identifier-4):
- If the POINTER phrase is not specified, the sending field character-string
is examined, beginning with the leftmost character. If the POINTER
phrase is specified, the field is examined, beginning at the relative
character position specified by the value in the pointer field.
- If the DELIMITED BY phrase is specified, the examination proceeds from
left to right, character-by-character, until a delimiter is
encountered. If the end of the sending field is reached before a
delimiter is found, the examination ends with the last character in the
sending field. If there are more receiving fields, the next one is
selected, otherwise, an overflow condition occurs.
- If the DELIMITED BY phrase is not specified, the number of characters
examined is equal to the size of the current data receiving field, which
depends on its data category:
- If the receiving field is alphanumeric or alphabetic, the number of
characters examined is equal to the number of characters in the current
receiving field.
- If the receiving field is numeric, the number of characters examined is
equal to the number of characters in the integer portion of the current
receiving field.
- If the receiving field is described with the SIGN IS SEPARATE clause, the
number of characters examined is one less than the size of the current
receiving field.
- If the receiving field is described as a variable-length data item, the
number of characters examined is determined by the size of the current
receiving field at the beginning of the UNSTRING operation.
- The examined characters (excluding any delimiter characters) are treated
as an alphanumeric elementary item, and are moved into the current data
receiving field, according to the rules for the MOVE statement (see MOVE Statement).
- If the DELIMITER IN phrase is specified, the delimiting characters in the
sending field are treated as an elementary alphanumeric item and are moved to
the current delimiter receiving field, according to the rules for the MOVE
statement. If the delimiting condition is the end of the sending field,
the current delimiter receiving field is filled with spaces.
- If the COUNT IN phrase is specified, a value equal to the number of
examined characters (excluding any delimiters) is moved into the data count
field, according to the rules for an elementary move.
- If the DELIMITED BY phrase is specified, the sending field is further
examined, beginning with the first character to the right of the
delimiter.
- If the DELIMITED BY phrase is not specified, the sending field is further
examined, beginning with the first character to the right of the last
character examined.
- For each succeeding data receiving field, the preceding procedure is
repeated either until all the characters in the sending field have been
transferred, or until there are no more unfilled data receiving fields.
- When the POINTER phrase is specified, the value of the pointer field
behaves as if it were increased by 1 for each examined character in the
sending field. When this execution of the UNSTRING statement is
completed, the pointer field contains a value equal to its initial value, plus
the number of characters examined in the sending field.
- When the TALLYING phrase is specified, then, when this execution of the
UNSTRING statement is completed, the field-count field contains a value equal
to the initial value, plus the number of data receiving areas acted
upon.
- Note:
- All subscripting, reference modification, variable-length calculations, or
function evaluations are performed only once, at the beginning of the
execution of the UNSTRING statement.
If any of the UNSTRING statement identifiers are subscripted or indexed,
the subscripts and indexes are evaluated as follows:
- Any subscripting or indexing associated with the sending field, the
pointer field, or the field-count field is evaluated only once, immediately
before any data is transferred to any of the receivers.
- Any subscripting or indexing associated with the delimiters, the data and
delimiter receiving fields, or the data-count fields, is evaluated immediately
before the transfer of data into the affected data item.
Figure 25 illustrates the rules of execution for the UNSTRING
statement.
Figure 25. Results of UNSTRING Statement Execution

- (1)
- 3 characters are placed in ID-R1.
- (2)
- Because ALL * is specified, all consecutive asterisks are processed, but
only one asterisk is placed in ID-D1.
- (3)
- 5 characters are placed in ID-R2.
- (4)
- A ? is placed in ID-D2. The current receiving field is now
ID-R3.
- (5)
- A ? is placed in ID-D3; ID-R3 is filled with spaces; no
characters are transferred, so 0 is placed in ID-C3.
- (6)
- No delimiter is encountered before 5 characters fill ID-R4; 8 is
placed in ID-C4, representing the number of characters examined since the last
delimiter.
- (7)
- ID-P is updated to 21, the total length of the sending field + 1;
ID-T is updated to 5, the number of fields acted upon + 1. Since there
are no unexamined characters in the ID-SEND, the OVERFLOW EXIT is not
taken.
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]
(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.