Document revision date: 19 July 1999

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. If FAB$V_NIL is specified with other options, it takes precedence.

This option corresponds to the FDL attribute SHARING PROHIBIT.

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

5.5 NAM$B_DEV and NAM$L_DEV Fields

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

5.6 NAM$W_DID Field

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.

5.7 NAM$B_DIR and NAM$L_DIR Fields

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

5.8 NAM$T_DVI Field

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.

5.9 NAM$L_ESA Field

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.

5.10 NAM$B_ESL Field

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.

5.11 NAM$B_ESS 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.

5.12 NAM$W_FID Field

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.

5.13 NAM$W_FIRST_WILD_DIR Field

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.

	privacy and legal statement
4523PRO_007.HTML