Compaq COBOL AAQ2G1FTK - Manual (Page 162)

Using the STRING, UNSTRING, and INSPECT Statements
5.2 Separating Data Using the UNSTRING Statement
If the compiler has moved only three sending strings when it reaches the end
of FIELD1, it adds 3 to RCOUNT. The first three receiving items (FIELD2A,
FIELD2B, and FIELD2C) contain data from the UNSTRING operation, but the
last two (FIELD2D and FIELD2E) do not.
The UNSTRING statement does not initialize the TALLYING data item. The
TALLYING data item always contains the sum of its initial contents plus the
number of receiving items receiving data. Thus, you might want to initialize the
tally count before each use.
You can use the POINTER and TALLYING phrases together in the same
UNSTRING statement, but the POINTER phrase must precede the TALLYING
phrase. Both phrases must follow all of the item names, the DELIMITER phrase,
and the COUNT phrase. The data items for both phrases must contain numeric
integers without editing characters or the symbol P in their PICTURE character-
strings; both data items can be either COMP or DISPLAY usage. They can be
signed or unsigned and, if they are DISPLAY usage, they can contain any desired
sign option.
5.2.7 Exiting an UNSTRING Statement Using the OVERFLOW Phrase
The OVERFLOW phrase detects the overflow condition and causes an imperative
statement to be executed when it detects the condition. An overflow condition
exists when:
• The UNSTRING statement is about to execute and its pointer data item
contains a value less than one or greater than the size of the sending item.
The compiler generates code that executes the OVERFLOW phrase before it
moves any data, and the values of all the receiving items remain unchanged.
• Data still remains in the sending item after the UNSTRING statement has
filled all the receiving items. The compiler executes the OVERFLOW phrase
after it has executed the UNSTRING statement. The value of each receiving
item is updated, but some data is still unmoved.
If the UNSTRING operation causes the scan to move past the rightmost position
of the sending item (thus exhausting it), the compiler does not execute the
OVERFLOW phrase.
The following set of instructions causes program control to execute the
UNSTRING statement repeatedly until it exhausts the sending item. The
TALLYING data item is a subscript that indexes the receiving item. Compare
this loop with the previous loop, which accomplishes the same thing:
MOVE 1 TO TLY PNTR.
PAR1. UNSTRING FIELD1 DELIMITED BY ","
OR CR
INTO FIELD2(TLY) WITH POINTER PNTR
TALLYING IN TLY
ON OVERFLOW GO TO PAR1.
5.2.8 Common UNSTRING Statement Errors
The most common errors made when writing UNSTRING statements are as
follows:
• Leaving the OR connector out of a delimiter list
• Misspelling or interchanging the words DELIMITED and DELIMITER
• Writing the DELIMITER and COUNT phrases in the wrong order when both
are present (DELIMITER must precede COUNT)
5–16 Using the STRING, UNSTRING, and INSPECT Statements