The UNSTRING statement separates a data item into one or more receiving fields. Delimiters may be used to specify the ends of fields. Substring values are assigned to unique destination data items.
UNSTRING source
[ DELIMITED BY [ALL] delim
[ OR [ALL] delim ] ... ]
INTO { dest [ DELIMITER in delim-dest ]
[ COUNT IN counter ] } ...
[ WITH POINTER ptr-var ]
[ TALLYING IN tally-var ]
[ ON OVERFLOW statement-1 ]
[ NOT ON OVERFLOW statement-2 ]
[ END-UNSTRING ]
Syntax Rules
1. Source is an alphanumeric data item.
2. Dest is a USAGE DISPLAY data item. It may not be edited.
3. Delim is a nonnumeric literal or an alphanumeric data item. An "ALL literal" is not allowed.
4. Delim-dest is an alphanumeric data item.
5. Counter, ptr-var, and tally-var are integer numeric data items.
6. Statement-1 and statement-2 are imperative statements.
7. Ptr-var must be large enough to contain a value one greater than the size of source.
8. The DELIMITER IN and COUNT IN phrases can appear only if there is a DELIMITED BY phrase.
General Rules
1. UNSTRING breaks up source into the various dest fields. Source is the sending field and dest is the receiving field. Up to 50 dest items are allowed.
2. Counter represents the count of the number of characters within source isolated by the delimiters for the move to dest. This does not include a count of the delimiter characters.
3. Ptr-var represents the relative character position within source to move from. The leftmost position is position "1". If no POINTER phrase is specified, examination begins with the leftmost character position.
4. Tally-var is a counter which is incremented by 1 for each dest item accessed during the UNSTRING operation.
5. Neither ptr-var nor tally-var is initialized by the UNSTRING statement.
6. Each delim represents one delimiter. When a delimiter contains two or more characters, all the characters must be present in contiguous positions in source to be recognized as a delimiter. When delim is a figurative constant, it stands for a single nonnumeric literal.
7. When the ALL phrase is specified, one or more contiguous occurrences of delim in source are treated as if they were only one occurrence for the remaining General Rules. Only one occurrence of delim is moved to delim-dest in this case.
8. When two or more delimiters are specified, an OR condition exists between them. Each delimiter is compared to the sending field in the order written. If a match occurs, the characters in the sending field are considered to be a single delimiter. No characters in source can be considered a part of more than one delimiter.
9. When an examination encounters two contiguous delimiters, the current receiving area is space-filled if it is alphabetic or alphanumeric, or zero-filled if it is numeric.
10. When the UNSTRING statement initiates, the current receiving area is the first dest item. Data is transferred from source to the receiving area according to the following rules:
a) Examination starts at the character position indicated by ptr-var, or the leftmost position if ptr-var is not specified.
b) If the DELIMITED BY phrase is specified, the examination proceeds left-to-right until a delimiter is encountered. If the DELIMITED BY phrase is not specified, the number of characters examined is equal to the size of the receiving area. The sign character of the receiving item (if any) is not included in the size. If the end of source is encountered before the delimiting condition is met, the examination stops with the last character of source.
c) The characters examined (excluding the delimiting characters, if any) are treated as an elementary alphanumeric item. These characters are moved to the current receiving field according to the rules for the MOVE statement, including space filling.
d) If the DELIMITER IN phrase is specified, the delimiting characters are moved to delim-dest as if they were the alphanumeric source of a MOVE statement. If the delimiting condition is the end of source, then delim-dest is space-filled.
e) If the COUNT IN phrase is specified, the number of characters examined (excluding the delimiter) is moved to counter as if the count were the numeric source of a MOVE statement.
f) If the DELIMITED BY phrase is specified, the source item is further examined beginning with the first character to the right of the delimiter found. If the DELIMITED BY phrase is not specified, the source item is further examined beginning with the character to the right of the last character examined.
g) The current receiving area is then set to the next dest item and the cycle specified in steps (b) through (g) is repeated until either all the characters in source are examined or there are no more dest items.
11. The ptr-var (if any) is incremented by 1 for each character in source examined.
12. An overflow condition occurs in either of the following situations:
a) The value of ptr-var is less than one or greater than the size of source when the UNSTRING statement starts.
b) During execution, all dest items have been acted upon and source contains unexamined characters.
13. When the overflow condition exists, statement-1 (if any) executes and the UNSTRING statement terminates.
14. If statement-2 is specified, it executes after the UNSTRING statement has finished if the overflow condition has not occurred.
More: