HP 3000 Manuals HP 3000 Manuals
UNSTRING Statement The UNSTRING statement divides data in a sending field and places the segments of the data into multiple receiving fields. SyntaxParameters literal-1 and nonnumeric literals; may also be any figurative constants literal-2 without the optional word ALL. identifier-1, must be described implicitly or explicitly as identifier-2, alphanumeric data items. Identifier-1 may not be identifier-3, reference modified. and identifier-5, identifier-4 may be described as alphabetic, alphanumeric, or numeric data items. identifier-7 must be described as an elementary numeric integer data item of sufficient size to contain a value equal to 1 plus the size of the data item referenced by identifier-1. The symbol 'P' may not be used in the PICTURE character string of either identifier-4 or identifier-7. ________________________________________________________ NOTE Edited receiving fields are not permitted. ________________________________________________________ identifier-6 must be described as elementary numeric integer data and items. The P symbol may not be used in their identifier-8 descriptions. Description No identifier may name a level 88 entry. If the DELIMITED BY phrase is not specified, the DELIMITER IN and COUNT IN phrases must not be used. Identifier-1 represents the sending item. Identifier-4 represents the receiving data item. Identifier-2 or its associated literal, and identifier-3 or its associated literal, represent delimiters on the sending item. If a figurative constant is used as a delimiter, it stands for a single character nonnumeric literal. Identifier-5 names the receiving item for the specified delimiter. Identifier-6 is used to hold the count of the number of characters in the sending item moved to the receiving item. This value does not include the count of the delimiter character(s). A delimiter may be any character available in the ASCII collating sequences. Also, when a delimiter contains two or more characters, all of the characters must be in contiguous positions of the sending item, and be in the order specified to be recognized as a delimiter. When more than one delimiter is specified, each delimiter is compared to the sending item in turn. If a match occurs in one of these comparisons, examination of the sending field ceases. Delimiters may not overlap. That is, no character or characters in the sending item can be considered part of more than one delimiter. When the ALL keyword is used in the DELIMITED phrase, and an associated delimiter is encountered while examining the sending item, each contiguous occurrence of the delimiter, beginning at the point where the delimiter first occurs, is considered as part of that delimiter. If the DELIMITER IN phrase has been specified, the entire string of contiguous delimiters is moved to the appropriate delimiter receiver. After a single delimiter (or a string of delimiters as described in the preceding paragraph) has been found, if the next character or set of characters is a delimiter, the current receiving item is space or zero filled, depending upon how the receiving item is described. If the DELIMITER IN phrase is specified for that particular receiving item, the delimiter is then moved to the corresponding delimiter receiver. The data item represented by identifier-7 contains an integer used to indicate the first character, counting from the leftmost character of the sending item, to be examined. You are responsible for setting the initial value of this item. If it is less than one or is greater than the number of characters in the sending item when the UNSTRING statement is initiated, an OVERFLOW CONDITION exists. When an UNSTRING statement completes execution, if the POINTER phrase is specified, the value of identifier-7 is equal to the initial value plus the number of characters examined in the data item referenced by identifier-1. The data item referenced by identifier-8 is a counter that records the number of receiving items acted upon during the execution of an UNSTRING statement. As with identifier-7, you must initialize the value of identifier-8. When the UNSTRING statement completes execution, if the TALLYING phrase has been specified, the value of identifier-8 is the initial value of identifier-8 plus the number of data receiving items acted upon. Execution of the UNSTRING Statement When the UNSTRING statement is initiated, the current receiving item is the first receiving item. If the POINTER phrase is specified, the sending item is examined beginning with the character position indicated by the contents of the data item referenced by identifier-7. If this phrase is not used, examination begins with the leftmost character of the sending item. If the DELIMITED BY phrase is specified, the examination proceeds left to right until either a delimiter is found or no delimiters are found, and the last character of the sending item is examined. If the DELIMITED BY phrase is not specified, the number of characters in the current receiving item is used to determine how many characters of the sending item are to be examined. That is, the number of characters examined is equal to the size of the receiving data item. However, if the receiving data item is a numeric data item described with the SIGN IS SEPARATE clause, the number of characters examined is one less than the size of the receiving data item. When examination is complete, the examined characters, excluding any delimiters encountered, are treated as an elementary alphanumeric data item, and are moved into the receiving data item according to the rules for an alphanumeric MOVE. Refer to the description of the MOVE statement, earlier in this chapter. If the DELIMITER IN phrase is specified for the current receiving item and a delimiter was encountered, the character (or characters) making up the delimiter are treated as an elementary alphanumeric data item and is moved into the delimiter receiver according to the rules of the MOVE statement. If the examination of the sending item ceased for a reason other than the occurrence of a delimiter, the delimiter receiver is filled with spaces. If the COUNT IN phrase is specified for the current receiving item, a value equal to the number of characters examined, excluding any delimiter characters, is moved to the count receiver according to the rules for an elementary move. This completes the initial phase of execution of the UNSTRING statement. If all characters of the sending item (beginning from the position specified by identifier-7 if the POINTER phrase is specified) have been examined, the UNSTRING statement is complete and control passes to the next executable statement, or to the imperative statement of the NOT ON OVERFLOW phrase, if specified. If all characters have not been used and another receiving item is specified, examination of the sending item begins again. This second examination begins with the character immediately to the right of the delimiter (if any) that caused termination of the initial examination. If no delimiter was specified, meaning that examination ceased because the number of characters in the current receiving item had been examined, examination begins with the character immediately to the right of the last character transferred. The contents of the data item referenced by identifier-7 are incremented by one for each character examined in the sending item. A new phase of examination and transfer is executed for each receiver item specified, or until all characters in the sending item have been examined. Each new phase of the UNSTRING statement is executed in the same way. Overflow Conditions An overflow condition is caused by one of two situations. The first, described under the parameters description above, is caused by an invalid value for the data item represented by identifier-7. The second situation is when all receiving items have been acted upon, but there remain unexamined characters in the sending item. When an overflow condition occurs, execution of the UNSTRING condition ceases. If the ON OVERFLOW phrase is specified and an overflow condition occurs, the imperative statement in the ON OVERFLOW phrase is executed. If the ON OVERFLOW phrase is not specified, control is passed to the next executable statement following the UNSTRING statement. Subscripting or Indexing of Identifiers Subscripting or indexing of an identifier is evaluated only once, immediately before any data is transferred as the result of the initial phase of the UNSTRING statement. Example DATA DIVISION. WORKING-STORAGE SECTION. 01 ID-INFO PIC X(35). 01 EMPLOYEE-TABLE. 02 EMPLOYEE-STATS OCCURS 30 TIMES. 03 NAME PIC X(40). 03 BIRTH-DATE PIC X(6). 03 HAIR-COLOR PIC X(12). 03 EYE-COLOR PIC X(12). 03 HEIGHT PIC X(2). 01 SUBSCRIPTOR PIC X. 01 SUBSCRIPT PIC 99 VALUE 1. 01 INCREMENT PIC X VALUE ";". 01 CHARS PIC S9(4) USAGE COMP. 01 COMPLETE-INFO PIC S9(4) USAGE COMP. : MOVE 1 TO CHARS. MOVE 0 TO COMPLETE-INFO. UNSTRING ID-INFO DELIMITED BY "," OR INCREMENT INTO NAME (SUBSCRIPT) BIRTH-DATE (SUBSCRIPT) HAIR-COLOR (SUBSCRIPT) EYE-COLOR (SUBSCRIPT) HEIGHT (SUBSCRIPT) DELIMITER IN SUBSCRIPTOR WITH POINTER CHARS TALLYING IN COMPLETE-INFO ON OVERFLOW PERFORM FIND-CAUSE. If ID-INFO is in standard data format: WILSON JAMES,030250,BLONDE,BLUE,59; and the initial value of CHARS is 1, and of COMPLETE-INFO is 0, when the UNSTRING statement above is executed it goes through the phases described below. * Phase 1: WILSON JAMES, uparrow uparrow Initial delimiter pointer found Move "WILSON JAMES" into NAME(1) filling in spaces to the left of the rightmost character. Increment the value of CHARS by 13, giving 14. * Phase 2: WILSON JAMES,030250, uparrow uparrow new pointer delimiter found Move 030250 into BIRTH-DATE(1). Increment the value of CHARS by 7, giving 21. * Phase 3: WILSON JAMES,030250,BLONDE, uparrow uparrow new pointer delimiter found Move "BLONDE" into HAIR-COLOR(1), filling in spaces to the left of the rightmost character. Increment the value of CHARS by 7, giving 28. * Phase 4: WILSON JAMES,030250,BLONDE,BLUE, uparrow uparrow new pointer delimiter found Move "BLUE" into EYE-COLOR(1). Increment the value of CHARS by 5, giving 33. * Phase 5: WILSON JAMES,030250,BLONDE,BLUE,59; uparrow new pointer; first delimiter not found. WILSON JAMES,030250,BLONDE,BLUE,59; uparrow uparrow new pointer second delimiter found. Move "59" to HEIGHT(1), and ";" to SUBSCRIPTOR. Increment the value of CHARS by 3, giving 36. Since all receiving items have been used, this completes the execution of the UNSTRING statement. The value of CHARS is 36 and the value of COMPLETE-INFO is 5, since five receiving items were acted upon.
![[]](../../pic3k/M011820/FFN1163c50.gif)