Passing file handles to subroutines

In HP COBOL compatibility mode, you can pass the operating system's file handle for an open COBOL file to a subroutine by referring to that file's SELECT name in the CALL statement. One reason for doing this is to call an operating system function that allows the file to retrieve information not available through COBOL. For example:

ENVIRONMENT DIVISION.
FILE-CONTROL.
SELECT MY-FILE
ASSIGN TO DISK
SEQUENTIAL.

DATA DIVISION.
FILE SECTION.
FD MY-FILE.
01 RECORD-1     PIC X(80).

PROCEDURE DIVISION.
MAIN-LOGIC.
   OPEN INPUT MY-FILE.
   CALL "SUB" USING MY-FILE.
   CLOSE MY-FILE.

These rules apply when passing file handles to subroutines:

• For compatibility with HP COBOL, a file handle is automatically passed BY VALUE unless immediately preceded by a BY REFERENCE or BY CONTENT specification. Use BY REFERENCE or BY CONTENT to pass an open file handle to a COBOL subroutine because COBOL routines cannot take BY VALUE parameters.
• If the called subroutine is a COBOL routine, the handle passed is PIC S9(4) COMP-5. You can override this with the compiler option fileIdSize=# where # is the number of bytes you want in the passed integer (2, 4 or 8).
• If the called subroutine is not COBOL, the handle is passed as a signed native integer using the host's default integer size.
• The file handle passed is the host file system's identifying value for the open file. For all current implementations, this is the value returned by the C OPEN function. This may change in a future implementation.
• If the host file system does not have this information available, then -1 is used. This can happen if the host system is not a file (for example, Acu4GL for Oracle) or the host system does not provide a way of obtaining the handle (for example, the C-ISAM interface). Files served by AcuServer also use -1 since there is no useful way to use a remote process' open file handle.
• For Vision files in the multi-file format, the handle used is the handle of the first data segment. This is the same as the file name used when opening the file.
• It is best to avoid performing actual I/O on the file using this file handle because the COBOL file system is unaware of any state changes to the file and may perform incorrectly, potentially leading to data corruption.