Some routines may allow an argument list to be truncated in a specified location. For example:

DECLARE LIB$GET_INPUT ENTRY (ANY CHARACTER(*), ANY CHARACTER(*) OPTIONAL TRUNCATE, FIXED BINARY(15) OPTIONAL TRUNCATE);

This declaration of the Get Line from SYS$INPUT routine (LIB$GET_INPUT) specifies that the argument list may vary in length. In fact, LIB$GET_INPUT has three parameters, but the last two parameters are optional.

When you invoke such a routine omitting trailing arguments, you do not have to account for all the arguments in the procedure invocation argument list. For example, the LIB$GET_INPUT routine can be invoked with trailing arguments omitted:

CALL LIB$GET_INPUT(GET_STRING);

The variable GET_STRING is specified for the first argument. The other two arguments are not specified. Unlike the case with the OPTIONAL attribute, the compiler will not create blank entries in the argument vector passed to the called program.

11.2.5 Summary of Rules for Passing Parameters

You can specify the passing mechanism-reference, value, or descriptor-for a parameter in three ways:

• Use an attribute.
• Use a built-in function.
• Use a default.

The following rules and examples explain these three alternatives.

• Specify the REFERENCE, VALUE, or DESCRIPTOR attribute explicitly when you declare the parameter. For example:

  CHAR(*) REFERENCE (*) FIXED BINARY REFERENCE FIXED BIN(31) VALUE BIT(32) ALIGNED VALUE FLOAT BIN(23) VALUE ENTRY (FIXED BIN) RETURNS(FIXED BIN) VALUE FIXED BINARY DESCRIPTOR FIXED DECIMAL(10,2) DESCRIPTOR CHAR(10) DESCRIPTOR

• Use the REFERENCE, VALUE, or DESCRIPTOR built-in function at the call, overriding whatever passing mechanism would otherwise be used. For example:

  CALL E (REF(10)); CALL FOO (REF(E)); CALL I (VALUE(10)); CALL FOO (VALUE(E)); CALL E (DESC(10)); CALL FOO (DESC(E));

  
  The built-in function completely overrides the parameter declaration and consequently no type conversion is performed. The built-in function evaluates a numeric constant as FIXED BINARY(31,0) rather than FIXED DECIMAL. For example, REF(10) passes a longword containing the binary value 10 by reference.

• Use the default passing mechanism for the data type of the parameter. By default, parameters are passed by reference except for unaligned bit strings and parameters containing asterisk (*) extents, which are passed by descriptor. (Value is never the default passing mechanism.) For example, parameters of the following types are all passed by reference:

  CHAR(10) VARYING BIT(22) ALIGNED (10) FIXED DEC (20,-1:7) FLOAT CHAR 1,2 (10) FIXED, 2 (8) FLOAT

  
  Parameters of the following types are passed by descriptor, by default, because they contain asterisk (*) extents or an unaligned bit string:

  CHAR(*) BIT(10) UNALIGNED (*) FIXED BIN 1,2(*) FIXED DEC, 2(10) FLOAT

Restrictions

For passing by reference, a parameter must be addressable. Thus, entry constants, file constants, and unaligned bit strings cannot be passed by reference.

For passing by value, a parameter cannot occupy more than 32 bits and must be one of the following types:

• FIXED BINARY(m), where m is less than or equal to 31
• FLOAT BINARY(n), where n is less than or equal to 24
• BIT(p) or BIT(p) ALIGNED, where p is less than or equal to 32
• ENTRY
• OFFSET
• POINTER

The OpenVMS Run-Time Library is a library of prewritten, 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 11-3 lists all the language-independent run-time library facility prefixes and the types of tasks each facility performs.

Table 11-3 Run-Time Library Facilities

Facility Prefix	Types of Tasks Performed
DTK$	DECtalk routines that are used to control Digital's 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, and 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
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

The file SYS$LIBRARY:PLI$STARLET.TLB defines the entry points for these routines.

11.4 OpenVMS System Service Routines

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 OpenVMS Run-Time Library routines, which are divided into groups by facility, all system services share the same facility prefix (SYS$). These system services are logically divided into groups that perform similar tasks. Table 11-4 describes these groups.

Table 11-4 System Services

Group	Types of Tasks Performed
AST	Allows processes to control the handling of ASTs
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 VAX 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
Time and Timing	Schedules events, and obtains and formats binary time values

The file SYS$LIBRARY:PLI$STARLET.TLB defines the entry points for these routines.

11.5 OpenVMS Utility Routines

Utility routines are prewritten system routines that you can use to perform a variety of tasks such as sorting and library maintenance. Table 11-5 lists some of the commonly used OpenVMS utilities.

Table 11-5 OpenVMS Utilities

Utility Prefix	Types of Tasks Performed
ACLEDIT$	Callable interface to the Access Control List Editor
CLI$	Command line parsing
LBR$	Library manipulation
PSM$	Print Symbiont modification
SMB$	Job controller and symbiont process interface
SOR$	Sort/Merge procedures
TPU$	Callable interface to the DEC Text Processing Utility

The file SYS$LIBRARY:PLI$STARLET.TLB defines all of the entry points for these routines.

11.5.1 OpenVMS SORT/MERGE Routines

The OpenVMS SORT Utility (SORT) provides a range of sorting capabilities and options. You can use the SORT program in two ways:

• At the DCL command level, you can invoke the DCL command SORT. By specifying input and output files and sorting options, you can perform sorting functions interactively from the terminal.
• In a PL/I program, you can call SORT routines.

The SORT routines can be used in either of two sequences:

• You can sort all of the records in an entire file. This process is similar to calling SORT from the DCL command level to sort a file.
• You can process the records in a file, pass them to SORT one at a time, and request SORT to merge and sort the records and then to return them one at a time. This process allows you to perform some intermediate operation on each record before initiating the actual sorting of the records.

Examples of calling SORT routines are included in Section 11.8 of this chapter.

11.6 Calling Routines

The basic steps for calling routines are the same whether you are calling a routine written in PL/I, a routine written in some other OpenVMS language, a system service, a utility routine, or an OpenVMS Run-Time Library routine. The following sections outline the procedures for calling non-PL/I routines.

11.6.1 Determining the Type of Call

Before you call an external routine, you must first determine whether the call should be a procedure call or a function call. You should call a routine as a procedure if it does not return a value. You should call a routine as a function if it returns any type of value.

11.6.2 Declaring an External Routine and Its Arguments

To call a routine written in another OpenVMS language, or to call a system routine, you need to declare the routine as an external procedure or function and to declare the data types and passing mechanisms of its arguments. Note that arguments can be either required or optional.

You should include the following information in an external routine declaration:

• The name of the routine
• The data types of all the routine parameters
• The passing mechanisms for all the routine parameters, provided that the routine is not written in PL/I

Once you have declared a routine, you can call it. To call a procedure, you use the CALL statement. To call a function, you can use a function invocation either in an assignment statement or as an argument in another routine call. In either case, 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 actual parameters you are passing coincide with those you declared earlier, and with those declared in the routine.

If you do not want to specify a value for a required parameter, you can pass a null argument by inserting a comma (,) as a placeholder in the argument list. If you use any passing mechanism other than the default, you must specify the passing mechanism in the CALL statement or the function call.

At this point, the routine being called receives control, executes, and then returns control to the calling routine at the next statement after the CALL statement or function call.

11.6.4 Calling System Routines

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

11.6.4.1 Declaring System Routines

The default PL/I text library PLI$STARLET.TLB contains declarations for all the system routines as external entries. The text module names are most often the same as the routine entry points. Thus, to include the declaration of a system service you are going to use, you specify a %INCLUDE statement as in this example:

%INCLUDE SYS$TRNLNM;

The PL/I compilers, by default, locate the module SYS$TRNLNM in PLI$STARLET.TLB during compilation.

In PLI$STARLET.TLB, any system service that has a wait for event flag version is found in the same module as the version without the wait. Thus, to get the definition of any wait ("W") form, you need to use the base (nonwait) form of the service in the %INCLUDE statement. For example, to get the definition for SYS$GETJPIW, you should use the following:

%INCLUDE SYS$GETJPI;

Global symbol definitions for the entry vectors of all system services are located in the default system object module library, STARLET.OLB, in SYS$LIBRARY. When you link a PL/I program, the linker searches this library by default.

11.6.4.2 System Routine Arguments

All the 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 that are layered on the standard OpenVMS data types. For example, the OpenVMS usage mask_longword signifies an unsigned longword integer that is used as a bit mask, and the OpenVMS usage floating_point represents any OpenVMS floating-point data type. Table 11-6 lists all the OpenVMS usages and the PL/I statements you need to implement them. (The callout numbers in Table 11-6 are keyed to the list following the table.)

Table 11-6 PL/I Implementation of OpenVMS Usages

OpenVMS Data Type	Declaration
access_bit_names	1 ACCESS_BIT_NAMES(32), 2 LENGTH FIXED BINARY(15), 2 DTYPE FIXED BINARY(7) INITIAL((32)DSC$K_DTYPE_T), 2 CLASS FIXED BINARY(7) INITIAL((32)DSC$K_CLASS_S), 2 CHAR_PTR POINTER; (6)
	The length of the LENGTH field in each element of the array should correspond to the length of a string of characters pointed to by the CHAR_PTR field. You can use the constants DST$K_CLASS_S and DST$K_DTYPE_T by including the module $DSCDEF from PLI$STARLET or by declaring them GLOBALREF FIXED BINARY(31) VALUE.
access_mode	FIXED BINARY(7) (The constants for this type- PSL$C_KERNEL, PSL$C_EXEC, PSL$C_SUPER, PSL$C_USER-are declared in module $PSLDEF in PLI$STARLET.) (1)
address	POINTER
address_range	(2) POINTER (6)
arg_list	1 ARG_LIST BASED, 2 ARGCOUNT FIXED BINARY(31), 2 ARGUMENT (X REFER (ARGCOUNT)) POINTER; (6)
	If the arguments are passed by value, it may be appropriate to change the type of the ARGUMENT field of the structure. Alternatively, you can use the POSINT, INT, or UNSPEC built-in functions/ pseudovariables to access the data. X should be an expression with a value in the range 0-255 at the time the structure is allocated.
ast_procedure	PROCEDURE or ENTRY (2)
boolean	BIT ALIGNED (1)
byte_signed	FIXED BINARY(7)
byte_unsigned	FIXED BINARY(7) (3)
channel	FIXED BINARY(15)
char_string	CHARACTER(n) (4)
complex_number	(2) FLOAT BINARY(n) or 1 CPLX, 2 REAL FLOAT BIN(n), 2 IMAG FLOAT BIN(n); (See floating_point for values of n.)
cond_value	See module STS$VALUE in PLI$STARLET (6)
context	FIXED BINARY(31)
date_time	BIT(64) ALIGNED (5)
device_name	CHARACTER(n) (4)
ef_cluster_name	CHARACTER(n) (4)
ef_number	FIXED BINARY(31)
exit_handler_block	1 EXIT_HANDLER_BLOCK BASED, 2 FORWARD_LINK POINTER, 2 HANDLER POINTER, 2 ARGCOUNT FIXED BINARY(31), 2 ARGUMENT (n REFER (ARGCOUNT)) POINTER; (6) Replace n with an expression that will yield a value between 0 and 255 at the time the structure is allocated.
fab	See module $FABDEF in PLI$STARLET (6)
file_protection	BIT(16) ALIGNED (1)
floating_point	FLOAT BINARY(n) The values for n are as follows: 1 <= n <= 24 - F floating or S floating (AXP) 25 <= n <= 53 - D floating or T floating (AXP) 25 <= n <= 53 - G floating (with /G_FLOAT) 54 <= n <= 113 - H floating (VAX)
function_code	BIT(32) ALIGNED
identifier	POINTER
io_status_block	Because there are different formats for I/O status blocks for various system services, different definitions will be appropriate for different uses. Some of the common formats are shown here. (6) 1 IOSB_SYS$GETSYI, 2 STATUS FIXED BINARY(31), 2 RESERVED FIXED BINARY(31); 1 IOSB_TTDRIVER_A, 2 STATUS FIXED BINARY(15), 2 BYTE_COUNT FIXED BINARY(15), 2 MBZ FIXED BINARY(31) INITIAL(0); 1 IOSB_TTDRIVER_B, 2 STATUS FIXED BINARY(15), 2 TRANSMIT_SPEED FIXED BINARY(7), 2 RECEIVE_SPEED FIXED BINARY(7), 2 CR_FILL FIXED BINARY(7), 2 LF_FILL FIXED BINARY(7), 2 PARITY_FLAGS FIXED BINARY(7), 2 MBZ FIXED BINARY(7) INITIAL(0);
item_list_2	1 ITEM_LIST_2, 2 ITEM(SIZE), 3 COMPONENT_LENGTH FIXED BINARY(15), 3 ITEM_CODE FIXED BINARY(15), 3 COMPONENT_ADDRESS POINTER, 2 TERMINATOR FIXED BINARY(31) INITIAL(0); (6) Replace SIZE with the number of items you want.
item_list_3	1 ITEM_LIST_3, 2 ITEM(SIZE), 3 BUFFER_LENGTH FIXED BINARY(15), 3 ITEM_CODE FIXED BINARY(15), 3 BUFFER_ADDRESS POINTER, 3 RETURN_LENGTH POINTER, 2 TERMINATOR FIXED BINARY(31) INITIAL(0); (6) Replace SIZE with the number of items you want.
item_list_pair	1 ITEM_LIST_PAIR, 2 ITEM(SIZE), 3 ITEM_CODE FIXED BINARY(31), 3 ITEM UNION, 4 INTEGER FIXED BINARY(31), 4 REAL FLOAT BINARY(24), 2 TERMINATOR FIXED BINARY(31) INITIAL(0); (6) Replace SIZE with the number of items you want.
item_quota_list	1 ITEM_QUOTA_LIST, 2 QUOTA(SIZE), 3 NAME FIXED BINARY(7), 3 VALUE FIXED BINARY(31), 2 TERMINATOR FIXED BINARY(7) INITIAL(PQL$_LISTEND); (6) Replace SIZE with the number of quota entries that you want to use. The constant PQL$_LISTEND can be used by including the module $PQLDEF from PLI$STARLET or by declaring it GLOBALREF FIXED BINARY(31) VALUE.
lock_id	FIXED BINARY(31)
lock_status_block	1 LOCK_STATUS_BLOCK, 2 STATUS_CODE FIXED BINARY(15), 2 RESERVED FIXED BINARY(15), 2 LOCK_ID FIXED BINARY(31); (6)
lock_value_block	The declaration of an item of this structure will depend on the use of the structure, because the OpenVMS system does not interpret the value. (6)
logical_name	CHARACTER(n) (4)
longword_signed	FIXED BINARY(31)
longword_unsigned	FIXED BINARY(31) (3)
mask_byte	BIT(8) ALIGNED
mask_longword	BIT(32) ALIGNED
mask_quadword	BIT(64) ALIGNED
mask_word	BIT(16) ALIGNED
null_arg	Omit the corresponding parameter in the call. For example, FOO(A,,B) would omit the second parameter.
octaword_signed	BIT(128) ALIGNED (5)
octaword_unsigned	BIT(128) ALIGNED (3) (5)
page_protection	FIXED BINARY(31) (The constants for this type are declared in module $PRTDEF in PLI$STARLET.)
procedure	PROCEDURE or ENTRY (2)
process_id	FIXED BINARY(31)
process_name	CHARACTER(n) (4)
quadword_signed	BIT(64) ALIGNED (5)
quadword_unsigned	BIT(64) ALIGNED (3) (5)
rights_holder	1 RIGHTS_HOLDER, 2 RIGHTS_ID FIXED BINARY(31), 2 ACCESS_RIGHTS BIT(32) ALIGNED; (6)
rights_id	FIXED BINARY(31)
rab	See module $RABDEF in PLI$STARLET (6)
section_id	BIT(64) ALIGNED
section_name	CHARACTER(n) (4)
system_access_id	BIT(64) ALIGNED
time_name	CHARACTER(n) (4)
uic	FIXED BINARY(31)
user_arg	ANY
varying_arg	ANY with OPTIONS(VARIABLE) on the routine declaration
vector_byte_signed	(n) FIXED BINARY(7) (7)
vector_byte_unsigned	(n) FIXED BINARY(7) (3) (7)
vector_longword_signed	(n) FIXED BINARY(31) (7)
vector_longword_unsigned	(n) FIXED BINARY(31) (3) (7)
vector_quadword_signed	(n) BIT(64) ALIGNED (5) (7)
vector_quadword_unsigned	(n) BIT(64) ALIGNED (3) (5) (7)
vector_word_signed	(n) FIXED BINARY(15) (7)
vector_word_unsigned	(n) FIXED BINARY(15) (3) (7)
word_signed	FIXED BINARY(15)
word_unsigned	FIXED BINARY(15) (3)