Updated: 11 December 1998

OpenVMS Record Management Services Reference Manual

If the name block passed to RMS (see FAB$L_NAM) contains a block identifier (see NAML$B_BID) equal to NAML$C_BID, RMS performs the following validation checks:

1. NAML$B_BLN field is exactly equal to NAML$C_BLN.
2. NAML$L_LONG_RESULT_ALLOC and NAML$L_LONG_EXPAND_ALLOC are less than or equal to NAML$C_MAXRSS.
3. All unused fields (which have a symbolic name containing MBZ) contain zero. You can clear the entire structure before initializing any fields to meet this requirement.

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

6.4 NAML$B_BID Field

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

6.5 NAML$B_BLN Field

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

6.6 NAML$L_FILESYS_NAME Field

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.

6.7 NAML$L_FILESYS_NAME_ALLOC Field

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

6.8 NAML$L_FILESYS_NAME_SIZE Field

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

6.9 NAML$L_INPUT_FLAGS Field

The input flags field contains additional flags specified as input to RMS, including NAML$V_NO_SHORT_OUTPUT.

The NAML$L_INPUT_FLAGS field contains the following flag:

Flag	Meaning
NAML$V_NO_SHORT_OUTPUT	Set by the user to tell RMS not to fill in the NAM$L_ESA or NAM$L_RSA buffer.

6.10 NAML$L_LONG_DEFNAME and NAML$L_LONG_DEFNAME_SIZE Fields

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.

The following table illustrates this procedure.

To use this field:	Put a -1 in this field:	Use this size field:	Put a 0 in this field:
NAML$L_LONG_DEFNAME	FAB$L_DNA	NAML$L_LONG_DEFNAME_SIZE	FAB$B_DNS

6.11 NAML$L_LONG_DEV and NAML$L_LONG_DEV_SIZE Fields

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

6.12 NAML$L_LONG_DIR and NAML$L_LONG_DIR_SIZE Fields

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

6.13 NAML$L_LONG_EXPAND Field

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.

6.14 NAML$L_LONG_EXPAND_ALLOC Field

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.

6.15 NAML$L_LONG_EXPAND_SIZE Field

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.

6.16 NAML$L_LONG_FILENAME and NAML$L_LONG_FILENAME_SIZE Fields

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.

The following illustrates this procedure.

To use this field:	Put a -1 in this field:	Use this size field:	Put a 0 in this field:
NAML$L_LONG_FILENAME	FAB$L_FNA	NAML$L_LONG_FILENAME_SIZE	FAB$B_FNS

6.17 NAML$L_LONG_NAME and NAML$L_LONG_NAME_SIZE Fields

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.

6.18 NAML$L_LONG_NODE and NAML$L_LONG_NODE_SIZE Fields

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.

6.19 NAML$L_LONG_RESULT Field

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.

6.20 NAML$L_LONG_RESULT_ALLOC Field

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.

6.21 NAML$L_LONG_RESULT_SIZE Field

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.

6.22 NAML$L_LONG_TYPE and NAML$L_LONG_TYPE_SIZE Fields

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.

6.23 NAML$L_LONG_VER and NAML$L_LONG_VER_SIZE Fields

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.

6.24 NAML$L_OUTPUT_FLAGS Field

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

The NAML$L_OUTPUT_FLAGS field contains the following flags.

Flag	Meaning
NAML$V_FILESYS_NAME_UCS2	Set by RMS if name pointed to by NAML$L_FILESYS_NAME consists of a 2-byte Unicode character.
NAML$V_LONG_RESULT_DID	Set by RMS if there is a DID-compressed directory in the long resultant or expanded buffer.
NAML$V_LONG_RESULT_ESCAPE	Set by RMS if there are any escape characters (^) in the long resultant or expanded buffer.
NAML$V_LONG_RESULT_FID	Set by RMS if there is a FID-compressed name in the long resultant or expanded buffer.
NAML$V_LONG_RESULT_UNICODE	Set by RMS if there is one or more ^U sequences in the long resultant or expanded buffer.

6.25 NAML$Q_USER_CONTEXT Field

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.

The record access block (RAB) defines run-time options for a record stream and for individual operations within a predefined record stream context. After you connect the file to a record stream and associate the record stream with a FAB, you use the RAB fields to specify the next record you want to access and to identify appropriate record characteristics.

Table 7-1 gives the symbolic offset, the size, the FDL equivalent, and a brief description of each RAB field.

Table 7-1 RAB Fields

Field Offset	Size (Bytes)	FDL Equivalent	Description
RAB$B_BID 1	1	None	Block identifier
RAB$L_BKT	4	CONNECT BUCKET_CODE	Bucket code
RAB$B_BLN 1	1	None	Block length
RAB$L_CTX	4	CONNECT CONTEXT	User context
RAB$L_FAB	4	None	File access block address
RAB$W_ISI 2	2	None	Internal stream identifier
RAB$L_KBF	4	None	Key buffer address
RAB$B_KRF	1	CONNECT KEY_OF_REFERENCE	Key of reference
RAB$B_KSZ	1	None	Key size
RAB$B_MBC	1	CONNECT MULTIBLOCK_COUNT	Multiblock count
RAB$B_MBF	1	CONNECT MULTIBUFFER_COUNT	Multibuffer count
RAB$L_PBF	4	None	Prompt buffer address
RAB$B_PSZ	1	None	Prompt buffer size
RAB$B_RAC	1	CONNECT 3	Record access mode
RAB$L_RBF	4	None	Record buffer address
RAB$W_RFA	6	None	Record file address
RAB$L_RHB	4	None	Record header buffer address
RAB$L_ROP	4	CONNECT 3	Record-processing options
RAB$W_RSZ	2	None	Record size
RAB$L_STS 2	4	None	Completion status code
RAB$L_STV 2	4	None	Status value
RAB$W_STV0 4	2	None	Low-order word status value
RAB$W_STV2 4	2	None	High-order word status value
RAB$B_TMO	1	CONNECT TIMEOUT_PERIOD	Timeout period
RAB$L_UBF	4	None	User record buffer address
RAB$W_USZ	2	None	User record buffer size
RAB$L_XAB	4	None	Next XAB address

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 DECnet for OpenVMS Networking Manual.

The format and arguments of the $RAB macro and the $RAB_STORE macro are described in Appendix A.

7.2 RAB$B_BID Field

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

7.3 RAB$L_BKT Field

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

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.

7.4 RAB$B_BLN Field

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

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

4523PRO_009.HTML