# Compaq COBOL
Reference Manual

Previous | Contents | Index

Technical Notes

- On Alpha systems, because the reserved word RETURN-CODE is one of the X/Open reserved words, you cannot use the `reserved words` compiler option with the `noxopen` setting if you want to use the RETURN-CODE special register.
  For more information on the relationship between the GIVING phrase and the RETURN-CODE special register, see Table 6-7 in this chapter. <>
- On Tru64 UNIX systems, the linker is case sensitive, whereas the COBOL language is case insensitive. When prog-name in a CALL statement is a literal, and you are calling a program in a case-sensitive language (such as C), you might need to use a form of the `names` option when you compile.
  If you do not specify the `names` option on the command line, the default setting is `lowercase` , which causes the Compaq COBOL compiler to force all external names to be lowercase. Hence, there is no problem when you call a C program whose name contains no uppercase letters. If the name consists of all uppercase letters, use the `uppercase` setting of the `names` option. If it is mixed-case (for example, "Cprog") use the `as_is` setting. When you use `names as_is` , only literals in the CALL program name are affected.<>
- On OpenVMS, calls to the OpenVMS RTL routines LIB$ESTABLISH and LIB$REVERT, which are used to establish and cancel a condition handler, respectively, are handled specially by the Compaq COBOL compiler. Calls to these routines are intercepted and processed by the Compaq COBOL compiler at compile time (not runtime). <>
- CALL identifier (CALL data name) requires that all modules be specified to link the run unit. Since there are no link-time references to routines to be called with CALL identifier, the linkers on OpenVMS and Tru64 UNIX do not resolve these references at link time. Instead, the references are dynamically resolved at run-time using modules which have been explicitly linked into the run unit.

Additional References

- Section 6.8, General Formats and Rules for Statements
- Section 3.1.1, PROGRAM_ID Paragraph paragraph in Chapter 3
- Section 6.1.4, Scope of Statements
- Subsection Section 6.2.6.1, Conventions for Resolving Program_Name References in Section 6.2.6, Scope of Names
- Compaq COBOL User Manual chapter on interprogram communication, including `cobcall, cobcancel,` and `cobfunc` references

Refer to the OpenVMS Calling Standard for more information.

Examples

1. Passing arguments by reference:

       CALL "DATERTN" USING ITEMA ITEMB ITEMC.

2. On OpenVMS, mixing argument-passing mechanisms: Reference arguments are ITEMA, ITEMD, and "PAYROLL". Descriptor arguments are ITEMB, ITEMC, ITEMD, "TOTALS", and ITEMF. The value arguments are ITEME and "995.99". ITEMD is passed twice---by reference and by descriptor. The content arguments are ITEMG and "SUMMARY FLAG".

       CALL "NEWPROG" USING ITEMA
         BY DESCRIPTOR ITEMB ITEMC "TOTALS"
         BY REFERENCE ITEMD "PAYROLL"
         BY VALUE ITEME 995.99
         BY DESCRIPTOR ITEMD ITEMF
         BY CONTENT ITEMG "SUMMARY FLAG".                        <>

3. Mixing argument-passing mechanisms: Reference arguments are ITEMA, ITEMD, and "PAYROLL". The value arguments are ITEME and "995.99". The content arguments are ITEMG and "SUMMARY FLAG".

       CALL "NEWPROG" USING ITEMA
         BY REFERENCE ITEMD "PAYROLL"
         BY VALUE ITEME 995.99
         BY CONTENT ITEMG "SUMMARY FLAG".

4. Calling a program whose name is selected at run time:

       MOVE "PROG009" TO PROG-TO-CALL.
       .
       .
       .
       CALL PROG-TO-CALL USING ITEMA.

5. Receiving a function result:

       CALL "PROG010" USING ITEMA ITEMB "XYZ"
         GIVING ITEMC.

## 6.8.5 CANCEL

Function

The CANCEL statement returns the named program to its initial state.

> ### prog-name

> is a nonnumeric literal or the identifier of an alphanumeric data item. It contains the program-name of the program to be canceled.

Syntax Rules

1. prog-name must be from 1 to 31 characters long. It can contain the characters A to Z, a to z, 0 to 9, dollar sign ($), hyphen (-), and underline (_).
2. prog-name must be the name of a Compaq COBOL program.

General Rules

1. Two or more programs in the run unit can have the same prog-name. The scope of names conventions for prog-names resolve the CANCEL statement references to duplicate prog-names. (See the section on Conventions for Resolving Program-Name References.)
2. Using the scope of names conventions (See Section 6.2.6 ), if prog-name is called again after the CANCEL statement successfully executes, prog-name, and all programs contained within it, are in their initial state.
3. prog-name must be callable by the program that contains the CANCEL statement.
4. The program named by prog-name must not refer directly or indirectly to any program that: (a) has been called, and (b) has not yet executed an EXIT PROGRAM statement.
5. When the CANCEL statement executes, the contents of prog-name are interpreted as follows:
   - Hyphens are treated as underline characters.
   - Lowercase letters are treated as uppercase.
   - Leading and trailing spaces and tab characters are ignored.
6. A called program can be canceled in three ways:
   - By being named in a CANCEL statement
   - When the executable image ends
   - When an EXIT PROGRAM statement executes if the program has the initial attribute
7. When canceling a program these items do not change: (a) the contents of its data items in external data records, and (b) the status and positioning of a file associated with any external file connector.
8. During the execution of a CANCEL statement, an implicit CLOSE statement without any optional phrases executes for each file in the open mode that is associated with an internal file connector in prog-name.

Additional References

- Section 3.1.1, PROGRAM_ID Paragraph paragraph in Chapter 3
- Section 6.1.4, Scope of Statements
- Section 6.2.6, Scope of Names
- Section 6.8.4, CALL statement
- Compaq COBOL User Manual `cobcall, cobcancel, cobfunc` references

Examples

1. `CANCEL "PROG10".`
2. `CANCEL THE-PROG.`
3. `CANCEL SUB-PROG-A "PROG12" SUB-PROG-B.`

## 6.8.6 CLOSE

Function

The CLOSE statement ends processing of reels (or units) and files. It can also perform rewind, lock, and removal operations.

> ### file-name

> is the name of a file described in the Data Division. It cannot be a sort or merge file.

Syntax Rules

1. The REEL or UNIT phrase can be used only for sequential and line sequential files.
2. The words REEL and UNIT are equivalent.

General Rules

1. A CLOSE statement can execute only for an open file.
2. Executing a CLOSE statement updates the value of the FILE STATUS data item associated with the file.
3. The TERMINATE statement must be executed before a CLOSE statement can reference a report file.
4. If an optional file is not present, standard end-of-file processing does not occur.
5. The WITH NO REWIND and FOR REMOVAL phrases have no effect at execution time if they do not apply to the file's storage medium, except as specified in General Rule 2.
6. When the CLOSE statement applies to an output or extend file described with the LINAGE clause, end-of-page processing occurs before the file is closed.
7. After successful CLOSE statement execution (without the REEL or UNIT phrase), the file's record area is no longer available. After unsuccessful execution, record area availability is undefined.
8. After successful CLOSE statement execution (without the REEL or UNIT phrase), the file is no longer: (a) in the open mode or (b) associated with the file connector.
9. If the CLOSE statement has more than one file-name, the statement executes as if there were a separate CLOSE statement for each file-name.
10. In the file-sharing environment, CLOSE statement execution unlocks all locks for file-name.
11. If both the REEL/UNIT and WITH NO REWIND phrases are specified in the same CLOSE statement, the WITH NO REWIND phrase is ignored.
12. To show the effects of CLOSE statements, all files are categorized as follows:
    - Nonreel: a file for which the concepts of rewind and reel have no meaning because of its input or output medium (for example, a terminal device)
    - Sequential single-reel: a sequential file contained entirely on one reel
    - Sequential multireel: a sequential file contained on more than one reel
    - Nonsequential: a file with other than sequential organization, whose medium is on a mass storage device
13. For files specified with a MULTIPLE FILE TAPE clause the NO REWIND phrase, if any, is ignored.
14. Table 6-12 summarizes CLOSE statement results. Symbol definitions follow the table.
    Where definitions differ for input, output, and input-output files, separate definitions appear. Otherwise, a definition applies to files in all open modes.

    Table 6-12 Effects of CLOSE Statement Formats on Files by Category
    | File Category
    --- | ---
    CLOSE Statement Format | Nonreel | Sequential Single-Reel | Sequential Multireel | Nonsequential
    CLOSE | C | C,G | C,G,A | C
    CLOSE WITH LOCK | C,E | C,G,E | C,G,E,A | C,E
    CLOSE WITH NO REWIND | C,H | C,B | C,B,A | X
    CLOSE REEL | F | F,G | F,G | X
    CLOSE REEL FOR REMOVAL | F | F,D,G | F,D,G | X

    1. Previous reels unaffected
       For input and input-output files: All reels in the file before the current reel are processed according to the standard reel swap procedure. However, reels controlled by an earlier CLOSE REEL/UNIT statement are not affected. If other reels in the file follow the current reel, they are not processed.
       For output files: All reels in the file before the current reel are processed according to the standard reel swap procedure. However, reels controlled by an earlier CLOSE REEL/UNIT statement are not affected.
    2. No rewind of current reel
       The position of the current reel remains the same.

    3. Close file
       The file is closed.
    4. Reel/unit removal
       The current reel rewinds and is logically removed from the run unit However, the run unit can access the reel again in its proper order of reels in the file. To do this, the executable image must subsequently execute the following:
       - A CLOSE statement without the REEL/UNIT phrase for the file
       - An OPEN statement for the file
    5. File lock
       The executable image cannot open the file again in its current execution.
    6. Close reel/unit
       For input and input-output files, if the current reel is the last or only reel for the file:
       - A reel swap does not occur.
       - The Current Volume Pointer remains the same.
       - The File Position Indicator denotes that there is no next logical record.
       If another reel follows the current reel for the file:
       - A reel swap occurs.
       - The Current Volume Pointer points to the next reel for the file.
       - The File Position Indicator points to the next record in the file. If there are no records for the current volume, another reel swap occurs.
       For output files (reel/unit media), a reel swap occurs. The Current Volume Pointer points to the new reel.
       Executing the next WRITE statement for the file transfers a logical record to the new reel of the file.
       For output files (nonreel/unit media), execution of this statement is considered successful. The file remains in the open mode and no action takes place, except as specified in General Rule 2.
    7. Rewind
       The current reel (or device) is positioned to its physical beginning.
    8. Optional phrases ignored
       The CLOSE statement is executed as if none of the optional phrases are present.
    24. Invalid
        This is an invalid combination of CLOSE option and file category. It results in FILE STATUS data item value 30.

Technical Note

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

File Status | Meaning
--- | ---
00 | Successful
07 | CLOSE statement with NO REWIND, REEL/UNIT, or FOR REMOVAL phrase referenced a file on a nonreel/unit medium
30 | Any other CLOSE error
42 | File never opened, already closed, or not currently open

Additional Reference

See Section 6.6.8, I-O Status for more information.

## 6.8.7 COMPUTE

Function

The COMPUTE statement evaluates an arithmetic expression and stores the result in one or more data items.

> ### rsult

> is the identifier of an elementary numeric item or elementary numeric edited item. It is the resultant identifier.

> ### arithmetic-expression

> is an expression as described in Section 6.4, Arithmetic Expressions.

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

General Rules

1. The arithmetic expression is evaluated. Its value then replaces the current value of each occurrence of rsult, from left to right.
2. If the arithmetic-expression consists of a single identifier or literal, the COMPUTE statement behaves like a MOVE statement with the single identifier or literal acting as the source operand and each result operand acting as a destination operand.
3. For any rsult specification that includes the word rounded, the value of the expression is rounded before being moved to rsult.

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.7, Overlapping Operands and Incompatible Data

Examples

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

INITIAL VALUES

    03  ITEMA  PIC 999V99 VALUE 2.                      2.00
    03  ITEMB  PIC 999V99 VALUE 3.                      3.00
    03  ITEMC  PIC 999V99 VALUE 4.                      4.00
    03  ITEMD  PIC 999V99 VALUE 5.                      5.00

RESULTS

1. No rounding:

       COMPUTE ITEMC =                            ITEMC = 2.82
          (ITEMA + 6) ** (.1 * ITEMD).

2. With rounding:

       COMPUTE ITEMC ROUNDED =                    ITEMC = 2.83
          (ITEMA + 6) ** (.1 * ITEMD).

3. The ON SIZE ERROR phrase:

       COMPUTE ITEMB = (ITEMA * ITEMD) ** 3       ITEMB = 3.00
          ON SIZE ERROR
            MOVE 100 TO ITEMC.                    ITEMC = 100.00

4. The NOT ON SIZE ERROR phrase:

       COMPUTE ITEMB = (ITEMA * ITEMD) ** 2       ITEMB = 100.00
          ON SIZE ERROR
            MOVE 100 TO ITEMC
          NOT ON SIZE ERROR
            MOVE 200 TO ITEMC.                    ITEMC = 200.00

## 6.8.8 CONTINUE

Function

The CONTINUE statement indicates that no executable statement is present. It causes an implicit control transfer to the next executable statement.

Syntax Rule

The CONTINUE statement can be used wherever a conditional or imperative statement can be used.

General Rule

The CONTINUE statement causes an implicit control transfer to the next executable statement.

Example

    READ FILE-A
      INVALID KEY
        CONTINUE.
    MOVE ...

This example shows how CONTINUE can replace an INVALID KEY imperative statement. Control passes to the MOVE statement whether or not the INVALID KEY condition occurs.

## 6.8.9 DELETE

Function

The DELETE statement logically removes a record from a mass storage file.

> ### file-name

> is the name of a relative or indexed file described in the Data Division. It cannot be the name of a sequential or line sequential file or a sort or merge file.

> ### stment

> is one or more imperative statements executed for an invalid key condition.

> ### stment2

> is one or more imperative statements executed for a not invalid key condition.

Syntax Rules

1. There cannot be an INVALID KEY phrase or a NOT INVALID KEY phrase for a DELETE statement that references a file in sequential access mode.
2. There must be an INVALID KEY phrase if: (a) the file is not in sequential access mode and (b) there is no applicable USE AFTER EXCEPTION procedure.

General Rules

1. The file must be open in I-O mode when the DELETE statement executes.
2. For a file in sequential access mode, a successfully executed READ statement must be the last input-output statement executed for the file before the DELETE statement. The I/O system logically removes the record that the READ statement accessed.
3. For a relative file in random or dynamic access mode, the I/O system logically removes the record identified by the file's RELATIVE KEY data item. If the file does not contain that record, an invalid key condition exists.
4. For an indexed file in random access mode, the I/O system (logically removes the record identified by the file's primary record key data item. If the file does not contain that record, an invalid key condition exists.
5. For an indexed file in dynamic access mode, the behavior depends on the DUPLICATES phrase of the RECORD KEY clause of the SELECT statement. If the primary key allows duplicates, Rule 2 applies. If the primary key does not allow duplicates, Rule 4 applies.
6. After successful DELETE statement execution, the identified record has been logically removed from the file. It is no longer accessible.
7. DELETE statement execution does not affect the contents of the record area. It also does not affect the contents of the data item referred to in the DEPENDING ON phrase of the file's RECORD clause.
8. For sequential access files, DELETE statement execution does not affect the File Position Indicator.
9. For dynamic access files, the File Position Indicator can point to the record to be deleted before the DELETE statement executes. In this case, once the DELETE statement executes, the File Position Indicator:
   - Points to a relative file's next existing record
   - Points to an indexed file's next existing record, as established by the Key of Reference
   - Indicates the at end condition if the file has no next record
   In all other cases, the File Position Indicator is not affected by the execution of a DELETE statement.
10. DELETE statement execution updates the value of the FILE STATUS data item for the file.
11. If there is an applicable USE AFTER EXCEPTION procedure, it executes whenever an input or output condition occurs that would result in a nonzero value in the first character of a FILE STATUS data item. However, it does not execute if the condition is invalid key, and there is an INVALID KEY phrase. If the condition is not invalid key and no applicable USE AFTER EXCEPTION Declarative procedure exists, the run unit terminates abnormally.

See the rules for the INVALID KEY phrase, Section 6.6.10.

Technical Notes

- In a Compaq standard file-sharing environment for relative files, records that are manually locked and then deleted retain a lock on the deleted record. This affects a subsequent WRITE from a different access stream (either from a different file connector in the same run-unit or from a file connector in a different run-unit). A WRITE statement under such conditions gets a file status 92 (record locked by another program). All other statements will treat a record that was locked and subsequently deleted in the same manner as a record that was not locked and subsequently deleted.
- DELETE statement execution can result in the following FILE STATUS data item values:

  File Status | Access Method | Meaning
  --- | --- | ---
  00 | All | Successful
  23 | Rand, Dyn | Record not in file (invalid key)
  43 | Seq | No previous READ or record not locked by prior READ or START
  49 | All | File not open, or incompatible open mode
  92 | All | Record locked by another program
  30 | All | All other permanent errors

- If the current record to be deleted is not locked by the current stream, the delete results in a permanent error. On OpenVMS Alpha systems, RMS-STS indicates the record is not locked.

Additional References

- Section 6.1.4, Scope of Statements
- Section 6.6.8, I-O Status
- Section 6.6.10, INVALID KEY Phrase
- Section 6.8.24, OPEN statement
- Section 6.8.42, USE statement

Previous | Next | Contents | Index