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:

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:

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