Data Flow

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):
  1. 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.
  2. 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.
  3. 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:
    1. 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.
    2. 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.
    3. 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.
    4. 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.
  4. 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).
  5. 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.
  6. 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.
  7. If the DELIMITED BY phrase is specified, the sending field is further examined, beginning with the first character to the right of the delimiter.
  8. 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.
  9. 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.
  10. 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.
  11. 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 1 illustrates the rules of execution for the UNSTRING statement.

Figure 1. Results of UNSTRING Statement Execution
This figure illustrates the rules of execution for the UNSTRING statement
 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.