HP OpenVMS Systems Documentation

HP COBOL
User Manual

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

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