COBOL Manual for TNS/E Programs (H06.08+, J06.03+)

Functions (Routines That Return Values)
A function is a routine that returns a value to the calling program. COBOL has no mechanism for
returning a function’s value to the calling program, but HP COBOL has two:
• GIVING Phrase
• Special Register RETURN-CODE
GIVING Phrase
The GIVING phrase allows you to specify a data item, return-value, to hold the value that the
function returns. The storage operation is performed after any necessary scaling and follows the
rules for an elementary MOVE TO statement (for these rules, see MOVE TO (page 368)).
Special Register RETURN-CODE
The special register RETURN-CODE is accessible to an HP COBOL program that was compiled
with the PORT directive and uses the X/Open CALL statement to call a function.
The value of the function is returned in the special register RETURN-CODE, whose description is:
01 RETURN-CODE EXTERNAL PICTURE S9(5) COMPUTATIONAL.
If the value of the function is greater than 99,999, arithmetic overflow occurs.
If the calling program cannot access RETURN-CODE, the value of RETURN-CODE is unchanged.
Operating System Routines
Operating system routines are written in pTAL, HP C, and HP C++. The language in which an
operating system routine is written does not matter to the HP COBOL program that calls it. Operating
system routines execute in system code space, using both system data space (for system tables)
and user data space (for temporary storage). When an HP COBOL program calls an operating
system routine, it uses the ENTER statement.
Some operating system routines never need to be called by HP COBOL programs—file system
routines, for example. File system routines are called by the HP COBOL run-time routines to do
their input and output operations. Although it is possible to call file system routines explicitly from
an HP COBOL program, you are advised not to apply both HP COBOL I-O statements and explicit
calls to file system routines to the same file, as the HP COBOL run-time routines do significant
preprocessing and postprocessing.
NOTE: If you use operating system routines to do nowait I-O (you call a routine to do an input
or output operation and then call AWAITIO to wait for the operation to finish), be aware that the
HP COBOL run-time routines perform nowait I-O in some cases. The AWAITIO routine can wait
for any I-O operation to complete, or wait for the I-O operation on a specific file to complete. It is
best to apply AWAITIO to a specific file. Using the command PARAM WAITED-IO ON allows you
some latitude, however.
Examples of operating system routines that are useful to an HP COBOL program are ABEND,
which signals an abnormal termination, and PURGEDATA, which erases all data in a file but does
not purge the file itself.
Topics:
• Parameters
• Resolution
• Extensible and Variable Parameter Lists
• Generations of Operating System Routines
Calling Non-COBOL Routines 799