HP OpenVMS Systems Documentation
A stack is a LIFO (last-in/first-out) temporary
storage area that the system allocates for every user process. The
system keeps information about each routine call in the current image
on the call stack. Then, each time you call a routine, the system
creates a structure on the stack, defined as a stack
frame and further discussed in the HP OpenVMS Calling Standard and the
OpenVMS Programming Interfaces: Calling a System Routine.
13.2.2 Return of the Function Value
A function is a routine that returns a single value to the calling
routine. The function value represents the return
value that is assigned to the function's identifier during execution.
According to the HP OpenVMS Calling Standard, a function value may be returned as
either an actual value or a condition value that indicates success or
13.2.3 The Argument List
For Alpha and I64 systems, the HP OpenVMS Calling Standard defines a data structure called an argument list as an argument item sequence, consisting of the first six arguments occupying six integer and six floating-point registers (R16-R21 and F16-F21), with additional argument placed on the stack. The argument information is contained in R25 (AI register). The stack pointer is contained in R30.
For detailed information, refer to the HP OpenVMS Calling Standard.
13.3 OpenVMS System Routines (OpenVMS)
System routines are OpenVMS routines that perform common tasks, such as finding the square root of a number or allocating virtual memory. You can call any system routine from your program, provided that HP COBOL supports the data structures required to call the routine.
The system routines used most often are OpenVMS Run-Time Library
routines and system services. System routines are documented in detail
in the OpenVMS RTL Library (LIB$) Manual and the OpenVMS System Services Reference Manual.
13.3.1 OpenVMS Run-Time Library Routines
The OpenVMS Run-Time Library provides commonly used routines that perform a wide variety of functions. These routines are grouped according to the types of tasks they perform, and each group has a prefix that identifies those routines as members of a particular OpenVMS Run-Time Library facility. Table 13-2 lists all the language-independent Run-Time Library facility prefixes and the types of tasks each facility performs.
|Facility Prefix||Types of Tasks Performed|
|CVT$||Library routines that handle floating-point data conversion|
|DTK$||DECtalk routines that are used to control an HP DECtalk device|
Library routines that:
Obtain records from devices
Convert data types for I/O
Obtain system information
Establish condition handlers
Enable detection of hardware exceptions
Process cross-reference data
|MTH$||Mathematics routines that perform arithmetic, algebraic, and trigonometric calculations|
|OTS$||General-purpose routines that perform tasks such as data type conversions as part of a compiler's generated code|
|PPL$||Parallel processing routines that help you implement concurrent programs on single-CPU and multiprocessor systems|
|SMG$||Screen management routines that are used in designing, composing, and keeping track of complex images on a video screen|
|STR$||String manipulation routines that perform such tasks as searching for substrings, concatenating strings, and prefixing and appending strings|
System services are prewritten system routines that perform a variety of tasks, such as controlling processes, communicating among processes, and coordinating I/O.
Unlike the Run-Time Library routines, which are divided into groups by facility, all system services share the same facility prefix (SYS$ on OpenVMS or SYS_ on Tru64 UNIX). However, these services are logically divided into groups that perform similar tasks. Table 13-3 describes these groups.
|Group||Types of Tasks Performed|
|AST||Allows processes to control the handling of asynchronous system traps|
|Change Mode||Changes the access mode of particular routines|
|Condition Handling||Designates condition handlers for special purposes|
|Event Flag||Clears, sets, reads, and waits for event flags, and associates with event flag clusters|
|Information||Returns information about the system, queues, jobs, processes, locks, and devices|
|Input/Output||Performs I/O directly, without going through RMS|
|Lock Management||Enables processes to coordinate access to shareable system resources|
|Logical Names||Provides methods of accessing and maintaining pairs of character-string logical names and equivalence names|
|Memory Management||Increases or decreases available virtual memory, controls paging and swapping, and creates and accesses shareable files of code or data|
|Process Control||Creates, deletes, and controls execution of processes|
|Security||Enhances the security of OpenVMS systems|
|Timer and Time Conversion||Schedules events and obtains and formats binary time values|
The basic steps for calling routines are the same whether you are calling a routine (subprogram) written in COBOL, a routine written in some other language, a system service, or a Run-Time Library routine. There are five steps required to call any system routine:
The following sections outline the steps for calling non-COBOL
13.4.1 Determining the Type of Call (OpenVMS)
Before you call an external routine, you must first determine whether the call should be a procedure call or a function call. In COBOL, a routine that does not return a value should be called as a procedure call. A routine that returns a value should be called as a function call. Thus, a function call returns one of the following:
Although you can call most system routines as a procedure call, it is recommended that you do so only when the system routine does not return a value. By checking the condition value, you can avoid errors.
The OpenVMS documentation on system services and Run-Time Library routines contains descriptions of each system routine and a description of the condition values returned. For example, the RETURNS section for the system routine LIB$STAT_TIMER follows:
Because LIB$STAT_TIMER returns a value, it should be called as a function. If a system routine contains the following description under the RETURNS section, you should call the system routine as a procedure call: