# Compaq COBOL
Reference Manual

Previous | Contents | Index

- Using the POINTER phrase:

          MOVE 0 TO LINE-COUNT.
          MOVE 1 TO PTR.
      GET-WORD.
          IF LINE-COUNT NOT < 4
            DISPLAY "   " TEXT-STRING
            GO TO GOT-WORDS.
          ACCEPT INPUT-MESSAGE.
          DISPLAY INPUT-MESSAGE.
      SAME-WORD.
          MOVE PTR TO HOLD-PTR.
          STRING INPUT-MESSAGE DELIMITED BY SPACE
            ", " DELIMITED BY SIZE
            INTO TEXT-STRING
            WITH POINTER PTR
            ON OVERFLOW
          STRING "                 " DELIMITED BY SIZE
                INTO TEXT-STRING
                WITH POINTER HOLD-PTR
              DISPLAY "   " TEXT-STRING
          MOVE SPACES TO TEXT-STRING
              ADD 1 TO LINE-COUNT
              MOVE 1 TO PTR
              GO TO SAME-WORD.
          GO TO GET-WORD.
      GOT-WORDS.
          EXIT.

  Results

      This
      example
      demonstrates
      how
         This, example, demonstrates,
      the
      STRING
      statement
      can
         how, the, STRING, statement,
      construct
      text
      strings
         can, construct, text,
      using
      the
      POINTER
      phrase
         strings, using, the, POINTER,
         phrase,

  ## 6.8.37 SUBTRACT

  Function

  The SUBTRACT statement subtracts one, or the sum of two or more, numeric items from one or more items. It stores the difference in one or more items.

  > ### num

  > is a numeric literal or the identifier of an elementary numeric item.

  > ### rsult

  > is the identifier of an elementary numeric item. However, in Format 2, rsult can be an elementary numeric edited item. It is the resultant identifier.

  > ### stment

  > is an imperative statement executed when a size error condition has occurred.

  > ### stment2

  > is an imperative statement executed when no size error condition has occurred.

  > ### grp-1

  > is the identifier of a group item.

  > ### grp-2

  > is the identifier of a group item.

  Syntax Rule

  CORR is an abbreviation for CORRESPONDING.

  General Rules

  1. In Format 1, the values of the operands before the word FROM are summed. This total is then subtracted from each rsult.
  2. In Format 2, the values of the operands before the word FROM are summed. This total is subtracted from the num following the word FROM. The result replaces the current value of each rsult.
  3. In Format 3, data items in grp-1 are subtracted from and stored in the corresponding data items in grp-2.

  Additional References

  - Section 6.1.4, Scope of Statements
  - Section 6.6.1, Arithmetic Operations
  - Section 6.6.2, Multiple Receiving Fields in Arithmetic Statements
  - Section 6.6.3, ROUNDED Phrase
  - Section 6.6.4, ON SIZE ERROR Phrase
  - Section 6.6.5, CORRESPONDING Phrase
  - Section 6.6.7, Overlapping Operands and Incompatible Data

  Examples

  Each of the examples assume these data descriptions and initial values.

  INITIAL VALUES

           03  ITEMA  PIC S99 VALUE -85.             -85
           03  ITEMB  PIC 99 VALUE 2.                  2
           03  ITEMC  VALUE "123".
               05  ITEMD  OCCURS 3 TIMES             1 2 3
                       PIC 9.
           03  ITEME  PIC S99 VALUE -95.             -95

  1. Without GIVING phrase: RESULTS

         SUBTRACT 2 ITEMB FROM ITEMA.                   ITEMA = -89

  2. SIZE ERROR clause:
     (When the size error condition occurs and the SIZE ERROR clause is specified, the values of the affected resultant identifiers do not change.)

         SUBTRACT 14 FROM ITEMA, ITEME                  ITEMA = -99
           ON SIZE ERROR                                ITEME = -95
             MOVE 0 TO ITEMB.                           ITEMB = 0

  3. NOT ON SIZE ERROR clause:

         SUBTRACT 14 FROM ITEMA                         ITEMA = -99
           ON SIZE ERROR
             MOVE 9 TO ITEMB.
           NOT ON SIZE ERROR
             MOVE 1 TO ITEMB.                           ITEMB =  1

  4. Multiple receiving fields:
     (The operations proceed from left to right. Therefore, the subscript for ITEMB is evaluated after the subtraction changes its value.)

         SUBTRACT 1 FROM ITEMB ITEMD (ITEMB).           ITEMB = 1
                                                        ITEMD (1) = 0

  5. GIVING phrase:

         SUBTRACT ITEME ITEMD (ITEMB) FROM ITEMA        ITEMB = 8
              GIVING ITEMB.

  6. END-SUBTRACT:
     (The first SUBTRACT terminates with END-SUBTRACT. If the SIZE ERROR condition had not occurred, the second SUBTRACT statement would have executed anyway: the value of ITEMA would have been -86.)

         SUBTRACT 10 ITEMB FROM ITEMD (ITEMB)         ITEMD (2) = 2
           ON SIZE ERROR                              ITEMA = 0
               MOVE 0 TO ITEMA
           END-SUBTRACT.
         SUBTRACT 1 FROM ITEMA.                     ITEMA = -1

     (The following example shows the usefulness of END-SUBTRACT inside an IF statement. Without it, there would be no way to code the DISPLAY statements.)

         IF ITEMB < 3 AND > 1
            SUBTRACT 1 FROM ITEMD(ITEMB)
               ON SIZE ERROR
                  MOVE 0 TO ITEMA
            END-SUBTRACT
            DISPLAY 'yes'
         ELSE
            DISPLAY 'no'.

  ## 6.8.38 SUPPRESS

  Function

  The SUPPRESS statement causes the Report Writer Control System (RWCS) to inhibit the presentation of a report group.

  Syntax Rule

  The SUPPRESS statement can appear only in a USE BEFORE REPORTING Declarative procedure.

  General Rules

  1. The SUPPRESS statement inhibits only the presentation of a report-group-name (a 01-level Report Group Description entry).
  2. Each time the presentation of a report group is to be inhibited, the program must execute a SUPPRESS statement.
  3. The SUPPRESS statement directs the Report Writer Control System (RWCS) to inhibit the processing of these report group functions:
     - The presentation of the print lines
     - The processing of all LINE clauses
     - The processing of the NEXT GROUP clause
     - The adjustment of LINE-COUNTER
  4. The SUPPRESS statement does not inhibit the processing of sum counters or control breaks.

  Additional References

  - Section 6.6.7, Overlapping Operands and Incompatible Data
  - Section 6.8.42 statement

  Example

      PROCEDURE DIVISION.
      DECLARATIVES.
      DET SECTION.
          USE BEFORE REPORTING DETAIL-LINE.
      DETA-1.
          IF SORTED-NAME = NAME
              ADD A TO B
              SUPPRESS PRINTING.
          IF NAME = SPACES SUPPRESS PRINTING.
      END DECLARATIVES.
      MAIN SECTION.
          .
          .
          .

  ## 6.8.39 TERMINATE

  Function

  The TERMINATE statement causes the Report Writer Control System (RWCS) to complete the processing of the specified report.

  > ### report-name

  > names a report defined by a Report Description entry in the Report Section of the Data Division.

  General Rules

  1. If the TERMINATE statement includes more than one report-name, the statement executes as if there were a separate TERMINATE statement for each report-name.
  2. The program cannot execute a TERMINATE statement unless an INITIATE statement was executed before the TERMINATE statement for that report, and the program did not already execute a TERMINATE statement for that report.
  3. If the program did not execute a GENERATE statement, the execution of a TERMINATE statement does not cause the RWCS to produce any of its report groups or perform any of the related processing.
  4. The TERMINATE statement causes the RWCS to:
     - Produce all CONTROL FOOTING report groups beginning with the minor CONTROL FOOTING report group.
     - Produce the REPORT FOOTING report group.
     The RWCS makes the prior set of control data item values available to these two report groups and to any associated USE procedure. This action simulates a control break at the most major level.
  5. The RWCS automatically processes the PAGE HEADING and PAGE FOOTING report groups, if present, when it must advance the report to a new page to present a CONTROL HEADING, DETAIL, or CONTROL FOOTING report group.
  6. The TERMINATE statement does not automatically close a report file; the program must close the file. The program must terminate the report before the CLOSE statement can close the report file.

  Additional Reference

  Section 6.8.42, USE statement.

  ## 6.8.40 UNLOCK

  Function

  The UNLOCK statement removes a record lock from the current record or from all locked records in the file. On Alpha, the X/Open standard UNLOCK statement always removes the record lock from all locked records in the file.

  > ### file-name

  > is the name of a sequential, relative, or indexed file described in the Data Division.

  Syntax Rules

  1. For Format 1, if the UNLOCK statement does not include the RECORD or the ALL RECORDS option, the singular RECORD option is the default. (However, see General Rule 3.)
  2. For Format 2, the RECORD and RECORDS options have the same effect: to unlock all currently locked records. This behavior also is the default if neither option is specified.

  General Rules

  1. The first access stream to lock a record owns the record lock for that record.
  2. Only the owner of a record lock can unlock the record.
  3. For Format 1, implicitly (by default) or explicitly specifying the RECORD option unlocks the current record. Therefore, you must specify ALL RECORDS explicitly to unlock all the record locks held on file-name.
     The single exception to this rule for Format 1 is that for indexed files the RECORD option (implicitly or explicitly) is unsupported on Tru64 UNIX systems. The ALL RECORDS phrase is assumed. <>
  4. For Format 2, whether you specify the RECORD option or the RECORDS option, the effect is the same: to unlock all record locks held on file-name by the current access stream.
  5. If an access stream attempts to unlock a record (or records) in a file containing no record locks, the statement is considered successful and execution resumes at the statement following the UNLOCK statement.
  6. Because both formats of the UNLOCK statement include the `UNLOCK RECORD` and `UNLOCK` forms, the compiler determines whether to interpret these forms of the statement as X/Open standard (on Alpha) or Compaq standard as follows:
     - If on Alpha X/Open standard syntax (LOCK MODE or WITH (NO) LOCK) has been specified for file-name prior to the UNLOCK statement, the compiler interprets the statement according to the X/Open standard.
     - If Compaq standard syntax (LOCK-HOLDING, ALLOWING, or REGARDLESS) has been specified for file-name prior to the UNLOCK statement, the compiler interprets the statement according to the Compaq standard.
     - If no file-sharing syntax (LOCK-HOLDING, ALLOWING, REGARDLESS, LOCK MODE, or WITH [NO] LOCK) has been specified for file-name prior to the UNLOCK statement, then the compiler uses the /STANDARD=[NO]XOPEN qualifier on OpenVMS Alpha (or the Tru64 UNIX equivalent `-std [no]xopen` flag) to determine whether the START statement is interpreted as X/Open or Compaq standard: a setting of `xopen` selects the X/Open standard, whereas a setting of `noxopen` selects the Compaq standard.
     Any subsequent I-O locking syntax for the same file connector in your program must be consistent: X/Open standard locking and Compaq standard locking (implicit or explicit) cannot be mixed for the same file connector.

  Technical Notes

  - UNLOCK statement execution can result in these FILE STATUS data item values:

    File Status | File Organization | Access Method | Meaning
    --- | --- | --- | ---
    00 | All | All | Unlock is successful
    93 | All | All | No current record
    94 | All | All | File not open, or incompatible open mode
    30 | All | All | All other permanent errors

  Additional References

  - LOCK-HOLDING phrase in APPLY Clause in Section 4.2.10, I-O-CONTROL paragraph in Chapter 4
  - LOCK MODE phrase in SELECT clause in File Control paragraph in Chapter 4
  - Technical Notes for Section 6.8.9, DELETE statement
  - Section 6.8.24, OPEN statement

  Compaq Standard Examples

  These examples assume only one access stream for the image. The following examples refer to this partial program:

      CONFIGURATION SECTION.
      FILE-CONTROL.
          SELECT MASTER-FILE ASSIGN TO "CLIENT.DAT"
          ORGANIZATION IS INDEXED
          ACCESS MODE IS DYNAMIC
          RECORD KEY IS MASTER-KEY
          FILE STATUS IS FILE-STAT.
      I-O-CONTROL.

      *
      * This APPLY clause is required syntax for manual record locking
      *

          APPLY LOCK-HOLDING ON MASTER-FILE.

      DATA DIVISION.
      FD  MASTER-FILE
          LABEL RECORDS STANDARD.
      01  MASTER-RECORD.
           .
           .
           .
      PROCEDURE DIVISION.
      A100-BEGIN.

      *
      *  The ALLOWING phrase enables file sharing
      *

          OPEN I-O MASTER-FILE ALLOWING ALL.
           .
           .
           .
      A900-END-OF-JOB.

  1. Unlocking the record lock on the current record by taking the default RECORD option:

              READ MASTER-FILE KEY IS MASTER-KEY
                   ALLOWING NO OTHERS.
              REWRITE MASTER-RECORD ALLOWING NO OTHERS.
              UNLOCK MASTER-FILE.

  2. Explicitly unlocking the record lock on the current record:

              READ MASTER-FILE KEY IS MASTER-KEY
                   ALLOWING NO OTHERS.
              .
              .
              .
              UNLOCK MASTER-FILE RECORD.

  3. Unlocking all records in MASTER-FILE:

              PERFORM A100-READ-MASTER UNTIL
                        MASTER-KEY = ID-KEY
                     OR
                        MASTER-KEY > ID-KEY.
              .
              .
              .
              UNLOCK MASTER-FILE ALL RECORDS.
              .
              .
              .
          A100-READ-MASTER.
              READ MASTER-FILE ALLOWING NO OTHERS.

  X/Open Standard Example (Alpha)

  The following example shows the use of X/Open standard syntax:

        SELECT employee-file ASSIGN TO "EMPFIL"
               ORGANIZATION IS INDEXED
               ACCESS MODE IS DYNAMIC
               RECORD KEY IS employee-id
               LOCK MANUAL LOCK ON MULTIPLE RECORDS
               FILE STATUS IS emp-stat.
         .
         .
         .
      * The file is implicitly shareable via the SELECT specification.
          OPEN I-O employee-file.

          PERFORM UNTIL emp-stat = end-of-file
              READ employee-file NEXT RECORD
                   WITH LOCK

              IF employee-job-code = peon-code
                 PERFORM find-boss-record
              ENDIF
         .
         .
         .
              REWRITE employee-record

      *   This will unlock this record and the boss's
      *   record found earlier.

              UNLOCK employee-file RECORDS

           END-PERFORM.

      FIND-BOSS-RECORD.
          START employee-file
                KEY > employee-job-code.
          READ employee-file NEXT WITH LOCK.

  ## 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

  - Section 6.1.4, Scope of Statements
  - Section 6.8.22, MOVE statement

  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