| Previous | Contents | Index |
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. 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, see the OpenVMS Calling Standard.
13.3 OpenVMS Alpha System Routines (OpenVMS)
System routines are OpenVMS Alpha 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 Alpha 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 Alpha Run-Time Library Routines
The OpenVMS Alpha 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 Alpha 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 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 |
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 Alpha 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 Alpha 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
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 Alpha 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:
|
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:
| None. |
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 Alpha 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 Alpha 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 Alpha 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, see the Compaq COBOL Reference Manual, and refer to 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 Alpha system routine arguments are described in terms of the following information:
OpenVMS Alpha usages are data structures layered on the standard OpenVMS Alpha data types. For example, the OpenVMS Alpha usage mask_longword signifies an unsigned longword integer used as a bit mask, and the OpenVMS Alpha usage floating_point represents any OpenVMS Alpha floating-point data type. Table 13-4 lists the OpenVMS Alpha usages and the COBOL statements you need to implement them.
| OpenVMS Alpha 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(65535). |
| 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 |
| Previous | Next | Contents | Index |