# Compaq COBOL
User Manual

Previous | Contents | Index

## 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 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 systems, the 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 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 Compaq 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 a Compaq 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:

1. Determining the type of call
2. Defining the arguments
3. Calling the routine or service
4. Checking the condition value, if applicable
5. 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:

RETURNS

None. |

## 13.4.2 Defining the Argument (OpenVMS)

Most system routines have one or more arguments. These arguments are used to pass information to the system routine and to obtain information from it. Arguments can be either required or optional, and each argument has the following characteristics:

- Access type (read, write, modify...)
- Data type (floating point, longword...)
- Passing mechanisms (by value, by reference, by descriptor...)
- Argument form (scalar, array, string... )

To determine which arguments are required by a routine, check the format description of the routine in the OpenVMS documentation on system services or Run-Time Library routines. For example, the format for LIB$STAT_TIMER is as follows:

    LIB$STAT_TIMER  code ,value-argument [,handle-address]

The handle-address argument appears in square brackets ([]), indicating that it is an optional argument. Hence, when you call the system routine LIB$STAT_TIMER, only the first two arguments are required.

Once you have determined which arguments you need, read the argument description for information on how to call that system routine. For example, the system routine LIB$STAT_TIMER provides the following description of the code argument:

code |
OpenVMS Usage: type: access: mechanism: | longword_signed longword integer (signed) read only by reference

    Code that specifies the statistic to be returned. The code
    argument contains the address of a signed longword
    integer that is this code. It must be an integer from 1 to 5.

After you check the argument description, refer to Table 13-4 for the COBOL equivalent of the argument description. For example, the code argument description lists the OpenVMS usage entry longword_signed. To define the code argument, use the COBOL equivalent of longword_signed:

    01 LWS    PIC S9(9) COMP.

Follow the same procedure for the value argument. The description of value contains the following information:

value-argument |
OpenVMS Usage: type: access: mechanism: | user_arg longword (unsigned) write only by reference

    The statistic returned by LIB$STAT_TIMER. The value-argument
    argument contains the address of a longword or quadword
    that is this statistic.  All statistics are longword integers
    except elapsed time, which is a quadword.

For the value-argument argument, the OpenVMS usage, user_arg, indicates that the data type returned by the routine is dependent on other factors. In this case, the data type returned is dependent upon which statistic you want to return. For example, if the statistic you want to return is code 5, page fault count, you must use a signed longword integer. Refer to Table 13-4 to find the following definition for a longword_signed:

    01 LWS    PIC S9(9) COMP.

Regardless of which Run-Time Library routine or system service you call, you can find the definition statements for the arguments in the OpenVMS usage in Table 13-4.

## 13.4.3 Calling the External Routine (OpenVMS)

Once you have decided which routine you want to call, you can access the routine using the CALL statement. You set up the call to the routine or service the same way you set up any call in COBOL. To determine the syntax of the CALL statement for a function call or a procedure call, refer to the Compaq COBOL Reference Manual, and see the examples in this chapter.

Remember, you must specify the name of the routine being called and all parameters required for that routine. Make sure the data types and passing mechanisms for the parameters you are passing coincide with those defined in the routine.

## 13.4.4 Calling System Routines (OpenVMS)

The basic steps for calling system routines are the same as those for calling any routine. However, when calling system routines, you need to provide some additional information discussed in the following sections.

### 13.4.4.1 System Routine Arguments (OpenVMS)

All OpenVMS system routine arguments are described in terms of the following information:

- OpenVMS usage
- Data type
- Type of access allowed
- Passing mechanism

OpenVMS usages are data structures layered on the standard OpenVMS data types. For example, the OpenVMS usage mask_longword signifies an unsigned longword integer used as a bit mask, and the OpenVMS usage floating_point represents any OpenVMS floating-point data type. Table 13-4 lists the OpenVMS usages and the COBOL statements you need to implement them.

Table 13-4 COBOL Implementation of the OpenVMS Data Types (OpenVMS)
OpenVMS Data Type | COBOL Definition
--- | ---
access_bit_names | NA ... PIC X(128). 1
access_mode | NA ... PIC X. 1 access_mode is usually passed BY VALUE as PIC 9(9) COMP.
address | USAGE POINTER.
address_range | 01 ADDRESS-RANGE. 02 BEGINNING-ADDRESS USAGE POINTER. 02 ENDING-ADDRESS USAGE POINTER.
arg_list | NA ... Constructed by the compiler as a result of using the COBOL CALL statement. An argument list may be created as follows, but may not be referenced by the COBOL CALL statement. 01 ARG-LIST. 02 ARG-COUNT PIC S9(9) COMP. 02 ARG-BY-VALUE PIC S9(9) COMP. 02 ARG-BY-REFERENCE USAGE POINTER 02 VALUE REFERENCE ARG-NAME. ... continue as needed
ast_procedure | 01 AST-PROC PIC 9(9) COMP. 2
boolean | 01 BOOLEAN-VALUE PIC 9(9) COMP. 2
byte_signed | NA ... PIC X. 1
byte_unsigned | NA ... PIC X. 1
channel | 01 CHANNEL PIC 9(4) COMP. 2
char_string | 01 CHAR-STRING PIC X to PIC X(268435455).
complex_number | NA ... PIC X(n) where n is length. 1
cond_value | 01 COND-VALUE PIC 9(9) COMP. 2
context | 01 CONTEXT PIC 9(9) COMP. 2
date_time | NA ... PIC X(8). 1
device_name | 01 DEVICE-NAME PIC X(n) where n is length.
d_floating | 01 D-FLOAT USAGE COMP-2. (when /FLOAT=D_FLOAT)
ef_cluster_name | 01 CLUSTER-NAME PIC X(n) where n is length.
ef_number | 01 EF-NO PIC 9(9) COMP. 2
exit_handler_block | NA ... PIC X(n) where n is length. 1
fab | NA ... Too complex for general COBOL use. Most of a FAB structure can be described by a lengthy COBOL record description, but such a FAB cannot then be referenced by a COBOL I-O statement. It is much simpler to do the I-O completely within COBOL, and let the COBOL compiler generate the FAB structure, or do the I-O in another language.
file_protection | 01 FILE-PROT PIC 9(4) COMP. 2
function_code | 01 FUNCTION-CODE. 02 MAJOR-FUNCTION PIC 9(4) COMP. 2 02 SUB-FUNCTION PIC 9(4) COMP. 2
f_floating | 01 F-FLOAT USAGE COMP-1. (when /FLOAT=D_FLOAT or /FLOAT=G_FLOAT)
g_floating | 01 G-FLOAT USAGE COMP-2. (when /FLOAT=G_FLOAT)
identifier | 01 ID PIC 9(9) COMP. 2
io_status_block | 01 IOSB. 02 COND-VAL PIC 9(4) COMP. 2 02 BYTE-CNT PIC 9(4) COMP. 2 02 DEV-INFO PIC 9(9) COMP. 2
item_list_2 | 01 ITEM-LIST-TWO. 02 ITEM-LIST OCCURS n TIMES. 04 COMP-LENGTH PIC S9(4) COMP. 04 ITEM-CODE PIC S9(4) COMP. 04 COMP-ADDRESS PIC S9(9) COMP. 02 TERMINATOR PIC S9(9) COMP VALUE 0.
item_list_3 | 01 ITEM-LIST-3. 02 ITEM-LIST OCCURS n TIMES. 04 BUF-LEN PIC S9(4) COMP. 04 ITEM-CODE PIC S9(4) COMP. 04 BUFFER-ADDRESS PIC S9(9) COMP. 04 LENGTH-ADDRESS PIC S9(9) COMP. 02 TERMINATOR PIC S9(9) COMP VALUE 0.
item_list_pair | 01 ITEM-LIST-PAIR. 02 ITEM-LIST OCCURS n TIMES. 04 ITEM-CODE PIC S9(9) COMP. 04 ITEM-VALUE PIC S9(9) COMP. 02 TERMINATOR PIC S9(9) COMP VALUE 0.
item_quota_list | NA
lock_id | 01 LOCK-ID PIC 9(9) COMP. 2
lock_status_block | NA
lock_value_block | NA
logical_name | 01 LOG-NAME PIC X TO X(255).
longword_signed | 01 LWS PIC S9(9) COMP.
longword_unsigned | 01 LWU PIC 9(9) COMP. 2
mask_byte | NA ... PIC X. 1
mask_longword | 01 MLW PIC 9(9) COMP. 2
mask_quadword | 01 MQW PIC 9(18) COMP. 2
mask_word | 01 MW PIC 9(4) COMP. 2
null_arg | CALL ... USING OMITTED or PIC S9(9) COMP VALUE 0 passed USING BY VALUE.
octaword_signed | NA
octaword_unsigned | NA
page_protection | 01 PAGE-PROT PIC 9(9) COMP. 2
procedure | 01 ENTRY-MASK PIC 9(9) COMP. 2
process_id | 01 PID PIC 9(9) COMP. 2
process_name | 01 PROCESS-NAME PIC X TO X(15).
quadword_signed | 01 QWS PIC S9(18) COMP.
quadword_unsigned | 01 QWU PIC 9(18) COMP. 2
rights_holder | 01 RIGHTS-HOLDER. 02 RIGHTS-ID PIC 9(9) COMP. 2 02 ACCESS-RIGHTS PIC 9(9) COMP. 2
rights_id | 01 RIGHTS-ID PIC 9(9) COMP. 2
rab | NA ... Too complex for general COBOL use. Most of a RAB structure can be described by a lengthy COBOL record description, but such a RAB cannot then be referenced by a COBOL I-O statement. It is much simpler to do the I-O completely within COBOL, and let the COBOL compiler generate the RAB structure, or do the I-O in another language.
section_id | 01 SECTION-ID PIC 9(18) COMP. 2
section_name | 01 SECTION-NAME PIC X to X(43).
system_access_id | 01 SECTION-ACCESS-ID PIC 9(18) COMP. 2
s_floating | 01 S-FLOAT USAGE COMP-1. (when /FLOAT=IEEE_FLOAT)
time_name | 01 TIME-NAME PIC X(n) where n is the length.
t_floating | 01 T-FLOAT USAGE COMP-2. (when /FLOAT=IEEE_FLOAT )
uic | 01 UIC PIC 9(9) COMP. 2
user_arg | 01 USER-ARG PIC 9(9) COMP. 2
varying_arg | Dependent upon application.
vector_byte_signed | NA ... 3
vector_byte_unsigned | NA ... 3
vector_longword_signed | NA ... 3
vector_longword_unsigned | NA ... 3
vector_quadword_signed | NA ... 3
vector_quadword_unsigned | NA ... 3
vector_word_signed | NA ... 3
vector_word_unsigned | NA ... 3
word_signed | 01 WS PIC S9(4) COMP.
word_unsigned | 01 WS PIC 9(4) COMP. 2

1Most OpenVMS data types not directly supported in COBOL can be represented as an alphanumeric data item of a certain number of bytes. While COBOL does not interpret the data type, it may be used to pass objects from one language to another.
2Although unsigned computational data structures are not directly supported in COBOL, you may substitute the signed equivalent provided you do not exceed the range of the signed data structure.
3COBOL does not permit the passing of variable-length data structures.

Previous | Next | Contents | Index