HP OpenVMS Systems Documentation
Content starts here

HP COBOL
Reference Manual

Previous Contents Index

6.8.41 UNSTRING

Function

The UNSTRING statement separates contiguous data in a sending field and stores it in one or more receiving fields.

src-string

is the identifier of an alphanumeric class data item. It cannot be reference modified. Src-string is the sending field.

delim

is a nonnumeric literal or the identifier of an alphanumeric data item. It is the delimiter for the UNSTRING operation.

dest-string

is the identifier of an alphanumeric, alphabetic, or numeric DISPLAY data item. It is the receiving field for the data from src-string.

delim-dest

is the identifier of an alphanumeric data item. It is the receiving field for delimiters.

countr

is the identifier of an elementary numeric data item described as an integer. It contains the count of characters moved.

pointr

is the identifier of an elementary numeric data item described as an integer. It points to the current character position in src-string.

tally-ctr

is the identifier of an elementary numeric data item described as an integer. It counts the number of dest-string fields accessed during the UNSTRING operation.

stment

is an imperative statement executed for an on overflow condition.

stment2

is an imperative statement executed for a not on overflow condition.

Syntax Rules

  1. Literals can be any figurative constant other than ALL literal.
  2. pointr must be large enough to contain a value one greater than the size of src-string.
  3. The DELIMITER IN and COUNT IN phrases can appear only if there is a DELIMITED BY phrase.
  4. countr, pointr, dest-string, and tally-ctr cannot define the assumed decimal scaling position character P in their PICTURE clauses.

General Rules

  1. countr represents the number of characters in src-string isolated by the delimiters for the move to dest-string. The count does not include the delimiter characters.
  2. When delim is a figurative constant, its length is one character.
  3. When the ALL phrase is present:
    • One occurrence, or two or more contiguous occurrences, of delim (whether or not they are figurative constants) is treated as only one occurrence.
    • One occurrence of delim is moved to delim-dest when there is a DELIMITER IN phrase.
  4. When any examination finds two contiguous delimiters, the current dest-string is filled with:
    • Spaces, if its class is alphabetic or alphanumeric
    • Zeros, if its class is numeric
  5. delim can contain any characters in the computer character set.
  6. Each delim is one delimiter. When delim contains more than one character, all its characters must be in src-string (in contiguous positions and the given order) to qualify as a delimiter.
  7. When the DELIMITED BY phrase contains an OR phrase, an OR condition exists between all occurrences of delim. Each delim is compared to src-string. If a match occurs, the character in src-string is a single delimiter. No character in src-string can be part of more than one delimiter.
  8. Each delim applies to src-string in the order it appears in the UNSTRING statement.
  9. When execution of the UNSTRING statement begins, the current receiving field is the first dest-string.
  10. If there is a POINTER phrase, the string of characters in src-string is examined, beginning with the position indicated by pointr. Otherwise, examination begins with the leftmost character position.
  11. If there is a DELIMITED BY phrase, examination proceeds to the right until the UNSTRING statement detects delim. (See General Rule 6.)
  12. If there is no DELIMITED BY phrase, the number of characters examined equals the size of the current dest-string. However, if the sign of dest-string is defined as occupying a separate character position, UNSTRING examines one less character than the size of dest-string. If dest-string is a variable-length data item, its current size determines the number of characters examined.
  13. If the UNSTRING statement reaches the end of src-string before detecting the delimiting condition, examination ends with the last character examined.
  14. The characters examined (excluding delim) are:
    • Treated as an elementary alphanumeric data item
    • Moved to the current dest-string according to the MOVE statement rules
  15. When there is a DELIMITER IN phrase, the delimiter is:
    • Treated as an elementary alphanumeric data item
    • Moved to delim-dest according to the MOVE statement rules

    If the delimiting condition is the end of src-string, delim-dest is space-filled.
  16. The COUNT IN phrase causes the UNSTRING statement to:
    • Count the number of characters examined (excluding the delimiter).
    • Move the count to countr according to the elementary move rules.
  17. When there is a DELIMITED BY phrase, UNSTRING continues examining characters immediately to the right of the delimiter. Otherwise, examination continues with the character immediately to the right of the last one transferred.
  18. After data transfers to dest-string, the next dest-string becomes the current receiving field.
  19. The process described in General Rules 12 to 18 repeats until either:
    • There are no more characters in src-string.
    • The last dest-string has been processed.
  20. The UNSTRING statement does not initialize pointr or tally-ctr. The program must set their initial values before executing the UNSTRING statement.
  21. The UNSTRING statement adds one to pointr for each character it examines in src-string. When UNSTRING execution ends, pointr contains a value equal to its beginning value plus the number of characters the statement examined in src-string.
  22. At the end of an UNSTRING statement with the TALLYING phrase, tally-ctr contains a value equal to its beginning value plus the number of dest-string fields the statement accessed.
  23. An overflow condition can arise from either of these conditions:
    • When the UNSTRING statement begins, the value of pointr is less than one or greater than the number of characters in src-string.
    • During UNSTRING execution, all dest-string fields have been processed, and there are unexamined src-string characters.
  24. When an overflow condition occurs, if there is a NOT ON OVERFLOW phrase, this phrase is ignored and the UNSTRING operation ends. If there is an ON OVERFLOW phrase, stment executes. Otherwise, control passes to the end of the UNSTRING statement.
  25. At the end of the UNSTRING operation, when an overflow condition does not exist, the ON OVERFLOW phrase is ignored and the UNSTRING operation ends if a NOT ON OVERFLOW phrase does not exist. If there is a NOT ON OVERFLOW phrase, stment2 executes. After stment2 executes, control is passed to the end of the UNSTRING statement.
  26. If there is a DELIMITED BY phrase and the size of dest-string is zero characters, no characters are moved. However, delim-dest contains the matched delimiter and countr contains the character count.
  27. If there is no DELIMITED BY phrase and the size of dest-string is zero characters, no characters are moved. The value of pointr does not change. UNSTRING continues with the next dest-string.
  28. If the size of delim is zero characters, delim does not match any characters in src-string.

Additional References

Examples

The examples assume these data descriptions: 


WORKING-STORAGE SECTION.
01      INMESSAGE PIC X(20).
01      THEDATE.
        03  THEYEAR  PIC XX JUST RIGHT.
        03  THEMONTH PIC XX JUST RIGHT.
        03  THEDAY   PIC XX JUST RIGHT.
01      HOLD-DELIM   PIC XX.
01      PTR          PIC 99.
01      FIELD-COUNT  PIC 99.
01      MONTH-COUNT  PIC 99.
01      DAY-COUNT    PIC 99.
01      YEAR-COUNT   PIC 99.
  • With OVERFLOW phrase: 


            DISPLAY "Enter a date: " NO ADVANCING.
        ACCEPT INMESSAGE.
        UNSTRING INMESSAGE
          DELIMITED BY "-" OR "/" OR ALL " "
            INTO THEMONTH DELIMITER IN HOLD-DELIM
                 THEDAY DELIMITER IN HOLD-DELIM
                 THEYEAR DELIMITER IN HOLD-DELIM
          ON OVERFLOW MOVE ALL "0" TO THEDATE.
        INSPECT THEDATE REPLACING ALL " " BY "0".
        DISPLAY THEDATE.

    Results 


    Enter a date: 6/13/87
870613
Enter a date: 6-13-87
870613
Enter a date: 6-13 87
870613
Enter a date: 6/13/87/2
000000
Enter a date: 1-2-3
030102
  • With POINTER and TALLYING phrases: 


            DISPLAY "Enter two dates in a row: " NO ADVANCING.
        ACCEPT INMESSAGE.
        MOVE 1 TO PTR.
        PERFORM DISPLAY-TWO 2 TIMES.
        GO TO DISPLAYED-TWO.
DISPLAY-TWO.
        MOVE SPACES TO THEDATE.
        MOVE 0 TO FIELD-COUNT.
        UNSTRING INMESSAGE
          DELIMITED BY "-" OR "/" OR ALL " "
            INTO THEMONTH DELIMITER IN HOLD-DELIM
                 THEDAY DELIMITER IN HOLD-DELIM
                 THEYEAR DELIMITER IN HOLD-DELIM
            WITH POINTER PTR
            TALLYING IN FIELD-COUNT.
        INSPECT THEDATE REPLACING ALL " " BY "0".
        DISPLAY THEDATE "   " PTR "   " FIELD-COUNT.
DISPLAYED-TWO.
        EXIT.

    Results 


    Enter two dates in a row: 6/13/87 8/15/87
870613   09   03
870815   21   03
Enter two dates in a row: 10 15 87-1 1 88
871015   10   03
880101   21   03
Enter two dates in a row: 6/13/87-12/31/87
870613   09   03
871231   21   03
Enter two dates in a row: 6/13/87-12/31
870613   09   03
001231   21   02
Enter two dates in a row: 6/13/87/12/31/87
870613   09   03
871231   21   03

    Previous Next Contents Index