HP OpenVMS Systems Documentation

Table 11-2 summarizes the OpenVMS Alpha system services that support 64-bit addresses.

Although RMS system services provide some 64-bit addressing capabilities, they are not listed in this table because they are not full 64-bit system services. See Section 11.2 for more details.

OpenVMS system services not listed in Table 11-2 and all user-written system services that are not explicitly enhanced to accept 64-bit addresses will receive sign-extension checking. Any argument passed to these services that is not properly sign-extended will cause the error status SS$_ARG_GTR_32_BITS to be returned.

11.1.6 Language Support for 64-Bit System Services

C function prototypes for system services are available in SYS$LIBRARY:SYS$STARLET_C.TLB (or STARLET).

No 64-bit MACRO-32 macros are available for system services. The MACRO-32 caller must use the AMACRO built-in EVAX_CALLG_64 or the $CALL64 macro. For more information about MACRO-32 programming support for 64-bit addressing, see OpenVMS MACRO-32 Porting and User's Guide.

11.1.7 NEW STARLET Definitions for C

As of OpenVMS Alpha Version 7.0, SYS$LIBRARY:SYS$STARLET_C.TLB (or STARLET) provides C function prototypes for system services, as well as new and enhanced data structure definitions. The new definitions are more consistent with the OpenVMS C language coding conventions and definitions (typedefs) used in SYS$LIBRARY:SYS$LIB_C.TLB.

To maintain source compatibility for existing users of STARLET.H, the old style function declarations and definitions are still provided by default. To take advantage of the new system service function prototypes and type definitions, you must explicitly enable them.

You can either define the __NEW_STARLET symbol with a Compaq C command line qualifier or include the definition directly in your source program. For example:

• Define the _NEW_STARLET symbol with the Compaq C command line qualifier as follows:

  /DEFINE=(__NEW_STARLET=1)

  
  or
• Define the __NEW_STARLET symbol in your C source program before including the SYS$STARLET_C.TLB header files:

  #define __NEW_STARLET 1 #include <starlet.h> #include <vadef.h>

To see the currently available system service function prototypes in STARLET.H, you can use the Librarian Utility, as shown in the following example:

$ LIBRARY/OUTPUT=STARLET.H SYS$LIBRARY:SYS$STARLET_C.TLB/EXTRACT=STARLET

The following example shows a new system service function prototype as it is defined in STARLET.H:

    #pragma __required_pointer_size __long

     int sys$expreg_64(
               struct _generic_64 *region_id_64,
               unsigned __int64 length_64,
               unsigned int acmode,
               unsigned int flags,
               void *(*(return_va_64)),
               unsigned __int64 *return_length_64);

    #pragma __required_pointer_size __short

For more information about Compaq C pointer size pragmas, see the DEC C User's Guide for OpenVMS Systems.

The following source code example shows the sys$expreg_64 function prototype referenced in a program.

#define __NEW_STARLET 1               /* Enable "New Starlet" features */

#include <starlet.h>                  /* Declare prototypes for system services */
#include <gen64def.h>                 /* Define GENERIC_64 type */
#include <vadef.h>                    /* Define VA$ constants */

#include <ints.h>                     /* Define 64-bit integer types */
#include <far_pointers.h>             /* Define 64-bit pointer types */

{
    int status;                       /* Ubiquitous VMS status value */
    GENERIC_64 region = { VA$C_P2 };  /* Expand in "default" P2 region */
    VOID_PQ p2_va;                    /* Returned VA in P2 space */
    uint64 length;                    /* Allocated size in bytes */
    extern uint64 page_size;          /* Page size in bytes */

    status = sys$expreg_64( &region, request_size, 0, 0, &p2_va, &length );
    ...

}

Table 11-3 lists the data structures that are used by the new function prototypes.

This section summarizes changes to the RMS interface that support 64-bit addressing and enable you to use RMS to perform input and output operations to P2 or S2 space. You can take full advantage of these RMS enhancements by making only minor modifications to existing RMS code.

For complete information about RMS support for 64-bit addressing, see the OpenVMS Record Management Services Reference Manual.

The RMS user interface consists of a number of control data structures (FAB, RAB, NAM, XABs). These are linked together with 32-bit pointers and contain embedded pointers to I/O buffers and various user data buffers, including file name strings and item lists. RMS support for 64-bit addressable regions allows 64-bit addresses for the following user I/O buffers:

• UBF (user record buffer)
• RBF (record buffer)
• RHB (fixed-length record header buffer; fixed portion of VFC record format)
• KBF (key buffer containing the key value for random access)

The prompt buffer pointed to by RAB$L_PBF is excluded because the terminal driver does not allow 64-bit addresses.

Specific enhancements to the RMS interface for 64-bit addressing are as follows:

• Data buffers can be placed in P2 or S2 space for the following user I/O services:
  • Record I/O services: $GET, $FIND, $PUT, $UPDATE
  • Block I/O services: $READ, $WRITE
• The RAB structure points to the record and data buffers used by these services.
• An extension of the existing RAB structure is used to specify 64-bit buffer pointers and sizes.
• The buffer size maximum for RMS block I/O services ($READ and $WRITE) has been increased from 64 KB to 2 GB, with two exceptions:
  • For RMS journaling, a journaled $WRITE service is restricted to the current maximum (65535 minus 99 bytes of journaling overhead). An RSZ error is returned to RAB$L_STS if the maximum is exceeded.
  • Magnetic tape is still limited to 65535 bytes at the device driver level.
  
  Buffer size maximums for RMS record I/O services ($GET, $PUT, $UPDATE) have not changed. Prior RMS on-disk record size limits still apply.

The rest of the RMS interface currently is restricted to 32-bit pointers:

• FAB, RAB, NAM, and XABs must still be allocated in 32-bit space.
• Any descriptors or embedded pointers to file names, item lists, and so on, must continue to use 32-bit pointers.
• Any arguments passed to the RMS system services remain 32-bit arguments. If you attempt to pass a 64-bit argument, the SS$_ARG_GTR_32_BITS error is returned.

The RAB64, a RMS user interface structure, is an extended RAB that can accommodate 64-bit buffer addresses. The RAB64 data structure consists of a 32-bit RAB structure followed by a 64-bit extension as shown below:

The RAB64 contains fields identical to all of the RAB fields except that field names have the RAB64 prefix instead of the RAB prefix. In addition, RAB64 has the following fields in the extension:

Note that the fields with the PQ tag in their names can hold either a 64-bit address or a 32-bit address sign-extended to 64 bits. Therefore, you can use the fields in all applications whether or not you are using 64-bit addresses.

For most record I/O service requests, there is an RMS internal buffer between the device and the user's data buffer. The one exception occurs with the RMS service $PUT. If the device is a unit record device and it is not being accessed over the network, RMS passes the address of the user record buffer (RBF) to the $QIO system service. If you inappropriately specify a record buffer (RBF) allocated in 64-bit address space for a $PUT to a unit record device that does not support 64-bit address space (for example, a terminal), the $QIO service returns SS$_NOT64DEVFUNC. (See Writing OpenVMS Alpha Device Drivers in C and OpenVMS Alpha Guide to Upgrading Privileged-Code Applications for more information about $QIO.) RMS returns the error status RMS$_SYS with SS$_NOT64DEVFUNC as the secondary status value in RAB64$L_STV.

RMS system services support the RAB structure as well as the RAB64 structure.