RMS is a set of generalized services that assist application programs in processing and managing files and their contents. OpenVMS languages may invoke these services using appropriate macros stored in system libraries using the OpenVMS calling standard. Record management services are system services identified by the entry point prefix SYS$ followed by three or more characters; but the SYS prefix is omitted in the corresponding VAX MACRO macro name. For example, the Create service has an entry point of SYS$CREATE and a VAX MACRO macro name of $CREATE. A complete description of each service is provided in Part III, “OpenVMS RMS Services”.

Although RMS supports unit-record devices, such as terminals and printers, it primarily provides a comprehensive software interface to mass storage devices, such as disk and magnetic tape drives.

RMS provides a variety of disk file organizations, record formats, and record access modes from which you can select the appropriate processing techniques for your application. RMS supports sequential, relative, and indexed file organizations, and fixed-length and variable-length record formats are supported for each file organization. (Relative and sequential files also support other record formats.) The RMS record access modes permit you to access records sequentially, directly by key value, directly by relative record number, or directly by record file address (RFA). RMS also provides a means of performing block I/O operations for users with certain performance-critical applications (such applications may require user-defined file organizations or record formats, or both).

RMS also enforces the security requirements of a multiuser system with potential multinode access by restricting file access to one or more user types and a list of user names.

For systems that support network capabilities, RMS provides a subset of file and record management services through the data access protocol (DAP) to remote network nodes. Network DAP remote file operations are generally transparent to application programs.

RMS flexibility requires application programs to pass a multitude of arguments to RMS services for doing common operations such as file creation and file access. To minimize the problems associated with passing numerous arguments for each service call, the application program places the arguments in one or more data control blocks before it invokes a record management service. The only argument required for most services is the symbolic address of the appropriate data control block.

The RMS run-time processing environment consists of a set of blocks and the run-time services. The control block fields accessed by each service specify the appropriate file and record operations. Depending on the operation, RMS uses one or more control blocks by referring to one or more fields as input to, or output from, the operation.

To perform advanced RMS functions, you may need to set various control block field values at run-time between the time the file is opened and when the appropriate service is invoked.

Note that OpenVMS languages perform some of these steps transparently when a particular language statement or macro is present in a source program.

Two fields in each control block—the block length (BLN) field and the block identifier (BID) (or block code [COD] field in a XAB)—define the length of the control block (in bytes) and identify the control block type, respectively. These internal fields are always used as input arguments by the service that accesses the control block, and must be set before the control block can be used. After the block length and block identifier fields are established, you must treat them as read-only fields until the control block is no longer needed.

Part II, “RMS Control Blocks” describes each control block field in detail, including its length and its symbolic name.

Part III, “OpenVMS RMS Services” lists the calling format for each service together with the input control block fields and the output control block fields for each service.

RMS uses mnemonics to identify control block fields. For example, the mnemonic name for the FAB allocation quantity field is ALQ.

The mnemonic name (usually consisting of three characters) serves as a suffix to a symbolic name that identifies the location of each control block field. You should use the symbolic names to be sure you place values in the correct control block fields. RMS defines each symbolic name as a constant value equal to the offset, in bytes, from the beginning of the control block to the beginning of the field. These field names are thus called symbolic offsets.

Symbolic offset names are defined when the appropriate VAX MACRO control block initialization macro is used, when the appropriate VAX MACRO control block symbol definition macro is used, and when some languages invoke RMS. Alternatively, all control block symbolic offset names are available when you use the VAX MACRO $FABDEF, $RABDEF, $NAMDEF, and $XAB...DEF macros in a VAX MACRO program or procedure.

The format of the symbolic offsets consists of a 3-letter control block identifier (FAB, NAM, XAB, or RAB), a dollar sign ($), a 1-letter indicator of the length of the field (B, W, L, Q, or T), an underscore (_), and the field mnemonic, which is usually three letters.

ccc$x_fff

For example, the FAB field whose mnemonic is ALQ has a length of one longword and is identified by the symbolic offset FAB$L_ALQ. The field NAM$L_RLF is a NAM longword field whose mnemonic RLF reflects its name, the related file field.

Exceptions to the length designation are NAM$W_DID, NAM$W_FID, XAB$W_RFI, and RAB$W_RFA, each of which is three words in length rather than one word.

The length of a T field is specified by the corresponding S field; for example, the length of the NAM$T_DVI field is specified by the symbolic value field named NAM$S_DVI.

The xxx identifies the control block (FAB, NAM, XAB, or RAB); the $ and _ are separator characters, and the fff defines the mnemonic for the bit option. For example, the option CTG in the FAB file-processing options (FOP) field has a symbolic bit offset of FAB$V_CTG and a mask value of FAB$M_CTG.

Constant (or keyword) fields can contain only a limited set of values, thus there are no mask values or symbolic bit offsets. In some instances, the letter K is used to denote a constant (keyword) value field in place of the letter C; otherwise, the naming convention is the same.

xxx$C_fff

Note that the letter C replaces the letter M, denoting that this field is a constant (keyword) value field, not a mask value field. For example, the file organization (ORG) field of the FAB (FAB$B_ORG) can contain only the values FAB$C_IDX (indexed), FAB$C_REL (relative), or FAB$C_SEQ (sequential).

When specifying control block field locations, avoid using actual byte displacement values to identify control block field locations; instead, use the supplied symbolic offsets. RMS control block field locations may not always be the same from release to release; however, the symbolic offset names that identify the field locations always identify the same fields.

RMS uses the appropriate OpenVMS standard calling sequence and conventions, and preserves all general registers across a call, except for register 0 (R0) and register 1 (R1). When the service completes execution, it returns control to the calling program, passing a condition value in R0. You should analyze the completion value to determine the success or failure of the service and to alter the flow of execution of your program, if necessary. Where applicable, you should use the STS field and the STV field of the appropriate control block for signaling errors, instead of R0. For additional information about RMS completion values, see Section 2.4, “Service Completion”.

The argument list sent to the service is from two to four longwords in length, as shown in Figure 2.1, “Argument List Format”. (The Rename service, however, uses a 5-longword argument list.)

This section describes various service completion scenarios. The events associated with completing an RMS service call depend to some extent on how the user calls the service. The user may specify either the synchronous or asynchronous option in the control block (FAB or RAB) passed to the service, and the user may or may not specify an AST.

DBG> EXAMINE/CONDITION MYFAB+FAB$L_STS
DBG> EXAMINE/CONDITION MYFAB+FAB$L_STV

Generally, RMS executes in either executive mode or executive AST mode. When an operation is initiated, processing begins in executive mode. If device I/O is necessary to process the request, the $QIO system service is called. RMS specifies an executive-mode AST to signal completion. At this point, RMS exits from executive mode. If the operation is being performed asynchronously, control is returned to the caller; if the operation is synchronous, RMS waits for an event flag in the access mode of the caller. When the I/O is complete, RMS continues processing in executive AST mode. Thus, user-mode ASTs can be serviced while a synchronous operation called from user mode is awaiting I/O completion. However, processing in user mode during an asynchronous operation is interrupted by RMS processing in executive AST mode when I/O completes.

RMS should not be called from kernel mode, from executive AST mode, or from executive mode when executive-mode ASTs are disabled.

Previously, the data structures were protected at UREW (user read, executive write).

RMS uses system-reserved event flags to synchronize its internal operations. RMS reserves event flags 27, 28, 29, and 30 for possible use; in addition, event flag 31 is used to specify a “do not care” event flag for asynchronous processing.

You can use any character in the DEC Multinational character set in RMS records, including the key value of an indexed file. Keys are collated according to their corresponding character code value.

For a list of characters in the DEC Multinational character set, see the VSI OpenVMS User's Manual.

You can create, access, and deaccess a file using either the Create service or the Open service. The Create service constructs a new file structured to the attributes you specify in the FAB for the file, whereas the Open service makes an existing file available for processing by your program. Both of these services allocate the system resources needed to establish an access path to a file. You must open or create a file to perform most file operations and any record operations on that file. Where applicable, you must declare the type of shared access when you create or open a file. You do this through your program interface with RMS by selecting file access control options.

RMS provides several file-processing options for the Create service. The create-if option requests that the file be created only if it does not exist in the specified directory. If the file does exist in the specified directory, the existing file is opened. The Open and Create services both establish access to the desired file, but the Create service also allocates disk space and performs the functions related to allocation.

When you are finished processing a file, you invoke the Close service to close the file, disconnect all record streams associated with the file, and free all resources allocated to the file. If you do not explicitly invoke the Close service when the program image exits, RMS attempts an implicit close. All resources associated with open files are returned when the files are deaccessed at image rundown time. However, process permanent files are not implicitly closed when an image exits.

/*
** COPYFILE.C     This program copies the input file to the output file.
** It is made to resemble the MACRO example in the RMS Reference Manual.
*/
#define REC_SIZE 132
#define INPUT_NAME "INFILE"
#define OUTPUT_NAME "OUTFILE"
#define DEFAULT_NAME ".DAT"

#include      <rms>                /* defines for rabs and fabs */
#include      <stdio>              /* defins printf... */
#include      <starlet>            /* defines sys$open et al */

COPYFILE ()
{
struct FAB    infab, outfab, *fab; /* Allocate fabs and a pointer to fab */
struct RAB    inrab, outrab, *rab; /* Allocate fabs and a pointer to fab */
int           lib$signal();
int           stat;
char          rec_buff[REC_SIZE];  /* maximum record size */

infab = cc$rms_fab;                /* Make this a real FAB (bid and bln) */
infab.fab$l_fna = (char *) &INPUT_NAME; /* Primary file name:.. */
                                        /* ..(logical) name.. */
infab.fab$b_fns = sizeof INPUT_NAME -1; /* .. and its size */
infab.fab$l_dna = (char *) &DEFAULT_NAME; /* Default name:.. */
                                          /* ..here file type.. */
infab.fab$b_dns = sizeof DEFAULT_NAME -1; /* .. and its size */

inrab = cc$rms_rab;              /* Make this a real RAB (bid and bln) */
inrab.rab$l_fab = &infab;        /* Point to FAB for $CONNECT */
inrab.rab$v_rah = 1;             /* Set bitVield to request read-ahead */
inrab.rab$l_ubf = rec_buff;      /* Point to buffer area.. */
inrab.rab$w_usz = REC_SIZE;      /* ..and indicate its size */

outfab = cc$rms_fab;             /* Make this a real FAB (bid and bln) */
outfab.fab$v_ctg = 1;            /* Allocate contigeously */
outfab.fab$v_put = 1;            /* Write access (default on create) */
outfab.fab$v_nil = 1;            /* No sharing (default on create) */
outfab.fab$b_rat = FAB$M_CR;     /* Set option using bitMask */
outfab.fab$w_mrs = REC_SIZE;
outfab.fab$l_fna = (char *) &OUTPUT_NAME;
outfab.fab$b_fns = sizeof OUTPUT_NAME -1;
outfab.fab$l_dna = (char *) &DEFAULT_NAME;
outfab.fab$b_dns = sizeof DEFAULT_NAME -1;

outrab = cc$rms_rab;
outrab.rab$l_fab = &outfab;
outrab.rab$v_wbh = 1;              /* Write Ahead */
outrab.rab$l_rbf = rec_buff;       /* Same buffer address as before */

fab = &infab;                      /* for error handling */
stat = sys$open ( fab );           /* Actual open (could use &infab) */
if (stat & 1)                      /* $OPEN Success ? */
{
    outfab.fab$l_alq = infab.fab$l_alq; /* Set proper size for output */
    fab = &outfab;                  /* for error handling */
    stat = sys$create ( fab );      /* Try to create the file */
}

if (stat & 1)                       /* Both open & create success ? */
{
    rab = &outrab;                  /* for error handling */
    stat = sys$connect ( rab );     /* get some rms internal buffers */
    if (stat & 1)                   /* output $CONNECT Success ? */
    {
        rab = &inrab;               /* for error handling */
        stat = sys$connect ( rab ); /* input $CONNECT Success ? */
    }
    if (stat & 1)                   /* CONNECTs succes? then prime loop */
        stat = sys$get ( rab );     /* setting stat for while */

    while (stat & 1)                /* success on record operation ? */
    {
        /*
        ** Main Code. Opened and connected files and buffer
        ** First $GET done and inrab is current. Copy records.
        */
        outrab.rab$w_rsz = inrab.rab$w_rsz;  /* set correct size */
        rab = &outrab;                       /* error handler */
        stat = sys$put ( rab );              /* Actual copy */
        if (stat & 1)                        /* $PUT success? */
        {
            rab = &inrab;                    /* for error handling */
            stat = sys$get ( rab );          /* $GET next , set stat */
        }
    } /* while */


    /*
    ** Fallen through while. stat must be EOF if copy was succesful.
    ** if not, signal error from connect, get or put. Using stat instead
    ** of rab->rab$l_sts to handle (programming) error providing RAB.
    */

    if (stat != RMS$_EOF)
        stat = lib$signal( stat, rab->rab$l_stv );

    stat = sys$close ( &infab );
    stat = sys$close ( &outfab );
    }
else
{
    /* Failed to open input or output file */
    stat = lib$signal( stat, fab->fab$l_stv );
}

return stat;                  /* Using output close stat to return */
}

$ ASSIGN [INV]30JUN93,[INV.OLD]30JUN93 INFILE

infab.fab$l_dna = &DEFAULT_NAME;       /* Default name: here file type.. */
infab.fab$b_dns = sizeof DEFAULT_NAME; /* .. and its size */

#define REC_SIZE 132
outfab.fab$w_mrs = REC_SIZE;

outfab.fab$b_rat = FAB$M_CR;        /* Set option using bitMask */

outrab.rab$w_rsz = inrab.rab$w_rsz; /* set correct size */

stat = SYS$OPEN ( fab );            /* Actual open (could use &infab) */

stat = SYS$CONNECT ( rab );         /* get some rms internal buffers */

Example 3.3, “Displaying the Index Root for a File” shows the index root level(s) for a specified file. You can modify the program to display more parameters, add LIB$FIND_FILE, and so forth.

** Show_roots.c
**
*/

#include <rms>
#include <stdio>
#define MAXKEY 10
main (int argc, char *argv[])
{
struct FAB      fab;
struct XABSUM   sum;
struct XABKEY   xab[MAXKEY];
int             i, stat, lvl, keys;

fab = cc$rms_fab;
sum = cc$rms_xabsum;
fab.fab$b_shr = FAB$M_SHRPUT;
fab.fab$b_fac = FAB$M_GET;
fab.fab$l_fna = argv[1];
fab.fab$b_fns = STRLEN( argv[1] );
fab.fab$l_xab = &sum;
stat = SYS$OPEN ( &fab );
if (!(stat&1)) return stat;
if (fab.fab$b_org!=FAB$C_IDX) return RMS$_ORG;
keys = sum.xab$b_nok;
fab.fab$l_xab = &xab[0];
for (i=0; i<keys; i++)
    {
    /*
    ** Init Xab Key for each defined key
    ** Point previous to current except first.
    */
    xab[i] = cc$rms_xabkey;
    xab[i].xab$b_ref = i;
    if (i) xab[i-1].xab$l_nxt = &xab[i];
    }
/*
** Ask RMS to fill in the XABs hooked off the FAB.
*/
stat = SYS$DISPLAY ( &fab );
if (!(stat&1)) return stat;
printf ("File %s, Root levels: %d", argv[1], xab[0].xab$b_lvl);
for (i=1; i<keys; i++) printf (", %d", xab[i].xab$b_lvl);
printf (".\n");
return stat;
}

Example 3.4, “Using NAML Blocks for Extended File Specifications” contains a sample program which uses the new NAML blocks available beginning with OpenVMS V7.2. The NAML block is similar to the NAM block, except that it contains long fields to allow for the extended file names and deep directory structures supported on ODS-5 disks.

%CC-E-UNDECLARED, In the declaration of "primarySpec", "NAML$C_MAXRSS"
is not declared.

%RMS-F-NAM, invalid NAM block or NAM block not accessible

The program prompts for the file specification to process, and then displays the results.

/*--------------------------------------------------------------
 *
 *   NAML_EXAMPLE.C
 *
 *   This sample program uses NAML blocks (short and long
 *   buffers) with RMS $PARSE and $SEARCH functions to
 *   demonstrate extended file specification capabilities.
 *
 *   NAML blocks are supported only on Alpha platforms.
 *
 *   Notes:
 *      The no-short-upcase NAML bit is set, so the short expanded
 *      specification will not be upcased.
 *
 *-------------------------------------------------------------*/

#include <string>                       // for strlen, etc.
#include <ssdef>                        // for SS$_NORMAL
#include <stdio>                        // for printf, etc.
#include <starlet>                      // sys$parse, sys$search
                                        // function prototypes
#include <rms>                          // NAML and FAB structure definitions

int main()
{
    int vms_status;
    int primarySpecLength = 0;
    char primarySpec[NAML$C_MAXRSS+2];  // (Include room for LF and \0.)
    char defaultSpec[] = "*.*;*";

    /*
     *  Create the string buffers for the resultant and expanded strings
     */

    char Naml_Shrt_Esa[NAM$C_MAXRSS],
         Naml_Long_Esa[NAML$C_MAXRSS],
         Naml_Shrt_Rsa[NAM$C_MAXRSS],
         Naml_Long_Rsa[NAML$C_MAXRSS];

    /*
     *  Declare the FAB and NAML structures
     */

    struct FAB fab;
    struct namldef naml;

    /*
     *  Initialize the FAB and NAML using the default structures,
     *  then set them up for our use.
     */

    fab = cc$rms_fab;
    naml = cc$rms_naml;

    /*
     *  To indicate that the NAML fields should be used rather
     *  than the FAB fields for the filename, we put a -1 in
     *  the FNA field, and a zero in the FNS field.
     */

    fab.fab$l_fna = (char *)-1;
    fab.fab$b_fns = 0;

    fab.fab$l_dna = defaultSpec;
    fab.fab$b_dns = strlen(defaultSpec);

    fab.fab$l_naml = &naml;     //  tie the NAML to the FAB

    naml.naml$l_long_filename = primarySpec;
    naml.naml$l_esa = Naml_Shrt_Esa;
    naml.naml$b_ess = sizeof (Naml_Shrt_Esa);
    naml.naml$l_rsa = Naml_Shrt_Rsa;
    naml.naml$b_rss = sizeof (Naml_Shrt_Rsa);

    naml.naml$l_long_expand       = Naml_Long_Esa;
    naml.naml$l_long_expand_alloc = sizeof (Naml_Long_Esa);
    naml.naml$l_long_result       = Naml_Long_Rsa;
    naml.naml$l_long_result_alloc = sizeof (Naml_Long_Rsa);

    /*
     *  Set NAML options flags
     */

    naml.naml$v_synchk = 0;             // Have $PARSE do directory
                                        //   existence check
    naml.naml$v_no_short_upcase = 1;    // Don't upcase short expanded
                                        //   spec.

    /*
     *  Prompt for the input file specification.  A blank
     *  response will use the default filespec of *.*;*
     */

    printf("File specification to be scanned: ");
    gets(primarySpec);

    naml.naml$l_long_filename_size = strlen(primarySpec);

    /*
     *  Parse the given file specification.  This sets up for
     *  the $SEARCH loop.  On success, print out the expanded
     *  file specifications.
     */

    printf ("\n\nParsing: %s\n", primarySpec);
    vms_status = sys$parse (&fab);
    if (!(vms_status & 1))                      //  return any error
    {
        return vms_status;
    }

    naml.naml$l_esa[naml.naml$b_esl] = '\0';    //  terminate the string
    printf ("   (Short) Expanded Specification: '%s'\n",
                naml.naml$l_esa);

    naml.naml$l_long_expand[naml.naml$l_long_expand_size] = '\0';
    printf ("   (Long)  Expanded Specification: '%s'\n",
                naml.naml$l_long_expand);

    /*
     *  Go into the $SEARCH loop.  We loop until the
     *  $SEARCH fails or returns No More Files (NMF)
     *  For each successful $SEARCH, print out the
     *  resultant file names from the NAML block.
     */

    printf ("\n\nSearching for files matching: %s\n", primarySpec);
    while (1)
    {
        vms_status = sys$search (&fab);
        if (!(vms_status & 1))          //  handle any error
        {
            if (vms_status == RMS$_NMF)
                return SS$_NORMAL;
            else
                return vms_status;
        }

        printf ("   (Short) Resultant Specification: '%-*.*s'\n",
                    naml.naml$b_rsl,
                    naml.naml$b_rsl,
                    naml.naml$l_rsa);

        printf ("   (Long)  Resultant Specification: '%-*.*s'\n",
                    naml.naml$l_long_result_size,
                    naml.naml$l_long_result_size,
                    naml.naml$l_long_result);

    }  //  end of while loop

}  // end of function main()

Many FAB fields are directly equivalent to certain File Definition Language (FDL) attributes. For information about FDL, refer to the VSI OpenVMS Record Management Utilities Reference Manual.

Each FAB field is described in this section. Unless indicated otherwise, each field is supported for DECnet for OpenVMS operations on files at the remote OpenVMS systems. For information about the support of RMS options for remote file access to other systems, see the VSI OpenVMS DECnet Networking Manual.

To use a FAB, you must allocate process storage and specify the character string for the primary file specification and, optionally, the default file specification. The FAB$L_FNA and FAB$B_FNS fields define the primary file specification to RMS; the FAB$L_DNA and FAB$B_DNS fields define the default file specification to RMS.

This field comprises four 2-bit subfields, two of which are unsupported. The supported subfields are the FAB$V_CHAN_MODE subfield and the FAB$V_LNM_MODE subfield (see Section 4.22, “FAB$V_LNM_MODE Subfield”).

The allocation quantity (ALQ) field defines the number of blocks to be initially allocated to a disk file when it is created (using the Create service) or to be added to the file when it is explicitly extended (using the Extend service). This field corresponds to the FDL attribute FILE ALLOCATION.

For the Extend service, this field specifies the number of blocks to be added to the file. Note that RMS uses this as the extension value when a process extends a file using the Extend service, unless the process changes the value before it invokes the Extend service.

When you use the Create and Extend services, the allocation quantity value is rounded up to the next disk cluster boundary; the number of blocks actually allocated is returned in the FAB$L_ALQ field.

Note that the function of the FAB$L_ALQ field changes if allocation control XABs are used when you create or extend a file. The description of the XABALL control block (see Chapter 9, Allocation Control XAB (XABALL)) discusses how allocation control XABs affect the FAB$L_ALQ field.

The block identifier (BID) field is a static field that identifies a control block as a FAB. Once set, this field should not be altered unless the control block is no longer needed. This field must be initialized to the symbolic value FAB$C_BID (this is done by the $FAB macro).

The bucket size (BKS) field is used only for relative or indexed files to specify the number of blocks in each bucket of the file.

This field contains a numeric value in the range of 0 to 63. If you do not specify a value or specify a value of 0, RMS uses a default of the minimum number of blocks needed to contain a single record, or a minimum of two records for indexed files. If the file will be processed by RMS-11, the bucket size must be less than or equal to 32 blocks.

When calculating the bucket size, you must consider the control information (overhead) associated with each bucket. Also, certain record types contain control bytes; thus, the number of records per bucket multiplied by the number of control bytes per record equals the number of record overhead bytes per bucket. See the VSI OpenVMS Guide to OpenVMS File Applications for more information.

You can use the Edit/FDL utility to determine the optimum bucket size. Note that if an allocation control XAB is specified, the value specified in the XAB$B_BKZ field supersedes the value specified in the FAB$B_BKS field. When multiple allocation control XABs are specified, the largest value in any XAB$B_BKZ field supersedes the value in the FAB$B_BKS field. Refer to Section 9.6, “XAB$B_BKZ Field” for information about the XAB$B_BKZ field.

When you open an existing relative or indexed file, RMS sets the FAB$B_BKS field to the defined size of the largest bucket size in the file. However, when you create a new relative or indexed file, set the FAB$B_BKS field before you invoke the Create service rather than use the default.

With indexed files, note that if the FAB$B_BKS field is not specified and a maximum record size (FAB$W_MRS field) is specified, then RMS selects a bucket size that allows at least one maximum size record to fit. Generally, performance for record insertion and sequential retrieval on the primary key improves if at least six or seven data records fit into a primary data bucket. If either the bucket size or the disk cluster size is other than one block, use a default extension quantity (FAB$W_DEQ) that is the least common multiple of the bucket size and cluster size to avoid allocated but unused blocks within the file.

This field corresponds to the FDL attribute FILE BUCKET_SIZE.

The block length (BLN) field is a static field that defines the length of the FAB. Once set, this field should not be altered unless the control block is no longer needed. This field must be initialized to the symbolic value FAB$C_BLN (this is done by the $FAB macro).

RMS uses the block size (BLS) field as input for nondisk files. The BLS field usually defines the size, in bytes, of the blocks on a magnetic tape. Note that for some devices, this value must be an even number. This field corresponds to the FDL attribute FILE MT_BLOCK_SIZE.

The FAB$W_BLS field contains a numeric value in the range of 20 through 65,535 for ANSI-formatted tapes and 14 through 65,532 for foreign tapes. (Foreign tapes are those that are not in the standard ANSI format used by OpenVMS operating systems, and must be mounted using the DCL command MOUNT/FOREIGN.) If no value or a value of 0 is specified, the default selected when the volume was mounted is used.

When you create a magnetic tape file, you can set the FAB$W_BLS field before you invoke the Create service. In all other cases, RMS ignores this field. When you open an existing sequential file with an Open service, RMS returns the device buffer size. For terminals, this field defines the WIDTH setting; for mailboxes, this field defines the maximum message size.

For compatibility with RMS-11, RMS rounds off the block size for an ANSI-formatted tape to the next highest multiple of 4. For example, if you set the block length to 38, RMS sets it to 40. The block size of a foreign tape is not rounded off by RMS.

To create a magnetic tape for interchange with operating systems other than OpenVMS systems, consult the documentation for the recipient system to identify possible limitations on block size. ANSI standards require that the block size be less than or equal to 2048 bytes.

The user context (CTX) field allows you to convey user information to a completion routine in your program. This field contains a user-specified value, up to four bytes long, and is intended solely for your use. RMS never uses it for record management activities.

This field corresponds to the FDL attribute FILE CONTEXT.

The default file extension quantity (DEQ) field specifies the number of blocks to be added when RMS automatically extends the file. Automatic extension only applies to files that reside on disk devices and occurs whenever your process invokes a Put or Write service and the currently allocated file space is exhausted. When you invoke a Put service, automatic file extension occurs when needed, regardless of the file organization. When you invoke the Write service, automatic extension occurs only for sequential files (indexed and relative files require the Extend service to extend file allocation).

This field corresponds to the FDL attribute FILE EXTENSION.

This field contains a numeric value in the range 0 through 65,535, which is rounded up to the next cluster boundary. A large value results in fewer file extensions over the life of a file; a small value results in numerous file extensions over the life of a file. When a file has numerous file extensions that may be noncontiguous, this slows record access.

If you do not specify a value or specify the value 0 when you create a file, RMS uses the default specified by the DCL command SET RMS_DEFAULT/EXTEND_QUANTITY. If this value is 0, RMS uses the system default extension quantity specified by the system parameter RMS_EXTEND_SIZE. If this value is 0, RMS computes the default value.

If the value in the FAB$W_DEQ field, the value set by the SET RMS_DEFAULT/EXTEND_QUANTITY command, and the value of the system parameter RMS_EXTEND_SIZE are all 0, RMS may provide an overly large value to minimize the number of extend operations that it must perform. At times, this value can exceed the available disk quota even though there is actually enough space for the file if only the required amount is used. You can use the DCL command SET RMS_DEFAULT/EXTEND_QUANTITY to limit (explicitly specify) the extension size to the recommended number of blocks. An appropriate size is the number of blocks specified as the cluster size for the device (set by the DCL command INITIALIZE/CLUSTER_SIZE). For large files on a volume where there is sufficient disk space, consider using a multiple of the cluster size to improve subsequent performance.

When creating a new file, you can specify the extension quantity for the file by setting the desired value in the FAB$W_DEQ field before or after invoking the Create service. This value becomes a permanent attribute for the file.

When processing an existing file, you can temporarily override the default extension quantity specified when the file was created. To do this, set the desired value before or after invoking the Open service. When you subsequently close the file, the default extension quantity reverts to the value set when the file was created.

See the discussion under FAB$B_BKS for indexed files.

Note that the use of an allocation control XAB overrides the value in this field. See Chapter 9, Allocation Control XAB (XABALL) for a detailed description of allocation control XABs.

The device characteristics (DEV) field allows your program to obtain the generic characteristics of the device containing the file. You can locate and test the various bits in the field using symbolic offsets. RMS returns a value in this binary options field when you invoke an Open, Create, or Display Service. RMS also returns a value in this field for the Parse service unless you take the syntax check option (NAM$V_SYNCHK in the NAM$B_NOP field is clear).

For DECnet for OpenVMS operations, this field represents the actual characteristics of the target device when a Create, Open, or Display service is invoked. It is not filled in when a Parse service is invoked using a file specification that contains a node name.

The default file specification string address (DNA) field provides the address of a file specification string RMS uses to apply defaults for any missing components of the file specification. This field works with the FAB$B_DNS field, which initializes the default file specification string size, to provide a default file specification string. Defaults are applied after RMS examines the primary file specification string to which the FAB$L_FNA field (described in Section 4.15, “FAB$L_FNA Field”) points.

This field and the FAB$B_DNS field correspond to the FDL attribute FILE DEFAULT_NAME.

The FAB$L_DNA field contains the symbolic address of a default file specification string, which is an ASCII string containing one or more components of a file specification. The components in the string must be in the order in which they would occur in a complete file specification.

The FAB$L_DNA (input only) field is equivalent to the NAML$L_LONG_DEFNAME field of the long name (NAML) block. See Chapter 6, Long Name Block (NAML) for more information.

The default file specification string is used only if components are missing from the string whose address is stored in the FAB$L_FNA field and those components are present in the default file specification string.

The default file specification string size (DNS) field indicates the size, in bytes, of the string whose address is contained in the FAB$L_DNA field. This field contains a numeric value in the range 0 to 255.

This field and the FAB$L_DNA field correspond to the FDL attribute FILE DEFAULT_NAME.

The file access (FAC) field specifies the operations and services a process is seeking to use in accessing a file. RMS uses this field, together with the share field (SHR) in each potential accessor's FAB, to determine whether to permit a process to access a file. The FAC field corresponds to the FDL primary attribute ACCESS.

Within the FAC field, each bit position corresponds to an operation or service option that the process intends to use when accessing the file. In this manner, a process may specify several options, assuming they are compatible, by setting the appropriate bits. Each option has its own symbolic bit offset and mask value. For example, the GET service option has a symbolic bit offset of FAB$V_GET and a mask value of FAB$M_GET.

When RMS attempts to open a file for a process, it examines the process's FAB$B_FAC field to determine what operations or services the process is seeking to use in conjunction with the file access.

RMS determines whether or not the process seeking access to the file intends to use operations and services that are compatible with the sharing options permitted by processes currently accessing the file. It checks the FAC field of the requesting process to determine whether it requires read or write access to the file. It then checks the SHR field of the requesting process to determine whether it will share read or write access with other processes that are accessing the file. A read (GET) implies read access. Delete (DEL), write (PUT), truncate (TRN), and update (UPD) all imply write access.

For example, assume that Process A opens the file for GET access (FAC=GET) and is willing to share the file with processes that are doing GET and PUT accesses (SHR=GET,PUT). Since this is the only process accessing the file, RMS permits it to read access the file.

Assume that a second process, Process B, wants to access the same file doing PUT accesses (FAC=PUT) and is willing to share the file with processes doing GET accesses and PUT accesses (SHR=GET,PUT). Because Process B is compatible with Process A (they both agree to share the file with any process that is doing either GET accesses or PUT accesses), RMS permits the second process to access the file.

Now assume that a third process, Process C, wants GET access (FAC=GET) to the same file but will share the file only with processes doing GET accesses (SHR=GET). Although Process C is compatible with Process A (FAC=GET), it is not compatible with Process B (FAC=PUT), so RMS denies Process C access to the file. Conversely, if C tries to access the file before B, C gets access and B is denied access.

RMS always grants file access to the first process accessing a file, assuming no security access restrictions exist. When a process acquires access to a file, RMS rejects any attempt to use a service not included in the initial access request.

Options

FAB$V_BIO

Requests file access for doing block I/O operations that use Read (FAB$V_GET), Write (FAB$V_PUT), or the Space services. Specifying block I/O prohibits the use of record I/O operations (such as the Get, Put, Update, Delete, or Truncate services).

This option corresponds to the FDL attribute ACCESS BLOCK_IO.

FAB$V_BRO

Requests file access for doing either block I/O or record I/O as determined by the state of the RAB$V_BIO bit in the RAB at connect time. Mixed block and record I/O operations are restricted to sequential files. For additional information, see Section 7.19, “RAB$L_ROP Field” and Section B.3.10, “Using Block I/O”.

This option corresponds to the FDL attribute ACCESS RECORD_IO.

FAB$V_DEL

Requests file access for invoking the Delete service (or the equivalent language statement that deletes a record). This option applies only to relative and indexed files.

This option corresponds to the FDL attribute ACCESS DELETE.

FAB$V_GET

Requests file access for invoking either the Get or Find service (or equivalent language statement that reads a record). This is the default if a process requests access to a file without including FAB$B_FAC field information. If the process takes the FAB$V_GET option together with either the FAB$V_BIO option or the FAB$V_BRO option, it can invoke the Read service.

This option corresponds to the FDL attribute ACCESS GET.

FAB$V_PUT

Requests file access for invoking either the Put or Extend service (or the equivalent language statement that writes a record or extends a file). This is the default when a process creates a file. If the process takes the FAB$V_PUT option together with either the FAB$V_BIO option or the FAB$V_BRO option, it can invoke the Write service.

This option corresponds to the FDL attribute ACCESS PUT.

FAB$V_TRN

Requests file access for invoking the Truncate service (or the equivalent language statement that truncates a file). Also allows use of the RAB$L_ROP truncate-on-put (RAB$V_TPT) option with the Put and Write service. This option applies only to sequential files.

This option corresponds to the FDL attribute ACCESS TRUNCATE.

FAB$V_UPD

Requests file access for invoking either an Update or Extend service (or the equivalent language statement that rewrites a record or extends a file). Also allows use of the RAB$L_ROP update-if (RAB$V_UIF) option for the Put service.

This option corresponds to the FDL attribute ACCESS UPDATE.

The file specification string address (FNA) field works with the FAB$B_FNS field to specify the primary file specification of the file to be processed. If this string does not contain all the components of a full file specification, RMS uses the defaults supplied in the default file specification string (see FAB$L_DNA and FAB$B_DNS). If no default string is present, or if the file specification is still incomplete, RMS provides additional defaults.

This field contains the symbolic address of a file specification string, which is an ASCII string containing one or more components of a file specification. This field is used as input by many file-processing services. To obtain the file specification returned by RMS after it translates any logical names and applies defaults, a NAM or NAML block must be present (see FAB$L_NAM).

This field and the FAB$B_FNS field correspond to the FDL attribute FILE NAME.

The FAB$L_FNA field is equivalent to the NAML$L_LONG_FILENAME field of the long name block (NAML). See Chapter 6, Long Name Block (NAML) for more information.

The file specification string size (FNS) field specifies the size, in bytes, of the ASCII file specification string, whose address is contained in the FAB$L_FNA field. This field contains a numeric value in the range of 0 through 255.

This field and the FAB$L_FNA field correspond to the FDL attribute FILE NAME.

FAB$L_FOP is the symbolic offset value for the FAB's file-processing options (FOP) field. This field specifies which of the various optional file operations are to be implemented for the process.

FOP=SPL

As detailed in the appropriate descriptions, the only file-processing option bits that may be affected by record management services are the FAB$V_CBT, FAB$V_CTG, FAB$V_RCK, and FAB$V_WCK bits.

Allocation and Extension Options

FAB$V_CBT

Contiguous best try; indicates that the file is to be allocated contiguously on a “best effort” basis. It is input to the Create service and output from the Open service to indicate the file status. The FAB$V_CBT option overrides the FAB$V_CTG option. Note that this option is ignored if multiple areas are defined for an indexed file.

This option corresponds to the FDL attribute FILE BEST_TRY_CONTIGUOUS.

FAB$V_CTG

Contiguous; indicates that the space for the file is to be allocated contiguously. If this cannot be done, the operation fails. It is input to the Create service and is output by the Open service to indicate the status of the file. Note that this option is ignored if multiple areas are defined for an indexed file. The FAB$V_CBT option overrides the FAB$V_CTG option.

This option corresponds to the FDL attribute FILE CONTIGUOUS.

FAB$V_TEF

Truncate at end of file; indicates that unused space allocated to a file is to be deallocated on a Close service. This option is tested only at $CLOSE time. When a writer requests this option at close, if other readers are still accessing the file, the file systems defers the actual file truncation until the last reader closes the file. The system still returns a success status. The last truncation request made by a writer before the last close has precedence over any previous deferred truncation. Once the file system starts the truncate operation, the file is locked from other writers until the truncate operation is done.

The FAB$V_TEF option applies only to sequential files.

This option corresponds to the FDL attribute FILE TRUNCATE_ON_CLOSE.

File Name Parsing Modifiers

FAB$V_CIF

Create if nonexistent; creates and opens a file and returns the alternate success status RMS$_CREATED, assuming the file does not exist. If you specify an existing file, RMS opens it. Note that if you specify the CIF option for an indexed file, you need to provide a key XAB. If you do not provide a key XAB, RMS returns an RMS$_NPK error.

The FAB$V_CIF option is input only to the Create service and overrides the FAB$V_SUP option. When the create-if option is used with a search list logical name and the file is not found in any of the file specifications supplied using the search list, the file is created using the file specification from the first element of the search list.

This option corresponds to the FDL attribute FILE CREATE_IF.

FAB$V_MXV

Maximize version number; indicates that the version number of the file should be the maximum of the explicit version number given in the file specification, or one greater than the highest version number for an existing file in the same directory with the same file name and file type. This option enables you to create a file with a specific version number (if the requested version number is greater than that of the existing file) or a file with a version number that is one higher than the existing file's version number.

This option is used as input to the Create service only and it corresponds to the FDL attribute FILE MAXIMIZE_VERSION (default is “YES”).

FAB$V_NAM

Use NAM or NAML block inputs; indicates that the NAM or NAML block whose address is contained in the FAB$L_NAM (name block address) field provides the device, file, and/or the directory identification when a file is being opened, closed, or erased (deleted). If a file is being created, the field specifies the device and directory identification.

This option has no corresponding FDL attribute and it is not supported for DECnet for OpenVMS operations.

FAB$V_OFP

Output file parse; specifies that related file resultant file specification strings, if used, are to provide directory, file name, and file type defaults only (requires NAM or NAML block).

This option corresponds to the FDL attribute FILE OUTPUT_FILE_PARSE.

FAB$V_SUP

Supersede existing file; allows an existing file to be superseded on a Create service by a new file of the same name, type, and version. The FAB$V_CIF and the FAB$V_MXV option take precedence over the FAB$V_SUP option.

This option corresponds to the FDL attribute FILE SUPERSEDE.

File Disposition Options

FAB$V_DLT

Delete file on Close; indicates that the file is to be deleted when closed. This option may be specified for the Create, Open, or Close services. However, if you set the bit when you create or open a file, RMS deletes the file when you close it, regardless of the state of the bit when you invoke the Close service. You can specify the FAB$V_DLT option with the FAB$V_SCF or FAB$V_SPL option.

This option corresponds to the FDL attribute FILE DELETE_ON_CLOSE.

FAB$V_ERL

Erase regardless of lock; allows a file open for write access to be marked for delete by the $ERASE service. The erase operation will complete once the file's reference count reaches zero.

This option can only be specified for the Erase service.

FAB$V_SCF

Submit command file on Close; indicates that the file is to be submitted as a batch-command file to the process-default batch queue (SYS$BATCH) when the file is closed. This option can be specified for the Create, Open, and Close services. However, if you set the bit when you create or open a file, RMS submits the file to SYS$BATCH when you close it, regardless of the state of the bit when you invoke the Close service.

The FAB$V_SCF option applies to sequential files only and it corresponds to the FDL attribute FILE SUBMIT_ON_CLOSE.

FAB$V_SPL

Spool file on Close; indicates that the file is to be spooled to the process-default print queue (SYS$PRINT) when the file is closed. This option can be specified for the Create, Open, or Close services. However, if you set the bit when you create or open a file, RMS spools the file to SYS$PRINT when you close it, regardless of the state of the bit when you invoke the Close service.

The FAB$V_SPL option applies to sequential files only and it corresponds to the FDL attribute FILE PRINT_ON_CLOSE.

FAB$V_TMD

Temporary file marked for delete; indicates that a temporary file is to be created but is to be deleted when the file is closed. This option is input only to the Create service. The FAB$V_TMD option takes precedence over the FAB$V_TMP option.

This option corresponds to the FDL attribute FILE TEMPORARY.

FAB$V_TMP

Temporary file; indicates that a temporary file is to be created and retained, but that no directory entry is to be made for it. This option is used solely as input to the Create service. If you have a NAM or NAML block, you are given the file identification (FID) of the file, which you can use to reopen the file. If you do not have a NAM or NAML block or if you do not save the FID, the file becomes inaccessible once it is closed. The FAB$V_TMD option overrides the FAB$V_TMP option.

This option corresponds to the FDL attribute FILE DIRECTORY_ENTRY (“NO” means this bit is set).

Magnetic Tape Processing Options

FAB$V_NEF

Do not position to end of file; inhibits positioning to the end of a file when a tape file is opened and the FAB$B_FAC (file access) field indicates a Put service.

This option corresponds to the FDL attribute FILE MT_NOT_EOF.

FAB$V_POS

Current position; directs RMS to position the magnetic tape volume set immediately after the most recently closed file (the current position) when it opens the next file. If you use this option when you invoke the Create service, RMS begins overwriting data beginning with the current tape position.

The FAB$V_POS option corresponds to the FDL attribute FILE MT_CURRENT_POSITION and is superseded by the FAB$V_RWO option, where applicable.

FAB$V_RWC

Rewind file on Close; specifies that the magnetic tape volume is to be rewound when the file is closed. This option can be specified for the Close, Create, or Open services.

This option corresponds to the FDL FILE attribute MT_CLOSE_REWIND.

FAB$V_RWO

Rewind on Open; specifies that the magnetic tape volume is to be rewound before the file is opened or created. If you use this option when you invoke the Create service, RMS overwrites the tape beginning with the first file. The FAB$V_RWO option takes precedence over the FAB$V_POS option.

This option corresponds to the FDL FILE attribute MT_OPEN_REWIND and takes precedence over the FAB$V_POS option, where applicable.

Nonstandard Processing Options

FAB$V_NFS

Non-file-structured; indicates (on an Open or Create service) that the volume is to be processed in a non-file-structured manner.

The FAB$V_NFS option corresponds to the FDL attribute FILE NON_FILE_STRUCTURED and it is not supported for DECnet for OpenVMS operations.

FAB$V_UFO

User file open; indicates that RMS operations for this file are limited to opening it or creating it. To perform additional processing of the file, invoke the $QIO system service using the channel number returned by RMS in the status value field (FAB$L_STV). This channel is assigned the access mode of the caller unless otherwise specified by the FAB$V_CHAN_MODE bits.

If you specify this option, you must set the FAB$B_SHR field FAB$V_UPI bit option unless the file is not shared (FAB$B_SHR field FAB$V_NIL option is set). For the Create service, the end-of-file mark is set to the end of the block specified in the FAB$L_ALQ field on input. For either the Open or Create services, the FAB$W_IFI field is set to 0 on return to indicate that RMS cannot perform any more operations (including the Close service) on the file. If you set the FAB$V_UFO option with the Open or Create service, the channel needs only to be deassigned when you finish with the file.

This option corresponds to the FDL attribute FILE USER_FILE_OPEN and it is not supported for DECnet for OpenVMS operations.

Performance Options

FAB$V_ASY

Asynchronous; indicates that the specified task is to be done asynchronously. The FAB$V_ASY option is relevant only to file tasks that involve I/O operations. The asynchronous I/O option is typically used with success/error ASTs, or in conjunction with the $WAIT service, to synchronize the program with task completion. When you specify FAB$V_ASY, you pass the address of the FAB as an argument to the AST routine and RMS returns control to your program immediately.

This option corresponds to the FDL attribute FILE ASYNCHRONOUS.

FAB$V_DFW

Deferred write; indicates that writing back to the file of modified I/O buffers is to be deferred until the buffer must be used for other purposes. This option applies to relative files, indexed files, and sequential files opened for shared access.

This option corresponds to the FDL attribute FILE DEFERRED_WRITE and is not supported for DECnet for OpenVMS operations.

FAB$V_SQO

Local File Accesses

Sequential only; indicates that the file can be processed only in a sequential manner, permitting certain processing optimizations. Any attempt to perform random access results in an error. This option is restricted to sequential files and is ignored for all other file organizations. The FAB$V_SQO option is input to the Create and Open services.

Remote DECnet Accesses

For OpenVMS DECnet operations, this option has an added meaning. When set for a remote file access, it indicates that file transfer mode (FTM) should be used for Get, Put, Read, and Write services. File transfer mode is a Data Access Protocol (DAP) feature that allows several records to be transferred in a single-network I/O operation to maximize throughput for sequential access file transfers.

While the file transfer mode (FTM) feature for the SQO option is applied regardless of file organization to remote accesses, FTM has restrictions to make it consistent with the sequential only meaning applied to local accesses. For a remote file access, FTM is restricted to sequential access; if FTM is requested (FAB$V_SQO option set), a keyed or RFA record access will fail with an RMS-F-FTM error (network file transfer mode precludes operation (SQO set)). For record I/O, FTM is also restricted to Gets or Puts; Updates or Deletes, if attempted, will fail with the RMS-F-FTM error.

The transmitting of records as a block of data, of course, results in performance improvement; what is not as obvious is that some of the improvement is due to the fact that the Data Access Protocol (DAP) eliminates much of its messaging for the FTM feature. Messages are not sent between the local and remote systems on a record-by-record basis but rather for the whole block of records transferred. This can result in apparent inconsistencies in what a reader sees when FTM is used.

While the RMS default locking behavior does not change when FTM is used, by the time the record is in your buffer on the local system, the record may have already been updated or deleted by another process that is not using FTM. If a locking collision happens on the remote system when the records are being loaded into the message buffer, then the locking error will not be returned until the end of the transfer. When using the file transfer mode (SQO) feature with shared write access to a remote file, you should expect to see the same kind of inconsistencies in reading data as you see when the read-regardless (RRL) option is set. To avoid the possibility of a hang that may be induced by retrying remote accesses after a record lock error, you are advised to set both the no-lock (NLK) and read-regardless (RRL) options in the RAB$L_ROP in applications that use the file transfer mode (SQO) feature for remote file accesses. (The no query locking (NQL) option is not supported by the DAP protocol for remote files.)

This option corresponds to the FDL attribute FILE SEQUENTIAL_ONLY.

FAB$V_SYNCSTS

Synchronous status; returns the success status RMS$_SYNCH if the requested service completes its task immediately. The most common reason for not completing a task immediately is that the task involves I/O operations. If the service completes synchronously (that is, it has not returned to caller's execution mode prior to completion), RMS returns RMS$_SYNCH as the completion status in R0, stores the true completion status (success or failure) in FAB$L_STS, and does not deliver an AST.

The FAB$V_SYNCSTS option is best used in conjunction with the FAB$V_ASY option.

The system returns RMS$_SYNCH status in R0. Refer to the FAB$L_STS field for the actual success status or failure status of the task.

Reliability Options

FAB$V_RCK

Read-check; specifies that transfers from disk volumes are to be checked by a read-compare operation, which effectively doubles the amount of disk I/O at some increase in reliability. This option is an input to the Open and Create services. If FAB$V_RCK is set, then checking is performed for the duration of the access. The FAB$V_RCK option is also an output of the Open service, which indicates the default for the file. This option is not available for RX01 and RX02 devices, or for any device that has been mounted using the DCL command MOUNT/FOREIGN.

This option corresponds to the FDL attribute FILE READ_CHECK.

FAB$V_WCK

Write-check; indicates that transfers to disk volumes are to be checked by a read-compare operation. The FAB$V_WCK option is similar to the FAB$V_RCK option. This option is not available for RX01 and RX02 devices, or for any device that has been mounted using the DCL command MOUNT/FOREIGN.

This option corresponds to the FDL attribute FILE WRITE_CHECK.

The fixed-length control area size (FSZ) field is used only for variable with fixed-length control (VFC) records. When you create a file with this record type, you must set the value for the fixed-control area before you issue the Create service. When you open an existing file that contains variable with fixed control records, RMS sets this field equal to the value specified when the file was created. The FAB$B_FSZ field is not applicable to indexed files.

This field corresponds to the FDL attribute RECORD CONTROL_FIELD_SIZE.

This field contains a numeric value in the range of 1 to 255 that indicates, in bytes, the size of the fixed control area; the default size is 2 bytes. If you do not specify a value or specify 0, then the default size is used.

The global buffer count (GBC) field indicates the requested number of global buffers for a file. This field contains a numeric value in the range of 0 to 32,767; the default is 0.

Global buffers support sharing of I/O buffers by more than one process. The use of global buffers can minimize I/O operations for a shared file, thus reducing record access time at the cost of using additional system resources. RMS is able to locate requested records (or blocks) in the global buffers associated with this file, which it can read directly from memory, eliminating much I/O. However, since global buffers use global sections, the value contained in FAB$W_GBC is limited by systemwide restrictions on resources determined by the system parameters GBLSECTIONS (number of global sections), GBLPAGES (number of global page table entries), and GBLPAGFIL (number of systemwide pages allowed for global page-file sections, or scratch global sections). For a complete description of these parameters, see the VSI OpenVMS System Management Utilities Reference Manual.

If global buffers are specified for a file, global buffers are used instead of local (process) buffers, with the exception of deferred write operations (FAB$L_FOP field FAB$V_DFW option).

The value that is specified when the file is created is returned in the FAB$W_GBC field as output from the Open service. This value is then used as input to the Connect service.

If you want to override the default value specified when the file was created, you can set a different value in the FAB$W_GBC field after opening the file but before invoking the Connect service. If you do not want to use global buffers, you can clear the field before issuing the Connect service if the default value is not 0.

If you modify the value in the FAB$W_GBC field that is returned from the Open service prior to the Connect service, this action determines whether or not global buffers are assigned to your process.

SET FILE file-spec /GLOBAL_BUFFERS=buffer-count

SET FILE file-spec /GLOBAL_BUFFERS=0

You can also vary the number of global buffers used each time you process the file. If you choose this method, you change (or clear) the FAB$W_GBC field after you open the file, but before you invoke the Connect service. In this case, the specified value is assigned to the FAB$W_GBC field, or the FAB$W_GBC field remains clear only for the current processing of the file; that is, you do not permanently alter the FAB$W_GBC field in the FAB. If no value is specified in the FAB$W_GBC field when the file is created, the default value is 0.

The number of global buffers for a file is determined by the first record stream to connect to the file (systemwide). If the file is already open and connected, then the number of global buffers is already set and modifications made before the Connect service are useful only to request that this process use (or not use) global buffers.

To specify a read-only global buffer cache, the initial accessor must set the FAB$B_SHR field FAB$V_SHRGET and FAB$V_MSE bits on. Selecting the FAB$V_MSE option turns on locking to coordinate access to the global buffer cache.

You can use global buffers for all file organizations opened for shared record access. If the global buffer count is nonzero for the first process that connects to the file, then a temporary global section that is large enough to contain the specified number of buffers (as well as internal RMS data structures) is created and mapped. This section is mapped by processes that subsequently connect to the file, thus allowing multiple processes to reference a single set of one or more buffers without performing additional I/O operations. Thus, the first user to open the file requesting global buffers determines the number of the global buffers. For shared sequential file operations, the value stored in the RAB$B_MBC field establishes the global buffer size. See Section 7.11, “RAB$B_MBC Field” for more information.

The FAB$W_GBC field corresponds to the FDL attribute FILE GLOBAL_BUFFER_COUNT and it is not supported for DECnet for OpenVMS operations.

The internal file identifier (IFI) field associates the FAB with the corresponding internal file access block. RMS sets this field on successful Create or Open services. It is then an input for subsequent Close, Connect, Display, and Extend services. The Close service deallocates the internal control structures and clears the FAB$W_IFI field. When the user file open (FAB$V_UFO) option in the FAB$L_FOP field is specified, no internal structures are allocated on Create or Open services. Therefore, the FAB$W_IFI field remains cleared.

There is no FDL equivalent for this field.

You can obtain additional information about a file marked for journaling using the journaling XAB. For example, you can obtain the name of the after-image journal file, and so forth.

$OPEN   FAB = MY_FAB 
BLBC    R0,ERROR 
BBS     #FAB$V_RU,FAB$B_JOURNAL+MY_FAB,- 
        FILE_MARKED_FOR_RU

There are no corresponding FDL attributes for the journaling flags because they cannot be set through the FDL interface.

A listing of symbolic offsets for each of the journaling flags follows:

Flags

FAB$V_AI

The file is marked for after-image journaling.

FAB$V_BI

The file is marked for before-image journaling.

FAB$V_RU

The file is marked for recovery unit journaling.

The logical name translation access mode (LNM_MODE) subfield is the part of the FAB$B_ACMODES field that specifies the RMS access mode used to translate logical names during parsing.

The FAB$V_LNM_MODE field is not supported for DECnet for OpenVMS operations, and it is ignored during remote file access.

There is no corresponding FDL equivalent for this field. For more information about logical name concepts, see the VSI OpenVMS Programming Concepts Manual, Volume II.

The maximum record number (MRN) field applies only to relative files and indicates the highest record number that can be written to a file.

This field contains a numeric value of the highest numbered record allowed in the file, in the range of 0 to 2,147,483,647, although the maximum value depends on the number of blocks on the device to be used. The default for this field is 0.

If you attempt to write (put) or retrieve (get) a record with a relative record number higher than the specified limit, an error occurs and RMS returns a message indicating an invalid record number. Checking is suppressed if you specify 0 for the FAB$L_MRN field.

Note that RMS does not maintain the relative record number of the highest existing record in the file.

This field corresponds to the FDL attribute FILE MAX_RECORD_NUMBER.

The maximum record size (MRS) field defines the size of all records in a file with fixed-length records, the maximum size of variable-length records, the maximum size of the data area for variable with fixed-length control records, and the cell size (minus overhead) for relative files.

This field contains a numeric value in the range applicable to the file type and record format (see Table 4.4, “Maximum Record Size for File Organizations and Record Formats”) that indicates the size of the records in the file, in bytes. This value specifies the number of bytes of data and does not include any control bytes associated with each record.

For fixed-length records, the value represents the actual size of each record in the file. You must specify a size when you create a file with fixed-length records.

For variable-length records, the value represents the size of the largest record that can be written into the file. If the file is not a relative file, a value of 0 is used to suppress record size checking, thus indicating that there is no user limit on record size, except for the limitations listed in Table 4.4, “Maximum Record Size for File Organizations and Record Formats” and certain physical limitations. For magnetic tape files, a value of 0 sets an effective maximum record size that is equal to the block size minus 4.

The size of variable-length records must conform to physical limitations. With indexed and relative files, for example, records may not cross bucket boundaries. If both the FAB$B_BKS and FAB$W_MRS fields are 0 (not specified) for an indexed file, RMS attempts to calculate a reasonable bucket size, usually 2. Thus, if any record requires more than two buckets, you must explicitly specify the required value for the FAB$B_BKS or the FAB$W_MRS field. If the FAB$B_BKS field is specified, the value should specify a bucket size large enough to exceed the longest possible record.

For variable with fixed-length control records, the value includes only the data portion; it does not include the size of the fixed control area.

For all relative files, the size is used in conjunction with the FAB$B_BKS field to determine the size of the record cell. You must specify the FAB$W_MRS field when you create a relative file.

You specify a value when you invoke a Create service. RMS returns the maximum record size when you invoke an Open service.

For DECnet for OpenVMS remote file access, the maximum record size may be set by the /NETWORK_BLOCK_COUNT=n qualifier to the SET RMS_DEFAULT command or by a $XABITM parameter. DECnet for OpenVMS remote file access can support record sizes as large as the record sizes that RMS supports. The default number of blocks is equal to the system parameter RMS_DFNBC, the default for which is 8 blocks (4096 bytes). For more information about the SET RMS_DEFAULT command, see the VSI OpenVMS DCL Dictionary. The system parameters are detailed in the VSI OpenVMS System Management Utilities Reference Manual.

This field corresponds to the FDL attribute RECORD SIZE.

The name block field specifies the address of either the name (NAM) block (see Chapter 5, Name Block (NAM)) or the long name (NAML) block (see Chapter 6, Long Name Block (NAML)) used to invoke a file service, such as an Open or Create. On Alpha systems, the NAML block can optionally take the place of a NAM block. The NAML allows OpenVMS Alpha users to locate and use file specifications that are longer than 255 bytes.

The NAM or NAML block is required only in conjunction with the file specification processing services. Both can also be used with other services, typically to obtain a file specification string after all logical name translation is completed and all defaults applied.

To allow for appropriate type checking of a NAML block, FAB$L_NAML is available as an alternative definition for C programmers who are using a NAML block.

For further information, see Section 4.17, “FAB$L_FOP Field” and Chapter 6, Long Name Block (NAML).

The file organization (ORG) field assigns the organization of the file.

The FAB$B_ORG field is a keyword value field in which each file organization has a symbolic value. Options are identified using 3-letter mnemonics. Each option in the FAB$B_ORG field has its own symbolic constant value. For example, the relative (REL) file organization has a constant value of FAB$C_REL.

The record attributes (RAT) field specifies control information associated with each record in a file, including carriage control information, block boundary control, and count byte formatting for variable-length records. Within the FAB$B_RAT field, each control bit has a unique symbolic offset and constant value. For example, the CR (carriage return) control bit has a symbolic offset of FAB$V_CR and a mask value of FAB$M_CR.

For most programs, the default value for the carriage control is FAB$V_CR (carriage return). When you create your own file, however, the default value is 0. When you want to create a stream format file or a file containing ASCII text, specify the FAB$V_CR option for the Create service. RMS sets this field when you invoke an Open service.

When a process-permanent file is accessed indirectly for output, the value in this field is always an input value. Therefore, RMS automatically uses the process-permanent file's record attributes.

This field corresponds to the FDL primary attribute RECORD.

Options

FAB$V_CR

Indicates that each record is to be preceded by a line feed and followed by a carriage return when the record is written to a carriage control device such as a line printer or terminal.

This option corresponds to the FDL attribute RECORD CARRIAGE_CONTROL CARRIAGE_RETURN. It cannot be used with either the FAB$V_FTN option or the FAB$V_PRN option.

FAB$V_FTN

Indicates that the first byte of each record contains a FORTRAN (ASA) carriage control character.

FAB$V_PRN

Indicates print file format for variable-length records having 2-byte fixed-length control fields, where the fixed-length control area contains the carriage control specification. The first byte of the control area constitutes a “prefix” area, that is, action to be taken before printing the record. The second byte constitutes a “suffix” area, that is, action to be taken after printing the record.

FAB$V_BLK

Applicable to sequential files only; indicates that records are not permitted to cross block boundaries. The FAB$V_BLK record attribute option may be used with any one of the other record attribute options (FAB$V_CR, FAB$V_FTN, or FAB$V_PRN), but it cannot be used with files that use the STREAM record format.

This option corresponds to the FDL attribute RECORD BLOCK_SPAN.

FAB$V_MSB

The state of this control bit determines whether the format for the 2-byte count field that is prefixed to each variable-length record is formatted as LSB or MSB. If the bit is set, RMS reads the contents of the 2-byte count field using the most significant byte as the high-order byte. The 2-byte count field contains the number of bytes in the associated variable-length record.

This option corresponds to the FDL attribute RECORD MSB_RECORD_LENGTH.

The record format (RFM) field specifies the format for all the records in a file.

The FAB$B_RFM field is a keyword value field where each record format has a symbolic value. Options are identified by mnemonics. Each option has its own symbolic constant value. For example, the FIX (fixed) record format has a symbolic constant value of FAB$C_FIX; the STMCR (stream with carriage return) record format has a symbolic constant value of FAB$C_STMCR.

When you create the file, you must set this field before you invoke the Create service. RMS returns the record format when you invoke an Open service. The record format options are described under Options.

This field corresponds to the FDL attribute RECORD FORMAT.

Options

FAB$C_FIX

Indicates fixed-length record format.

This option corresponds to the FDL attribute RECORD FORMAT FIXED.

FAB$C_STM

Indicates stream record format. Records are delimited by FF, VT, LF, or CR LF, and all leading zeros are ignored. This format applies to sequential files only and cannot be used with the block spanning option.

This option corresponds to the FDL attribute RECORD FORMAT STREAM.

FAB$C_STMCR

Indicates stream record format. Records are delimited by CR. This format is supported for sequential files only.

This option corresponds to the FDL attribute RECORD FORMAT STREAM_CR.

FAB$C_STMLF

Indicates stream record format. Records are delimited by LF. This format is supported for sequential files only.

This option corresponds to the FDL attribute RECORD FORMAT STREAM_LF.

FAB$C_UDF

Indicates undefined record format. The undefined record format is valid for sequential files only. This is the default value if the FAB is not initialized with a $FAB macro.

This option corresponds to the FDL attribute RECORD FORMAT UNDEFINED.

FAB$C_VAR

Indicates variable-length record format. For the $FAB macro, this is the default value.

This option corresponds to the FDL attribute RECORD FORMAT VARIABLE.

FAB$C_VFC

Indicates variable-length with fixed-length control record format. This format is not supported for indexed files.

This option corresponds to the FDL attribute RECORD FORMAT VFC.

If you intend to use stream record format, then specify the FAB$V_CR record attribute (see FAB$B_RAT).

The retrieval window size (RTV) field specifies the number of retrieval pointers RMS is to maintain in memory for the file. Retrieval pointers are stored in the file header and indicate the beginning of each extent associated with the file. If a file has been extended repeatedly, the extents may be scattered noncontiguously on the disk, requiring numerous retrieval pointers. When RMS needs to access a new extent, it must obtain the retrieval pointer for that extent. RMS first looks for the retrieval pointer in the retrieval window, which contains the number of retrieval pointers specified by this field. If the retrieval pointer is not in the retrieval window, RMS reads the file header, thereby requiring an additional I/O operation.

This field contains a numeric value in the range of 0 through 127, or 255. A value of 0 directs RMS to use the system default number of retrieval pointers. A value of 255 means to map the entire file, if possible. If you specify a value of 255 when creating a file, the initial number of retrieval pointers is minimal; as records are added, however, the number of retrieval pointers increases as the number of extents increases. The system resources required for retrieval windows are subtracted from the buffered I/O quota of the process. Values from 128 to 254 (inclusive) are reserved for future use.

This field corresponds to the FDL attribute FILE WINDOW_SIZE and it is not supported for DECnet for OpenVMS operations.

The secondary device characteristics (SDC) field is equivalent to the FAB$L_DEV field, except that secondary device characteristics refer to the intermediate device used for spooling or the logical link for DECnet for OpenVMS operations. Within the FAB$L_SDC field, the bit definitions are the same as those defined for the FAB$L_DEV field (see Table 4.2, “Device Characteristics”). Like the FAB$L_DEV field, the bit definitions must first be made available to your process referring to the $DEVDEF system macro definition; the values are set by certain record management services (see FAB$L_DEV for additional information).

The file sharing (SHR) field defines the record operations that the opening process allows sharing processes to perform. RMS supports file sharing for all file organizations.

Within the FAB$B_SHR field, each record operation that sharing processes are permitted to do has a corresponding bit assignment. You can specify multiple record operations (multiple bits may be set).

Options are identified by symbolic bit offsets. Note that conflicts between the names of symbolic offsets in the FAB$B_SHR field and the names of symbolic offsets in the FAB$B_FAC field are resolved by prefixing the letters SHR to the symbolic offset in the FAB$B_SHR field. For example, both the FAB$B_FAC and FAB$B_SHR fields have a bit that specifies the get record option. In the FAB$B_FAC field, this bit offset is assigned the symbol FAB$V_GET; in the FAB$B_SHR field, this bit is assigned the symbol FAB$V_SHRGET.

Note that the letters SHR in the mnemonic part of the bit offset symbol may be omitted by VAX MACRO programs. Thus, the GET option, which is common to the FAB$B_FAC and FAB$B_SHR fields, has a symbolic bit offset of FAB$V_SHRGET and a mask value of FAB$M_SHRGET, but VAX MACRO programs may use the synonyms FAB$V_GET and FAB$M_GET. This rule applies to the FAB$V_SHRPUT, FAB$V_SHRGET, FAB$V_SHRDEL, and FAB$V_SHRUPD options.

The way in which RMS uses the file access (FAB$B_FAC) field and file sharing (FAB$B_SHR) field is described in greater detail in the FAB$B_FAC field discussion.

The following list includes descriptions of the sharing options.

Options

FAB$V_MSE

Allows multistream access and is relevant for record operations only. You must specify FAB$V_MSE whenever you want to call Connect services for multiple RABs for this FAB.

Note that if you specify the FAB$V_MSE and FAB$V_BIO options, you must set the FAB$V_UPI bit regardless of the other sharing bits. To specify a read-only global buffer cache, the initial accessor must set the FAB$B_SHR field FAB$V_SHRGET and FAB$V_MSE bits. Selecting the FAB$V_MSE option turns on locking to coordinate access to buffers. The FAB$V_MSE option is not supported for DECnet for OpenVMS operations. RMS returns an error when the application program attempts to connect a second stream. Although RMS cannot perform multistreaming for DECnet for OpenVMS operations, you can obtain similar functionality by using multiple FABs to access the file in a shared manner.

This option is available for all file organizations and corresponds to the FDL attribute SHARING MULTISTREAM.

FAB$V_NIL

Prohibits any file sharing by other users. Setting this option requires the user to have write protection access to the file. If FAB$V_NIL is specified with other options, it takes precedence.

This option corresponds to the FDL attribute SHARING PROHIBIT.

FAB$V_NQL

Requests that RMS disable query locking (see the description of the query record locking option in the VSI OpenVMS Guide to OpenVMS File Applications) for any read operation that has both RAB$V_NLK and RAB$V_RRL set in the RAB$L_ROP field for the entire period the file is open. If both record options are not set, RMS ignores the query disabling request. This option is only processed when some form of write sharing is allowed, and can be set with any combination of the other sharing options in this list that can be assigned to the FAB$B_SHR field.

This option is implemented on the Alpha platform with OpenVMS V7.2–1H1. The FAV$V_NQL symbol facilitates common code and you may specify it in applications that execute on both the Alpha and VAX platforms. The functionality for the option is not implemented on the VAX platform.

This option is not supported for DECnet for OpenVMS operations, and has no corresponding FDL attribute.

FAB$V_SHRPUT

Allows other users to write records to the file or to extend the file.

This option corresponds to the FDL attribute SHARING PUT.

FAB$V_SHRGET

Allows other users to read the file.

This option corresponds to the FDL attribute SHARING GET.

FAB$V_SHRDEL

Allows other users to delete records from the file.

This option corresponds to the FDL attribute SHARING DELETE.

FAB$V_SHRUPD

Allows other users to update records that currently exist in the file or to extend the file.

This option corresponds to the FDL attribute SHARING UPDATE.

FAB$V_UPI

This option is used when the user wants to assume responsibility for interlocking of multiple, simultaneous accessors of a file. This option disables all RMS locking for the current access of the file. Except for block I/O, the FAB$V_MSE option overrides the FAB$V_UPI option. Usually, the FAB$V_UPI option is used for a file that is open for block I/O (FAB$V_BIO or FAB$V_BRO).

When you select the FAB$V_UFO option, you must also select the FAB$V_UPI option if the file is write shared. A file is specified as being write shared when you select either the FAB$V_PUT option, the FAB$V_DEL option, the FAB$V_TRN option, or the FAB$V_UPD option in the FAB$B_SHR field.

This option corresponds to the FDL attribute SHARING USER_INTERLOCK.

RMS sets the completion status code (STS) field with success or failure codes before it returns control to your program (except for a subset of errors, as detailed in Section 2.4, “Service Completion”). Register 0 contains the same status as the STS field. Potential error codes for specific services are listed under their descriptions.

RMS sets the status value (STV) field on the basis of the operation performed and the contents of the completion status code (FAB$L_STS) field, communicates additional completion information to your program.

The extended attribute block address (XAB) field specifies the XAB, or first of a series of XABs, that you want to use for file operations. This field contains the symbolic address of a XAB control block. A value of 0 (the default) indicates no XABs for the file.

For some operations, you must associate extended attribute blocks with a FAB to convey additional attributes about a file. (See Section 1.2.2, “Control Blocks for File Services” for a description of a XAB.) The FAB$L_XAB field can contain the symbolic address of the first associated block (of a potential chained list of such blocks) for the file.

The NAM block fields have no corresponding FDL equivalents. However, if your application requires the presence of a NAM block, consider using the $NAM macro (or equivalent) in a USEROPEN or a USERACTION routine.

Unless otherwise indicated, each field is supported for DECnet for OpenVMS operations on files at remote OpenVMS systems. For information about the support of RMS options for remote file access to other systems, see the VSI OpenVMS DECnet Networking Manual.

Depending on the services to be used, the user may need to allocate program storage for the expanded string and the resultant string. The Parse service uses the expanded string to pass information related to wildcards (or search lists) to the Search service. When it creates a resultant string for other file services, RMS uses the expanded string as a work area to apply defaults. You can use the resultant string with file services to provide the file specification that results from the translation of logical names and the application of defaults. Typical uses of the resultant string include showing the resulting file specification after a partial file specification is entered by a terminal user, reporting errors, and logging the progress of a program.

To request use of the expanded or resultant strings, you must indicate the address and size of the user-allocated buffer to receive the string. The expanded string is indicated by the NAM$L_ESA and NAM$B_ESS fields; the resultant string is indicated by the NAM$L_RSA and NAM$B_RSS fields. When it fills in the expanded or resultant strings, RMS returns the actual length of the returned string in the NAM$B_ESL or NAM$B_RSL fields.

Descriptors

NAM$B_NODE, NAM$L_NODE

Node name descriptor, including access control string and double colon (::) delimiter.

NAM$B_DEV, NAM$L_DEV

Device name descriptor, including colon (:) delimiter.

NAM$B_DIR, NAM$L_DIR

Directory name descriptor, including brackets ([] or <>).

NAM$B_NAME, NAM$L_NAME

File name descriptor or, if the file specification following a node name is within quotation marks (“file”), a quoted string descriptor.

NAM$B_TYPE, NAM$L_TYPE

File type descriptor, including period (.) delimiter.

NAM$B_VER, NAM$L_VER

File version number descriptor, including semicolon (;) or period (.) delimiter.

These descriptors are returned, enabling the program to extract a particular component from the resultant string without having to parse the resultant or expanded string. The entire resultant or expanded string, including delimiters, is described by the various component descriptors. If the value in the NAM$B_RSL field is nonzero, then the descriptors point to the NAM$L_RSA field. If the value in the NAM$B_RSL field is 0 and the value in the NAM$B_ESL field is nonzero, then the descriptors point to the NAM$L_ESA field. In all other cases, they are undefined.

NODE"TEST password"::WORK_DISK:[TEST.TEMP]FILE.DAT;3

   NODE   NODE"TEST password"::
   DEV    WORK_DISK:
   DIR    [TEST.TEMP]
   NAME   FILE
   TYPE   .DAT
   VER    ;3

You can use the file component descriptors individually or collectively to describe sections of the resultant or expanded string. For example, if you want to use the file name and file type fields, use NAM$L_NAME for the starting address and NAM$B_NAME+NAM$B_TYPE for the total length.

The block identifier (BID) field is a static field that identifies this control block as a NAM block. Once set, this field must not be altered unless the control block is no longer needed. This field must be initialized to the symbolic value NAM$C_BID (this is done by the $NAM macro).

The block length (BLN) field is a static field that defines the length of the NAM block, in bytes. Once set, this field must not be altered unless the control block is no longer needed. This field must be initialized to the symbolic value NAM$C_BLN (this is done by the $NAM macro).

RMS fills this field with a pointer into either the expanded string buffer specified by NAM$L_ESA or the resultant string buffer specified by NAM$L_RSA. The pointer in NAM$L_DEV points to the start of the device name within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAM$B_RSS. If NAM$B_RSS is 0, this field points into the buffer specified by NAM$L_ESA. Otherwise, it points into the buffer specified by NAM$L_RSA. The device name is always returned with uppercase letters.

For NAM$B_DEV, RMS fills this field with the length, in bytes, of the device name pointed to by NAM$L_DEV, including the ":".

The directory identification (DID) field identifies the directory for the file. RMS outputs this 3-word field as part of the Open, Create and Display services. RMS also outputs this field as part of the Parse service unless you specify the syntax check option (NAM$V_SYNCHK). If, once you open the file, you want to refer to this directory again, you can do so more quickly by specifying that the NAM block has a valid directory identifier.

This field is not supported for DECnet for OpenVMS operations; it is ignored on input and zero-filled on output.

RMS fills this field with a pointer into either the expanded string buffer specified by NAM$L_ESA or the resultant string buffer specified by NAM$L_RSA. The pointer in NAM$L_DIR points to the directory specification within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAM$B_RSS. If NAM$B_RSS is 0, this field points into the buffer specified by NAM$L_ESA. Otherwise, it points into the buffer specified by NAML$L_RSA.

For NAM$B_DIR fills this field with the length, in bytes, of the directory pointed to by NAM$L_DIR, including the delimiter ] or >.

The device identification (DVI) field defines the device for the file. RMS outputs this field as part of the Open, Create, and Display services. RMS also outputs this field as part of the Parse service unless you specify the syntax check option (NAM$V_SYNCHK). You can use this field with the file identification field to reopen the file by referring to the NAM block. The symbolic value NAM$S_DVI gives the length of this field in bytes. The form of this field is a counted string. The first byte is a count of the number of characters following it.

This field is not supported for DECnet for OpenVMS operations; it is ignored on input and zero-filled on output.

The expanded string area address (ESA) field contains the symbolic address of a user buffer in the application program to receive the file specification string resulting from the translation of logical names and the application of default file specification information.

You must specify this field for processing wildcard characters.

RMS sets the expanded string length (ESL) field as part of the Open, Create, and Parse services. This field contains the length, in bytes, of the file specification string returned in the buffer whose address is in the NAM$L_ESA field.

The expanded string area size (ESS) field contains the size of the user-allocated buffer whose address is contained in the NAM$L_ESA field.

This field contains a numeric value representing the size, in bytes, of the user buffer that will receive the file specification string, in the range of 0 through 255.

The symbolic value NAM$C_MAXRSS defines the maximum possible length of an expanded file specification string.

The file identification (FID) field is a 3-word field that RMS uses to identify the file when it invokes an Open, Create, or Display service. When you want to open a file by using the file identifier, set this field before you open the file.

This field is not supported for DECnet for OpenVMS operations; it is ignored on input and zero-filled on output.

The first wild directory field contains a number that indicates how may levels below the device or root directory RMS first encountered a wildcard. The topmost directory level is numbered 0. If there are no wildcards, this field contains -1.

The following examples illustrate the use of NAM$W_FIRST_WILD_DIR:

For the filespec DKB100:[ROOT1.ROOT2.][*.SUBDIR1.SUBDIR2], NAM$W_FIRST_WILD_DIR would be set to 0.

For the filespec DKB100:[SUBDIR0.*.SUBDIR2], NAM$W_FIRST_WILD_DIR would be set to 1.

For the filespec DKB100:[SUBDIR0.SUBDIR1.SUBDIR2], NAM$W_FIRST_WILD_DIR would be set to -1.

This field is not supported by DECnet for OpenVMS operations.

The file name status (FNB) field is a binary options field that RMS uses to convey status information obtained from the file specification parsing routine. Each bit within this field denotes a specific status relative to the various components of the file specification.

This field contains the total number of directory levels that exist below the device or root directory. The topmost directory level is numbered 0. For directory levels between 0 and 7, this field contains the same number that NAM$V_DIR_LVLS contains. If NAM$V_DIR_LVLS_G7 is set, this field is the only way to find out the number of directory levels.

The following are examples of using NAM$W_LONG_DIR_LEVELS:

For the filespec, DKB100:[ROOT1.ROOT2.][*.SUBDIR1.SUBDIR2], NAM$W_LONG_DIR_LEVELS would be set to 2.

For the filespec, DKB100:[SUBDIR0.SUBDIR1], NAM$W_LONG_DIR_LEVELS would be set to 1.

This field is not supported by DECnet for OpenVMS operations.

RMS fills this field with a pointer into either the expanded string buffer specified by NAM$L_ESA or the resultant string buffer specified by NAM$L_RSA. The pointer in NAM$L_NAME points to the start of the file name within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAM$B_RSS. If NAM$B_RSS is 0, this field points into the buffer specified by NAM$L_ESA. Otherwise, it points into the buffer specified by NAM$L_RSA.

For NAM$B_NAME, RMS fills this field with the length, in bytes, of the file name pointed to by NAM$L_NAME, not including the type field nor the period separating the name from the type.

The name characteristics (NMC) field is a binary field that RMS uses to convey characteristics of file specifications. Each bit within this field denotes a specific status relative to the various components of the file specification.

RMS fills this field with a pointer into either the expanded string buffer specified by NAML$L_NODE or the resultant string buffer specified by NAM$L_RSA. The pointer in NAM$L_NODE points to the start of the node name within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAM$B_RSS. If NAM$B_RSS is 0, this field points into the buffer specified by NAM$L_ESA. Otherwise, it points into the buffer specified by NAM$L_RSA.

For NAM$B_NODE, RMS fills this field with the length, in bytes, of the node name pointed to by NAM$L_NODE, including the ::. Note that if this is not a DECnet file specification, NAM$B_NODE will be 0.

The name block options (NOP) field indicates the options applicable to the file name parsing services.

The NAM$B_NOP field is a binary options field in which each option has a corresponding bit assignment. Multiple options can be specified (multiple bits can be set) but the default state for each bit is clear (not set). Each option has its own symbolic bit offset and mask value. For example, the SYNCHK option has a symbolic bit offset of NAM$V_SYNCHK and a mask value of NAM$M_SYNCHK.

Options

NAM$V_NOCONCEAL

When used with the Open, Create, Parse, Search, or Display services, a concealed device logical name is translated into its physical device name (and directory, if so defined) in the resultant string field, whose address is supplied by the NAM$L_RSA field. If this option is not set and a concealed device name is used, the concealed device name appears in the resultant string field, instead of the physical device name (and directory, if so defined).

NAM$V_NO_SHORT_UPCASE

When set by the user, this option tells RMS not to uppercase the directory and file specification in the NAM$L_ESA buffer.

NAM$V_PWD

When used with the Create, Open, Parse, Search, or Display services, the password in the access control string of a node specification, if present, is returned unaltered in the expanded or resultant file specification fields. If you do not select this option, the actual password used is replaced by the word “password” in the resultant or expanded file specification string fields for security reasons.

NAM$V_SRCHXABS

When used with the Search service for remote file access, this option directs RMS to fill in the FAB and any chained XABs as if a Display service had been invoked. This allows you to obtain file attribute information using the Search service without the need to open the file.

NAM$V_SYNCHK

This gives you the option of using the Parse service to verify the syntax validity of the file specification without invoking I/O processing that verifies the actual existence of the specified device and directory.

If you invoke the Parse service without setting the NAMV_SYNCHK bit, an accompanying I/O process verifies that the device and directory exist. Note that this processing verifies the existence of the device and directory, only; it does not verify the existence of the file. You can only verify the existence of the file using a $SEARCH or $OPEN.

If you opt to set the NAM$V_SYNCHK bit when you invoke the Parse service, RMS does not return the device characteristics (FAB$L_DEV and FAB$L_SDC fields) and does not fill in the NAM$W_DID and NAM$T_DVI fields, rendering the results of the $PARSE unusable for subsequent Search services. It also does not do a directory ID (DID) compression of long path names.

The related file NAM block address (RLF) field contains the symbolic address of the NAM block for the related file. A NAML block may optionally be used. This field supports the secondary file concept of the command language (DCL), giving an extra default level in processing file specifications.

To provide an extra level of file specification defaults, the related NAM or NAML block must have been used previously by an Open, Create, Search, or Display service to create a resultant file specification string. Moving the address of the related NAM block into the NAM$L_RLF field of the current NAM block specifies that the previously parsed NAM block's resultant file specification string should be used as a default when the current NAM block is parsed. Note that the previously parsed NAM block must contain a resultant file specification (see NAM$L_RSA and NAM$B_RSS for additional details).

Note that a NAM can be used in the NAM$L_RLF field of a NAML, and a NAM can be used in the NAML$L_RLF field of a NAML. To allow for appropriate type checking of a NAML block, NAM$L_RLF_NAML is available as an alternative definition for C programmers who are using a NAML block.

Refer to the VSI OpenVMS Guide to OpenVMS File Applications for additional details on file specification parsing concepts.

The resultant string area address (RSA) field contains the symbolic address of a buffer in your program to receive the resultant file specification string. The NAM$B_RSS field must also be specified to obtain a resultant file specification string.

This string is the fully specified name of the file that results from the resolution of all system defaults, including version numbers and wildcard character substitution in the expanded file name string. You must specify this field for wildcard processing.

The resultant string length (RSL) contains the length, in bytes, of the resultant file specification string returned in the buffer whose address is in the NAM$L_RSA field.

The resultant string area size (RSS) field defines the size of the user-allocated buffer whose address is contained in the NAM$L_RSA field.

This field contains a numeric value representing the size, in bytes, of the user buffer that will receive the resultant file specification string, in the range of 0 through 255.

The symbolic value NAM$C_MAXRSS defines the maximum possible length of a resultant file specification string.

RMS fills this field with a pointer into either the expanded string buffer specified by NAM$L_ESA or the resultant string buffer specified by NAM$L_RSA. The pointer in NAM$L_TYPE points to the start of the file type, including the dot separating it from the name, within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAM$B_RSS. If NAM$B_RSS is 0, this field points into the buffer specified by NAM$L_ESA. Otherwise, it points into the buffer specified by NAM$L_RSA.

For NAM$B_TYPE, RMS fills this field with the length, in bytes, of the file type pointed to by NAM$L_TYPE.

RMS fills this field with a pointer into either the expanded string buffer specified by NAM$L_ESA or the resultant string buffer specified by NAM$L_RSA. The pointer in NAM$L_VER points to the start of the file version, including the semicolon separating if from the type, within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAM$B_RSS. If NAM$B_RSS is 0, this field points into the buffer specified by NAM$L_ESA. Otherwise, it points into the buffer specified by NAM$L_RSA.

For NAM$B_VER, RMS fills this field with the length, in bytes, of the file version pointed to by NAM$L_VER.

The wildcard context (WCC) field contains the information needed to use wildcard characters in place of the various file specification components. In particular, this field restarts a directory search to find the next matching file name, type, and/or version number. You can also use it to identify various RMS extended contexts; for instance, during remote file processing.

The NAML has fields that are equivalent to all the NAM fields, plus 28 additional fields to accommodate longer file specifications. The additional fields are not supported for DECnet operations. There are also no equivalent FDL attributes for these additional fields.

Many of the additional fields in the NAML correspond to NAM fields but allow longer names. For example, the fields NAML$L_LONG_EXPAND, NAML$L_LONG_EXPAND_ALLOC, and NAML$L_LONG_EXPAND_SIZE correspond to NAM$L_ESA, NAM$B_ESS, and NAM$B_ESL, but allow names that are longer than 255 bytes. When there are fields that correspond like this, the original field is referred to as a "short field." The corresponding field is referred to as a "long field."

When RMS is writing information into fields in a NAML that have both a short and long version, RMS normally writes the equivalent information into both fields. If either the short field or the long field is too small to contain the information, RMS returns an error, though RMS attempts to compress file specifications to allow them to fit in the short fields. You can prevent RMS from writing into the short fields by setting the flag NAML$V_NO_SHORT_OUTPUT. However, if you are using a NAML, RMS always uses the long fields. If you do not want RMS to use the long fields, you must use a NAM rather than a NAML.

When RMS is reading information from fields in a NAML that has both a short and a long version, RMS always reads from the long version. If you want RMS to read from the short fields, you must use a NAM rather than a NAML. The most common time that RMS reads from these fields is during a $SEARCH operation following a $PARSE, when RMS reads from the buffer pointed to by NAML$L_LONG_EXPAND for a NAML and NAM$L_ESA for a NAM. In addition, if a NAM or NAML is used as a related name block, RMS reads information from the buffer pointed to by NAML$L_LONG_RESULT for a NAML, or NAM$L_RSA for a NAM.

Because of these differences in the way RMS processes a NAM and a NAML, it is important that any code that might come in contact with the NAML be aware that it is a NAML and not a NAM. Several operations that a routine might do on a NAM will not work as expected on a NAML. For example, if a routine makes a copy of a NAML but uses the NAM$C_BLN constant as the length to copy, the result is an illegal NAML. If a routine replaces the buffers pointed to by NAM$L_ESA and NAM$L_RSA with the expectation that it can use the NAM without affecting the calling routine, it misses the buffers pointed to by NAML$L_LONG_EXPAND and NAML$L_LONG_RESULT.

For this reason, any API supplied by OpenVMS adheres to the rule that if it returned a NAM (either directly or indirectly through a FAB) in previous versions, it will not now start returning a NAML without some explicit action by the caller (usually setting a flag bit). We recommend that other APIs use the same rule. Further, if a NAML-aware application passes a NAML to an API, it must be prepared for that API to use only the NAM section (for example, it should not set the NAML$V_NO_SHORT_OUTPUT bit).

If you are writing a routine that is to accept either a NAM or a NAML, you should check the NAM$B_BID field to determine whether you have a NAM or a NAML; if you have a NAML, and you wish to read information that RMS has left in the NAML, look at the information in the long fields. In addition, if you wish to copy that NAM or NAML block to another location, you must be careful to use the length that is stored in the structure itself to determine how much to copy. You should use the NAM$B_BLN field in the structure you are copying rather than the NAM$C_BLN constant, since NAM$B_BLN contains the actual length of the structure. If you use the NAM$C_BLN, which is the length of a NAM, it would be too short for a NAML.

If any of these validation checks fail, a RMS$_NAML error status is returned.

The block identifier (BID) field is a static field that identifies this control block as a NAML block. Once set, this field must not be altered unless the control block is no longer needed. This field must be initialized to the symbolic value NAML$C_BID (this is done by the $NAML macro).

The block length (BLN) field is a static field that defines the length of the NAML block, in bytes. Once set, this field must not be altered unless the control block is no longer needed. This field must be initialized to the symbolic value NAML$C_BLN (this is done by the $NAML macro).

This field contains the address of a user buffer that receives the file name, type, and version in a form appropriate for specifying directly to the file system by the SYS$QIO system service.

This field contains the size of the user-allocated buffer whose address is contained in the NAML$L_FILESYS_NAME field.

RMS sets this field to indicate the length, in bytes, of the name string returned in NAML$L_FILESYS_NAME.

These fields can be used to replace the FAB$L_DNA and FAB$B_DNS fields in the FAB. Using these NAML fields allows you to specify a default name string longer than the 255 bytes allowed by FAB$B_DNS.

RMS uses the NAML$L_LONG_DEFNAME and NAML$L_LONG_DEFNAME_SIZE fields in place of the FAB$L_DNA and FAB$L_DNS fields if FAB$L_DNA contains a -1 and FAB$B_DNS contains 0.

RMS fills this field with a pointer into either the expanded string buffer specified by NAML$L_LONG_EXPAND or the resultant string buffer specified by NAML$L_LONG_RESULT. The pointer in NAML$L_LONG_DEV points to the start of the device name within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAML$L_LONG_RESULT_SIZE. If NAML$L_LONG_RESULT_SIZE is 0, this field points into the buffer specified by NAML$L_LONG_EXPAND. Otherwise, it points into the buffer specified by NAML$L_LONG_RESULT. The device name is always returned with uppercase letters.

For NAML$L_LONG_DEV_SIZE, RMS fills this field with the length, in bytes, of the device name pointed to by NAML$L_LONG_DEV, including the ":".

RMS fills this field with a pointer into either the expanded string buffer specified by NAML$L_LONG_EXPAND or the resultant string buffer specified by NAML$L_LONG_RESULT. The pointer in NAML$L_LONG_DIR points to the directory specification within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAML$L_LONG_RESULT_SIZE. If NAML$L_LONG_RESULT_SIZE is 0, this field points into the buffer specified by NAML$L_LONG_EXPAND. Otherwise, it points into the buffer specified by NAML$L_LONG_EXPAND.

For NAML$L_LONG_DIR_SIZE, RMS fills this field with the length, in bytes, of the directory pointed to by NAML$L_LONG_DIR, including the delimiter ] or >.

The expanded string area address field contains the symbolic address of a user buffer in the application program to receive the file specification string resulting from the translation of logical names and the application of default file specification information.

You must specify this field for processing wildcard characters.

The NAML$L_LONG_EXPAND field's corresponding short field, NAML$L_ESA, can be specified as well, but a separate buffer must be allocated for it.

The expanded string area allocation size field contains the size of the user-allocated buffer whose address is contained in the NAML$L_LONG_EXPAND field.

This field contains a numeric value representing the size, in bytes, of the user buffer that will receive the file specification string, in the range of 0 through 4095.

The symbolic value NAML$C_MAXRSS defines the maximum possible length of an expanded file specification string.

RMS sets the expanded string size field as part of the Open, Create, and Parse services. This field contains the length, in bytes, of the file specification string returned in the buffer whose address is in the NAML$L_LONG_EXPAND field.

These fields can be used to replace the FAB$L_FNA and FAB$L_FNS fields in the FAB. Using these NAML fields allows you to specify a default name string longer than the 255 bytes allowed by FAB$B_FNS.

RMS uses the NAML$L_LONG_FILENAME and NAML$L_LONG_FILENAME_SIZE fields in place of the FAB$L_FNA and FAB$L_FNS fields if FAB$L_FNA contains -1 and FAB$B_FNS contains 0.

RMS fills this field with a pointer into either the expanded string buffer specified by NAML$L_LONG_EXPAND or the resultant string buffer specified by NAML$L_LONG_RESULT. The pointer in NAML$L_LONG_NAME points to the start of the file name within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAML$L_LONG_RESULT_SIZE. If NAML$L_LONG_RESULT_SIZE is 0, this field points into the buffer specified by NAML$L_LONG_EXPAND. Otherwise, it points into the buffer specified by NAML$L_LONG_RESULT.

For NAML$L_LONG_NAME_SIZE, RMS fills this field with the length, in bytes, of the file name pointed to by NAML$L_LONG_NAME, not including the type field nor the period separating the name from the type.

RMS fills this field with a pointer into either the expanded string buffer specified by NAML$L_LONG_EXPAND or the resultant string buffer specified by NAML$L_LONG_RESULT. The pointer in NAM$L_LONG_NODE points to the start of the node name within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAML$L_LONG_RESULT_SIZE. If NAML$L_LONG_RESULT_SIZE is 0, this field points into the buffer specified by NAML$L_LONG_EXPAND. Otherwise, it points into the buffer specified by NAML$L_LONG_RESULT.

For NAML$L_LONG_NODE_SIZE, RMS fills this field with the length, in bytes, of the node name pointed to by NAML$L_LONG_NODE, including the :: delimiter. Note that if this is not a DECnet file specification, NAML$L_LONG_NODE_SIZE will be 0.

The resultant string area address field contains the symbolic address of a buffer in your program to receive the resultant file specification string. The NAML$L_LONG_RESULT_ALLOC field must also be specified to obtain a resultant file specification string.

This string is the fully specified name of the file that results from the resolution of all system defaults, including version numbers and wildcard character substitution in the expanded file name string. You must specify this field for wildcard processing.

The NAML$L_LONG_RESULT field's corresponding short field, NAML$L_RSA, can be specified as well, but a separate buffer should be allocated for it.

The resultant string area allocation size field defines the size of the user-allocated buffer whose address is contained in the NAML$L_LONG_RESULT field.

This field contains a numeric value representing the size, in bytes, of the user buffer that will receive the resultant file specification string, in the range of 0 through 4095.

The symbolic value NAML$C_MAXRSS defines the maximum possible length of a resultant file specification string.

The resultant string size contains the length, in bytes, of the resultant file specification string returned in the buffer whose address is in the NAML$L_LONG_RESULT field.

RMS fills this field with a pointer into either the expanded string buffer specified by NAML$L_LONG_EXPAND or the resultant string buffer specified by NAML$L_LONG_RESULT. The pointer in NAML$L_LONG_TYPE points to the start of the file type, including the dot separating it from the name, within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAML$L_LONG_RESULT_SIZE. If NAML$L_LONG_RESULT_SIZE is 0, this field points into the buffer specified by NAML$L_LONG_EXPAND. Otherwise, it points into the buffer specified by NAML$L_LONG_RESULT.

For NAML$L_LONG_TYPE_SIZE, RMS fills this field with the length, in bytes, of the file type pointed to by NAML$L_LONG_TYPE.

RMS fills this field with a pointer into either the expanded string buffer specified by NAML$L_LONG_EXPAND or the resultant string buffer specified by NAML$L_LONG_RESULT. The pointer in NAML$L_LONG_VER points to the start of the file version, including the semicolon separating it from the type, within the complete file specification in the buffer. You can tell which buffer this field points into by checking NAML$L_LONG_RESULT_SIZE. If NAML$L_LONG_RESULT_SIZE is 0, this field points into the buffer specified by NAML$L_LONG_EXPAND. Otherwise, it points into the buffer specified by NAML$L_LONG_RESULT.

For NAML$L_LONG_VER_SIZE, RMS fills this field with the length, in bytes, of the file version pointed to by NAML$L_LONG_VER.

The output flags field contains additional status bits returned by RMS.

The user context field contains any user-selected value, up to 8 bytes long. This field is devoted exclusively to your use. RMS makes no use of the contents of this field; therefore, you can set any value you want in this field. For example, you could use this field to communicate with a file I/O completion routine in your program that the file access block (FAB) is passed to, since the FAB$L_NAM provides a link to this name block.

Unless otherwise indicated, each field is supported for DECnet for OpenVMS operations using files at remote OpenVMS systems. For information about the support of RMS options for remote file access to other systems, see the VSI OpenVMS DECnet Networking Manual.

The format and arguments of the $RAB macro and the $RAB_STORE macro are described in Appendix A, RMS Control Block Macros.

The block identifier (BID) field is a static field that identifies the block as a RAB. Once set, this field must not be altered unless the control block is no longer needed. This field must be initialized to the symbolic offset value RAB$C_BID (this is done by the $RAB macro).

The bucket code (BKT) field is used with records in a relative file and when performing block I/O.

This field contains a relative record number or a numeric value representing the virtual block number to be accessed.

For relative files, the relative record number of the record acted upon (or which produced an error) is returned to the RAB$L_BKT field only after the completion of a sequential operation. That is, RMS returns the relative record number when you set the record access mode for sequential access (RAB$B_RAC is RAB$C_SEQ) on the execution of a Get, Put, or Find service.

Before performing block I/O on disk devices, this field must contain the virtual block number (VBN) of the first block you want to read or write. For all other devices, this field is not used. If you specify a VBN of 0, RMS begins the block transfer at the block pointed to by the next block pointer (NBP). (The NBP is an internal pointer maintained by RMS; it is described in Section B.3.12, “Next Block Pointer (NBP)”.)

This field is also input to the Space service to specify the number of blocks to be spaced forward or backward.

This field corresponds to the FDL attribute CONNECT BUCKET_CODE.

The block length (BLN) field is a static field that defines the length of the RAB, in bytes. Once set, this field must not be altered unless the control block is no longer needed. This field must be initialized to the symbolic value RAB$C_BLN (this is done by the $RAB macro).

The user context (CTX) field contains any user-selected value, up to four bytes long. This field is devoted exclusively to your use. RMS makes no use of the contents of this field; therefore, you can set any value you want in this field. For example, you could use this field to communicate with a completion routine in your program.

This field corresponds to the FDL attribute CONNECT CONTEXT.

The file access block address (FAB) field contains the symbolic address of the FAB for the file. Before you invoke the Connect service, you must set this field to indicate the address of the FAB associated with the open file.

The internal stream identifier (ISI) field associates the RAB with a corresponding FAB. RMS sets this field after the execution of a Connect service. A Disconnect service clears this field. This field should not be altered.

The key buffer address (KBF) field contains the symbolic address of the buffer containing the key value for random access. Note that the RAB$B_KBF field has the same offset as the RAB$L_PBF (prompt buffer address) field, but no conflict is presented because the fields are used in mutually exclusive operations.

When the RAB$B_RAC (record access mode) field specifies random access by key value, this field provides the address of a buffer that contains the key of the desired record. The key is the relative record number in files that are organized for relative access or in files organized for sequential access containing fixed-length records. In indexed files, the key value in RAB$L_KBF is used with the index specified in the key of reference field (RAB$B_KRF) to randomly access the desired record. Note that although a collating key affects the stored order for records, the collating value does not govern record lookups. For example, a collating sequence may assign the same ordering for the keys “dog” and “DOG”. However, both keys do not have the same access (lookup) value. Therefore, when doing lookups, a program should specify either the specific key value or a range of values that includes the uppercase and lowercase combinations of the key. See the VSI OpenVMS Guide to OpenVMS File Applications for more information about accessing indexed records.

Before you invoke the Get or Find service for doing random access in an indexed file, you place the address of the location containing the specified key value in the RAB$L_KBF field. The size of this key value must be specified in the RAB$B_KSZ field. During execution of the Get or Find service, RMS uses the specified key value for searching an index (which you specify using the RAB$B_KRF field) to locate the desired record. The type of match, that is, exact, generic, approximate, or approximate generic, is determined by examining the RAB$B_KSZ field in combination with selected search bits in the RAB$L_ROP field.

The key of reference (KRF) field specifies the key or index (primary, first alternate, and so on) to which the operation applies. The RAB$B_KRF field is applicable to indexed files only.

This field contains a numeric value representing the key path to records in a file. The value 0, the default, indicates the primary key. The values 1 through 254 indicate alternate keys.

When your program invokes a Get or Find service in random access mode, the key of reference specifies the index to search for a match on the key value that is described by the RAB$L_KBF and RAB$B_KSZ fields. When your program invokes a Connect or Rewind service, the key of reference identifies the index in the file of the next record in the stream. The next record is important when records are retrieved sequentially.

Note that although a collating key affects the stored order for records, the collating value does not govern record lookups. For example, a collating sequence may assign the same ordering for the keys “dog” and “DOG”. However, both keys do not have the same access (lookup) value. Therefore, when doing lookups, a program should specify either the specific key value or a range of values that includes the uppercase and lowercase combinations of the key. See the VSI OpenVMS Guide to OpenVMS File Applications for more information about accessing indexed records. This field corresponds to the FDL attribute CONNECT KEY_OF_REFERENCE.

The key size (KSZ) field contains a numeric value equal to the size, in bytes, of the record key pointed to by the RAB$L_KBF field.

Note that the RAB$B_KSZ field has the same offset as the RAB$B_PSZ (prompt buffer size) field but no conflict is presented because the fields are used in mutually exclusive operations.

Note that for DECnet for OpenVMS operations, the RAB$B_KSZ field must be explicitly specified as a nonzero value because the key data type information might not be available to RMS at the local node.

The size of the relative record number of a record in a relative file or a sequential file with fixed-length records is a longword, positive, integer value; therefore, the key size is 4. For relative record numbers, the default value of 0 causes a key size of 4 to be used. For DECnet for OpenVMS operations, however, the RAB$B_KSZ field must be explicitly specified as 4 for relative files.

With indexed files, the size of key values in bytes of an indexed file can be from 1 to 255 bytes.