Document revision date: 15 July 2002

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

4.29 FAB$B_RTV Field

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.

4.30 FAB$L_SDC Field

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

4.31 FAB$B_SHR Field

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.

Note that if you do not specify a value in the FAB$B_SHR field, the following defaults apply:

• If the FAB$B_FAC field is set or defaulted to FAB$V_GET, the FAB$B_SHR field defaults to FAB$V_SHRGET.
• If the FAB$B_FAC field is set or defaulted to either FAB$V_PUT, FAB$V_DEL, FAB$V_UPD, or FAB$V_TRN, the FAB$B_SHR field defaults to FAB$V_NIL. Thus, write sharing must be explicitly requested using the FAB$B_SHR field (because it is not the default).

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 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). Register 0 contains the same status as the STS field. Potential error codes for specific services are listed under their descriptions.

4.33 FAB$L_STV Field

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.

4.34 FAB$L_XAB Field

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

RMS uses XAB values as follows:

• If you specify a XAB for either an Open or Display service, RMS returns the file attributes to the XAB.
• If you specify a XAB for a Create, Close, or Extend service, RMS uses the XAB as input to those functions.

The name (NAM) block provides additional fields for extended file specification use, including parsing and obtaining the actual file specification used for a file operation. On Alpha systems, the long name block (NAML) can optionally take the place of a NAM block (see Chapter 6).

5.1 Summary of Fields

The symbolic offset, the size, and a brief description of each NAM block field are presented in Table 5-1. Additional details are given in the remaining sections of this chapter.

Table 5-1 NAM Block Fields

Field Offset	Size (Bytes)	Description
NAM$B_BID 1	1	Block identifier
NAM$B_BLN 1	1	Block length
NAM$B_DEV 2	1	Device string length
NAM$L_DEV 2	4	Device string address
NAM$W_DID 2	6	Directory identification
NAM$B_DIR 2	1	Directory string length
NAM$L_DIR 2	4	Directory string address
NAM$T_DVI 2	16	Device identification
NAM$L_ESA	4	Expanded string area address
NAM$B_ESL 2	1	Expanded string length
NAM$B_ESS	1	Expanded string area size
NAM$W_FID 2	6	File identification
NAM$W_FIRST_WILD_DIR	2	The topmost directory level to contain a wildcard.
NAM$L_FNB 2	4	File name status bits
NAM$W_LONG_DIR_LEVELS	2	Total number directories
NAM$B_NAME 2	1	File name string length
NAM$L_NAME 2	4	File name string address
NAM$B_NMC	1	Name characteristics
NAM$B_NODE 2	1	Node name string length
NAM$L_NODE 2	4	Node name string address
NAM$B_NOP	1	Name block options
NAM$L_RLF 3	4	Related file NAM or NAML block address
NAM$L_RSA	4	Resultant string area address
NAM$B_RSL 2	1	Resultant string length
NAM$B_RSS	1	Resultant string area size
NAM$B_TYPE 2	1	File type string length
NAM$L_TYPE 2	4	File type string address
NAM$B_VER 2	1	File version string length
NAM$L_VER 2	4	File version string address
NAM$L_WCC 2	4	Wildcard context

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

5.2 File Specification Component Descriptors

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.

This is an example of a resultant file specification and its file specification component descriptors:

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.

5.3 NAM$B_BID Field

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

5.4 NAM$B_BLN Field

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

	privacy and legal statement
4523PRO_007.HTML