COBOL Manual for TNS and TNS/R Programs

Libraries and Utility Routines
HP COBOL Manual for TNS and TNS/R Programs—522555-006
13-100
COBOLSPOOLOPEN
Establishing a Declarative-File Connection
The HP COBOL compilers find the connection between generic file declarative
sections and logical files by examining the context of OPEN statements. A declarative
section preceded by a USE AFTER EXCEPTION PROCEDURE ON OUTPUT
statement is implicitly associated with each file whose name appears in an OPEN
OUTPUT statement. In such cases, the section is called whenever an exception occurs
during execution of an I-O statement for a file that is currently open for output. The
section is not called if the exception occurs in conjunction with a file that could be open
for output but is actually open in some other mode.
The HP COBOL compilers do not find such a connection from the occurrence of an
ENTER COBOLSPOOLOPEN statement; however, an application can instruct the
compiler to establish a declarative-file connection in either of two ways:
•
A declarative section preceded by a USE AFTER EXCEPTION PROCEDURE
file-name-list is explicitly associated with each file whose name appears in
the list.
•
A declarative section preceded by a USE AFTER EXCEPTION PROCEDURE ON
OUTPUT can be associated with a given logical file by inserting an OPEN
OUTPUT file-name statement in a portion of the program that is never
executed.
Although both methods establish the connection in conjunction with WRITE,
LOCKFILE, and CLOSE statements, a failure of the ENTER COBOLSPOOLOPEN
statement does not call the declarative section. The error detection must be
programmed explicitly by including the GIVING error-code phrase in the ENTER
statement and testing the value returned. If the file-status item is present in the
parameter list, a simple success-failure test can be made by examining its value.
Error Code
The error code returned by COBOLSPOOLOPEN can originate in either
COBOLSPOOLOPEN or the spooler. In most cases, it is generated by the spooler and
merely passed on by COBOLSPOOLOPEN.
•
All spooler error codes have a value of at least 512 (%1000). For more information,
see the Guardian Procedure Calls Reference Manual.
•
COBOLSPOOLOPEN returns error code values in the range 1 through 511
(1-%777). For values in the range 1 through 99, refer to the corresponding number
in Section 48, Run-Time Diagnostic Messages.
•
If no fd-name is present, 100 is returned. If the associated file is neither a
process nor a printer, 101 is returned. All nonzero codes imply the open operation
failed.
•
If the owner parameter does not specify a valid group/user combination, 102 is
returned.