[an error occurred while processing this directive]

HP OpenVMS Systems Documentation
Content starts here

HP COBOL
Reference Manual

Previous Contents Index

Technical Notes

  • On Alpha and I64 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 HP 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 HP COBOL compiler. Calls to these routines are intercepted and processed by the HP 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

Refer to the HP 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 an HP 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

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.
    1. No rewind of current reel
      The position of the current reel remains the same.

    Previous Next Contents Index