HP OpenVMS Systems Documentation

HP COBOL
User Manual

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 failure.

13.2.3 The Argument List

You can use an argument list to pass information to a routine and receive results.

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.

**Table 13-2 Run-Time Library Facilities (OpenVMS)**
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
LIB$	Library routines that: Obtain records from devices Manipulate strings Convert data types for I/O Allocate resources Obtain system information Signal exceptions 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

13.3.2 System Services

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.

**Table 13-3 System Services (OpenVMS)**
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

13.4 Calling Routines

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:

Determining the type of call
Defining the arguments
Calling the routine or service
Checking the condition value, if applicable
Locating the result

The following sections outline the steps for calling non-COBOL routines.

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:

A function value (a COMP integer, COMP-1, or COMP-2 number). For example, on OpenVMS the call LIB$INDEX returns an integer value.
A return status, which is a longword (PIC 9(5) to 9(9) USAGE IS COMP) condition value that indicates the program has either successfully executed or failed. For example, on OpenVMS, LIB$GET_INPUT returns a return status.

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:

RETURNS

OpenVMS usage:
type:
access:
mechanism:

cond_value
longword (unsigned)
write only
by value

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: