HP OpenVMS Systems Documentation

OpenVMS Programming Concepts Manual

You must specify the arguments according to the VAX MACRO assembler rules for specifying and addressing operands.

The way to specify a particular argument depends on the following factors:

• Whether the system service requires an address or a value as the argument. In the OpenVMS System Services Reference Manual, the descriptions of the arguments following a system service macro format always indicate whether the argument is an address. A Boolean value, number, or mask takes a value as the argument.
• The system service macro being used. The expansions of the $name and $name_S macros in the examples in Section D.1.1 show the code generated by each macro.

If you are unsure whether you specified a value or an address argument correctly, you can assemble the program with the .LIST MEB directive to check the macro expansion. See the VAX MACRO and Instruction Set Reference Manual for details.

D.1.3 Defining Symbolic Names for Argument List Offsets: $name and $nameDEF

You can refer symbolically to arguments in the argument list. Each argument in an argument list has an offset from the beginning of the list; a symbolic name is defined for the numeric offset of each argument. If you use the symbolic names to refer to the arguments in a list, you do not have to remember the numeric offset (which is based on the position of the argument shown in the macro format).

There are two additional advantages to referring to arguments by their symbolic names:

• Your program is easier to read.
• If an argument list for a system service changes with a later release of a system, the symbols remain the same.

You form the offset names for all system service argument lists by following the service macro name with $_ and the keyword name of the argument. In the following example, name is the name for the system service macro and keyword is the keyword argument:

Similarly, you can define a symbolic name for the number of arguments a particular macro requires, as follows:

You can define symbolic names for argument list offsets automatically whenever you use the $name macro for a particular system service. You can also define symbolic names for system service argument lists using the $nameDEF macro. This macro does not generate any executable code; it merely defines the symbolic names so they can be used later in the program. For example:

$QIODEF

This macro defines the symbol QIO$_NARGS and the symbolic names for the $QIO argument list offsets.

You may need to use the $nameDEF macro either if you specify an argument list to a system service without using the $name macro or if a program refers to an argument list in a separately assembled module.

For example, the $READEF and $READEFDEF macros define the values listed in the following table.

Thus, you can specify the $READEF macro to build an argument list for a $READEF system service call, as follows:

READLST:   $READEF  EFN=1,STATE=TEST1

Later, the program may want to use a different value for the state argument to call the service. The following lines show how you can do this with a call to the $name_G macro.

     MOVAL   TEST2,READLST+READEF$_STATE
     $READEF_G READLST

The MOVAL instruction replaces the address TEST1 in the $READEF argument list with the address TEST2; the $READEF_G macro calls the system service with the modified list.

D.2 Using Macros to Call System Services

You can use two generic macros for writing calls to system services:

$name_S
$name_G

Which macro you use depends on how the argument list for the system service is constructed.

• The $name_S macro requires you to supply the arguments to the system service in the system service macro. The macro generates code to push the argument list onto the call stack during program execution. With this macro, you can use registers to contain or point to arguments so that you can write reentrant programs.
• The $name_G macro requires you to construct an argument list elsewhere in the program and specify the address of this list as an argument to the system service. (A macro is provided to create an argument list for each system service.) With this macro, you can use the same argument list, with modifications if necessary, for more than one invocation of the macro.

The $name_S macro generates a CALLS instruction; the $name_G macro generates a CALLG instruction. The services are called according to the standard procedure-calling conventions. System services save all registers except R0 and R1, and restore the saved registers before returning control to the caller.

The following sections describe how to code system service calls using each of these macros.

D.2.1 The $name_S Macro

The $name_S macro call has the following format:

The macro generates code to push the arguments on the stack in reverse order. The actual instructions used to place the arguments on the stack are determined as follows:

• If the system service requires a value for an argument, either a PUSHL instruction or a MOVZWL to --(SP) instruction is generated.
• If the system service requires an address for an argument, a PUSHAB, PUSHAW, PUSHAL, or PUSHAQ instruction is generated, depending on the context.

The macro then generates a call to the system service in the following format:

In this format, n is the number of arguments on the stack.

D.2.1.1 Example of $name_S Macro Call

Because a $name_S macro constructs the argument list at execution time, you can supply addresses and values by using register addressing modes. You can use the following line to execute the $READEF_S macro:

$READEF_S EFN=#1,STATE=(R10)

R10 contains the address of the longword that will receive the status of the flags.

This macro instruction is expanded as follows.

     PUSHAL  (R10)
     PUSHL   #1
     CALLS   #2,@#SYS$READEF

The $name_G macro requires a single operand:

In this format, label is the address of the argument list.

D.2.3 The $name Macro

Macros are provided to create argument lists for the $name_G macro. The $name_G macro (used with the $name macro) is especially useful for doing the following:

• Making calls to system services that have long argument lists
• Calling services repeatedly during the execution of a single program with the same, or essentially the same, argument list

The format of the macros is as follows:

label

Symbolic address of the generated argument list. This is the label given as an argument in the $name_G macro.

$name

The service macro name.

arg1,...,argn

Arguments to be placed in successive longwords in the argument list.

The example that follows shows how you can write a call to the Read Event Flags ($READEF) system service using an argument list created by $name.

The $READEF system service has the following macro format:

The efn argument must specify the number of an event flag cluster, and the state argument must supply the address of a longword that will receive the contents of the cluster.

You can specify these arguments using the $name macro, as follows:

READLST:
        $READEF EFN=1, -          ; Argument list for $READEF
                STATE=TESTFLAG

This $READEF macro generates the following code:

READLST:
        .LONG   2                 ; Argument list for $READEF
        .ADDRESS 1
        .ADDRESS -
                TESTFLAG

Executing the $READEF macro requires only the following line:

$READEF_G READLST

The macro generates the following code to call the Read Event Flags system service:

CALLG  READLST,@#SYS$READEF

SYS$READEF is the name of a vector to the entry point of the Read Event Flags system service. The linker automatically resolves the entry point addresses for all system services.

As part of the OpenVMS common language environment, the OpenVMS system routine data types provide compatibility between procedure calls that support many different high-level languages. Specifically, the OpenVMS data types apply to both Alpha and VAX architectures as the mechanism for passing argument data between procedures. This appendix describes the context and structure of the OpenVMS system routine data types and identifies the associated declarations to each of the specific high-level language implementations.

E.1 OpenVMS Data Types

The OpenVMS usage entry in the documentation format for system routines indicates the OpenVMS data type of the argument. Most data types can be considered conceptual types; that is, their meaning is unique in the context of the OpenVMS operating system. The OpenVMS data type access_mode is one example. The storage representation of this OpenVMS type is an unsigned byte, and the conceptual content of this unsigned byte is the fact that it designates a hardware access mode and therefore has only four valid values: 0, kernel mode; 1, executive mode; 2, supervisor mode; and 3, user mode. However, some OpenVMS data types are not conceptual types; that is, they specify a storage representation but carry no other semantic content in the OpenVMS context. For example, the data type byte_signed is not a conceptual type.

To use the OpenVMS usage entry, perform the following steps:

1. Find the data type in Table E-1 and read its definition.
2. Find the same OpenVMS data type in the appropriate high-level language implementation table (Tables B--2 through B--13) and its corresponding source-language type declaration.
3. Use this code as your type declaration in your application program. Note that, in some instances, you might have to modify the declaration.

For both Alpha and VAX architectures, Table E-1 lists and describes the standard OpenVMS data type declarations for the OpenVMS usage entry of any system routine call.

Table E-1 OpenVMS Usage Data Type Entries

Data Type	Definition
access_bit_names	Homogeneous array of 32 quadword descriptors; each descriptor defines the name of one of the 32 bits in an access mask. The first descriptor names bit <0>, the second descriptor names bit <1>, and so on.
access_mode	Unsigned byte denoting a hardware access mode. This unsigned byte can contain one of four values: 0, kernel mode; 1, executive mode; 2, supervisor mode; and 3, user mode.
address	Unsigned longword denoting a position in virtual memory. On Alpha systems, the address can be represented by a 64-bit value, in which case the high-order 33 bits of that value must be the same (for example, the 64-bit value must equal the sign-extended 32-bit value).
address_range	Unsigned quadword denoting a range of virtual addresses that identifies an area of memory. The first longword specifies the beginning address in the range; the second longword specifies the ending address in the range.
arg_list	Procedure call argument list containing a sequence of entries together with a count of the number of argument entries. On Alpha systems 2, an argument list is represented as quadword entities in hardware registers (R16--21 or F16--21). The AI register (R25) contains the argument count. When there are more than six arguments, the argument list overflows onto the stack. See Figure 18-5 for more information. On VAX systems 1, an argument list (shown in the following figure) is represented as a vector of longwords, where the first longword contains the count and each remaining longword contains one argument.
ast_procedure	The procedure value of a procedure to be called at asynchronous system trap (AST) level. (Procedures that are not to be called at AST level are of type procedure.)
boolean	Unsigned longword denoting a Boolean truth value flag. This longword can have one of two values: 1 ( true) or 0 ( false).
buffer	Generic term for temporary memory.
buffer_length	Generic term for temporary memory that indicates the size of a buffer.
byte_signed	Same as the data type byte integer (signed) in Table 17-3.
byte_unsigned	Same as the data type byte (unsigned) in Table 17-3.
channel	Unsigned word integer that is an index to an I/O channel.
char_string	String of from 0 to 65535 eight-bit characters. This OpenVMS data type is the same as the data type character string in Table 17-3. The following diagram shows the character string XYZ:
complex_number	One of the OpenVMS standard complex floating-point data types. The six complex floating point numbers are F_floating complex, D_floating complex, G_floating complex, S_floating, T_floating, and X_floating. As shown in the following figure, an F_floating point complex number (real, imaginary) is composed of two F_floating point numbers: the first is the real part of the complex number; the second is the imaginary part. For more structure detail, see floating_point described later in this table.
	As shown in the following figure, a D_floating point complex number (real, imaginary) is composed of two D_floating point numbers: the first is the real part of the complex number; the second is the imaginary part. For more structure detail, see floating_point described later in this table.
	As shown in the following figure, a G_floating point complex number (real, imaginary) is composed of two G_floating point numbers: the first is the real part of the complex number; the second is the imaginary part. For more structure detail, see floating_point described later in this table.
	On VAX systems 1, as shown in the following figure, an H_floating complex number (real, imaginary) is composed of two H_floating point numbers: the first is the real part of the complex number; the second is the imaginary part. Note that H_float numbers apply to VAX environments only. For more structure detail, see floating_point described later in this table.
	On Alpha systems 2, as shown in the following figure, an S_floating point complex number (real, imaginary) is composed of two S_floating point numbers: the first is the real part of the complex number; the second is the imaginary part. For more structure detail, see floating_point described later in this table.
	On Alpha systems 2, as shown in the following figure, a T_floating complex number (real, imaginary) is composed of two T_floating point numbers: the first is the real part of the complex number; the second is the imaginary part. For more structure detail, see floating_point described later in this table.
	On Alpha systems 2, as shown in the following figure, an X_floating complex number (real, imaginary) is composed of two X_floating point numbers: the first is the real part of the complex number; the second is the imaginary part. For more structure detail, see floating_point described later in this table.
cond_value	Longword integer for VAX or quadword sign-extended integer for Alpha denoting a condition value (a return status or system condition code) that is typically returned by a procedure in R0. Each numeric condition value has a unique symbolic name in the following format, where the severity condition code is a mnemonic describing the return condition:
	Depending on your specific needs, you can test just the low-order bit, the low-order three bits, or the entire value. The low-order bit indicates successful (1) or unsuccessful (0) completion of the service. The low-order 3 bits taken together represent the severity of the error. The remaining bits <31:3> classify the particular return condition and the operating system component that issued the condition value.
context	Unsigned longword used by a called procedure to maintain position over an iterative sequence of calls. The data type is usually initialized by the caller but thereafter is manipulated by the called procedure.
date_time	Unsigned 64-bit binary integer denoting a date and time as the number of elapsed 100-nanosecond units since 00:00 o'clock, November 17, 1858. This OpenVMS data type is the same as the data type absolute date and time in Table 17-3.
device_name	Character string denoting the 1- to 15-character name of a device. This string can be a logical name, but if it is, it must translate to a valid device name. If the device name contains a colon (:), the colon and the characters following it are ignored. An underscore (_) preceding the device name string indicates that the string is a physical device name.
ef_cluster_name	Character string denoting the 1- to 15-character name of an event flag cluster. This string can be a logical name, but if it is, it must translate to a valid event-flag cluster name.
ef_number	Unsigned longword integer denoting the number of an event flag. Local event flags numbered 32 to 63 are available to your programs.
exit_handler_block	Variable-length structure denoting an exit-handler control block. This control block, which describes the exit handler, is depicted in the following diagram:
fab	Structure denoting an RMS file access block.
file_protection	Unsigned word that is a 16-bit mask that specifies file protection. The mask contains four 4-bit fields, each of which specifies the protection (access protected when a bit is 1) to be applied to file access attempts by one of the four categories of users, from rightmost field to leftmost field: (1) system users, (2) file owner, (3) users in the same UIC group as the owner, and (4) all other users (the world). Each field specifies, from rightmost bit to leftmost bit: (1) read access, (2) write access, (3) execute access, (4) delete access. Set bits indicate that access is denied. The following diagram depicts the 16-bit file-protection mask:
floating_point	One of the Alpha or VAX standard floating-point data types. VAX systems support F_floating, D_floating, G_floating, or H_floating data types. In addition, Alpha systems support S_floating, T_floating, or X_floating types. The following paragraphs briefly describe these data types: The structure of an F_floating datum follows. It contains two fraction fields. Note that the field 2 extension holds the least significant portion of the fractional number.
	The structure of a D_floating datum follows. It contains four fraction fields. Note that the field 4 extension holds the least significant portion of the fractional number. While OpenVMS Alpha 2supports the manipulation of D_floating and D_floating complex data, compiled-code support invokes conversion from D_floating to G_floating for Alpha arithmetic operations. Also, the conversion of G_floating intermediate results are converted back to D_floating when needed either for stores to memory or for passing parameters. However, use of D_floating data in arithmetic operations on Alpha processors produces results that are limited to G_float precision.
	The structure of a G_floating datum follows. It contains four fraction fields. Note that the field 4 extension holds the least significant portion of the fractional number.
	The structure of an H_floating datum follows (VAX 1systems only). It contains seven fraction fields. Note that the field 7 extension holds the least significant portion of the fractional number.
	The structure of an S_floating datum follows (Alpha 2 systems only). It contains two fraction fields. Note that the field 2 extension holds the least significant portion of the fractional number.
	The structure of a T_floating datum follows (Alpha 2 systems only). It contains four fraction fields. Note that fraction field 1 holds the most significant bits, and the field 4 extension holds the least significant portion of the fractional number.
	The structure of an X_floating datum follows (Alpha 2 systems only). An X_floating datum occupies 16 contiguous bytes in memory or two consecutive floating-point registers. It contains seven fraction fields (0--6). Note that fraction field 6 holds the most significant bits and the field 0 extension holds the least significant portion of the fractional number.
function_code	Unsigned longword specifying the exact operations a procedure is to perform. This longword has two word-length fields: the first field is a number specifying the major operation; the second field is a mask or bit vector specifying various suboperations within the major operation.
identifier	Unsigned longword that identifies an object returned by the system.
invo_context_blk 2	Structure that contains the context information of a specific procedure invocation in a call chain. For information describing the invocation context block, see the OpenVMS Calling Standard.
invo_handle 2	Unsigned longword that refers to a specific procedure invocation at run time. The invo_handle longword defines the invocation handle of a procedure in a call chain.
io_status_block	Quadword structure containing information returned by a procedure that completes asynchronously. The information returned varies depending on the procedure.
	The following figure illustrates the format of the information written in the IOSB for SYS$QIO:
	The first word contains a condition value indicating the success or failure of the operation. The condition values used are the same as for all returns from system services; for example, SS$_NORMAL indicates successful completion. The second word contains the number of bytes actually transferred in the I/O operation. Note that for some devices this word contains only the low-order word of the count. The second longword contains device-dependent return information. To ensure successful I/O completion and the integrity of data transfers, you should check the IOSB following I/O requests, particularly for device-dependent I/O functions.
item_list_2	Structure that consists of one or more item descriptors and is terminated by a longword containing 0. Each item descriptor is a 2-longword structure that contains three fields. The following diagram depicts a single-item descriptor:
	The first field is a word in which the service writes the length (in characters) of the requested component. If the service does not locate the component, it returns the value 0 in this field and in the component address field. The second field contains a user-supplied, word-length symbolic code that specifies the component desired. The item codes are defined by the macros specific to the service. The third field is a longword in which the service writes the starting address of the component. This address is within the input string itself.
item_list_3	Structure that consists of one or more item descriptors and is terminated by a longword containing 0. Each item descriptor is a 3-longword structure that contains four fields.
	The following diagram depicts the format of a single-item descriptor:
	The first field is a word containing a user-supplied integer specifying the length (in bytes) of the buffer in which the service writes the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of buffer length is too small, the service truncates the data. The second field is a word containing a user-supplied symbolic code specifying the item of information that the service is to return. These codes are defined by macros specific to the service. The third field is a longword containing the user-supplied address of the buffer in which the service writes the information. The fourth field is a longword containing the user-supplied address of a word in which the service writes the length in bytes of the information it actually returned.
item_list_pair	Structure that consists of one or more longword pairs, or doublets, and is terminated by a longword containing 0. Typically, the first longword contains an integer value such as a code. The second longword can contain a real or integer value.
item_quota_list	Structure that consists of one or more quota descriptors and is terminated by a byte containing a value defined by the symbolic name PQL$_LISTEND. Each quota descriptor consists of a 1-byte quota name followed by an unsigned longword containing the value for that quota.
lock_id	Unsigned longword integer denoting a lock identifier. This lock identifier is assigned to a lock by the lock manager when the lock is granted.
lock_status_block	Structure into which the lock manager writes status information about a lock. A lock status block always contains at least two longwords: the first word of the first longword contains a condition value; the second word of the first longword is reserved by Compaq. The second longword contains the lock identifier. The lock status block receives the final condition value plus the lock identification, and optionally contains a lock value block. When a request is queued, the lock identification is stored in the lock status block even if the lock has not been granted. This allows a procedure to dequeue locks that have not been granted. The condition value is placed in the lock status block only when the lock is granted (or when errors occur in granting the lock).
	The following diagram depicts a lock status block that includes the optional 16-byte lock value block:
lock_value_block	A 16-byte block that the lock manager includes in a lock status block if the user requests it. The contents of the lock value block are user-defined and are not interpreted by the lock manager.
logical_name	Character string of from 1 to 255 characters that identifies a logical name or equivalence name to be manipulated by OpenVMS logical name system services. Logical names that denote specific OpenVMS objects have their own OpenVMS types; for example, a logical name identifying a device has the OpenVMS type device_name.
longword_signed	Same as the data type longword integer (signed) in Table 17-3.
longword_unsigned	Same as the data type longword (unsigned) in Table 17-3.
mask_byte	Unsigned byte in which each bit is interpreted by the called procedure. A mask is also referred to as a set of flags or as a bit mask.
mask_longword	Unsigned longword in which each bit is interpreted by the called procedure. A mask is also referred to as a set of flags or as a bit mask.
mask_quadword	Unsigned quadword in which each bit is interpreted by the called procedure. A mask is also referred to as a set of flags or as a bit mask.
mask_word	Unsigned word in which each bit is interpreted by the called procedure. A mask is also referred to as a set of flags or as a bit mask.
mechanism_args	Structure (array) of mechanism argument vectors that contain information about the machine state when an exception occurs or when a condition is signaled. For more information concerning mechanism argument vectors, see the OpenVMS Calling Standard.
null_arg	Unsigned longword denoting a null argument. (A null argument is one whose only purpose is to hold a place in the argument list.)
octaword_signed	Same as the data type octaword integer (signed) in Table 17-3.
octaword_unsigned	Same as the data type octaword (unsigned) in Table 17-3.
page_protection	Unsigned longword specifying page protection to be applied by the Alpha or VAX hardware. Protection values are specified using bits <3:0>; bits <31:4> are ignored. If you specify the protection as 0, the protection defaults to kernel read only. The $PRTDEF macro defines the following symbolic names for the protection codes: Symbol Description PRT$C_NA No access PRT$C_KR Kernel read only PRT$C_KW Kernel write PRT$C_ER Executive read only PRT$C_EW Executive write PRT$C_SR Supervisor read only PRT$C_SW Supervisor write PRT$C_UR User read only PRT$C_UW User write PRT$C_ERKW Executive read; kernel write PRT$C_SRKW Supervisor read; kernel write PRT$C_SREW Supervisor read; executive write PRT$C_URKW User read; kernel write PRT$C_UREW User read; executive write PRT$C_URSW User read; supervisor write
procedure	Procedure value of a procedure that is not to be called at AST level. (Arguments specifying procedures to be called at AST level have the OpenVMS type ast_procedure.) A procedure value is an address that represents a procedure. On VAX systems, a procedure value is the address of the procedure entry mask. On Alpha systems, a procedure value is the address of the procedure descriptor for the procedure. For more information, see the OpenVMS Calling Standard.
process_id	Unsigned longword integer denoting a process identification (PID). This process identification is assigned to a process by the operating system when the process is created.
process_name	Character string containing 1 to 15 characters that specifies the name of a process.
quadword_signed	Same as the data type quadword integer (signed) in Table 17-3.
quadword_unsigned	Same as the data type quadword (unsigned) in Table 17-3.
rights_holder	Unsigned quadword specifying a user's access rights to a system object. This quadword consists of two fields: the first is an unsigned longword identifier (OpenVMS type rights_id), and the second is a longword bit mask in which each bit specifies an access right. The following diagram depicts the format of a rights holder:
rights_id	Unsigned longword denoting a rights identifier, which identifies an interest group in the context of the OpenVMS security environment. This rights environment might consist of all or part of a user's user identification code (UIC). Identifiers have two formats in the rights database: UIC format (OpenVMS type uic) and ID format. The high-order bits of the identifier value specify the format of the identifier. Two high-order zero bits identify a UIC format identifier; bit <31>, set to 1, identifies an ID format identifier. Bits <30:28> are reserved by Compaq. The remaining bits specify the identifier value. The following diagram depicts the ID format of a rights identifier:
	To the system, an identifier is a binary value; however, to make identifiers easy to use, the system translates the binary identifier value into an identifier name. The binary value and the identifier name are associated in the rights database.
	An identifier name consists of 1 to 31 alphanumeric characters and contains at least one nonnumeric character. An identifier name cannot consist entirely of numeric characters. It can include the characters A through Z, dollar signs ($), and underscores (_), as well as the numbers 0 through 9. Any lowercase characters are automatically converted to uppercase.
rab	Structure denoting an RMS record access block.
section_id	Unsigned quadword denoting a global section identifier. This identifier specifies the version of a global section and the criteria to be used in matching that global section.
section_name	Character string denoting a 1- to 43-character global-section name. This character string can be a logical name, but it must translate to a valid global section name.
system_access_id	Unsigned quadword that denotes a system identification value to be associated with a rights database.
time_name	Character string specifying a time value in an OpenVMS format.
transaction_id	Unsigned octaword that denotes a unique transaction identifier.
uic	Unsigned longword denoting a user identification code (UIC). Each UIC is unique and represents a system user. The UIC identifier contains two high-order bits that designate format, a member field, and a group field. Member numbers range from 0 to 65534; group numbers range from 1 to 16382. The following diagram depicts the UIC format:
user_arg	On VAX systems, an unsigned longword, and on Alpha systems, an unsigned quadword denoting a user-defined argument. The longword (VAX) or quadword (Alpha) is passed to a procedure as an argument, but the contents of the longword or quadword are defined and interpreted by the user.
varying_arg	On VAX systems, an unsigned longword, and on Alpha systems, an unsigned quadword denoting a varying argument. A variable argument can have variable types, depending on specifications made for other arguments in the call.
vector_byte_signed	Homogeneous array whose elements are all signed bytes.
vector_byte_unsigned	Homogeneous array whose elements are all unsigned bytes.
vector_longword_signed	Homogeneous array whose elements are all signed longwords.
vector_longword_unsigned	Homogeneous array whose elements are all unsigned longwords.
vector_quadword_signed	Homogeneous array whose elements are all signed quadwords.
vector_quadword_unsigned	Homogeneous array whose elements are all unsigned quadwords.
vector_word_signed	Homogeneous array whose elements are all signed words.
vector_word_unsigned	Homogeneous array whose elements are all unsigned words.
word_signed	Same as the data type word integer (signed) in Table 17-3.
word_unsigned	Same as the data type word (unsigned) in Table 17-3.