Document revision date: 15 July 2002

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.

5.14 NAM$L_FNB Field

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.

Each status bit has its own offset and mask value. For instance, the number of directory levels (DIR_LVLS) field has a symbolic bit offset of NAM$V_DIR_LVLS and a mask value of NAM$M_DIR_LVLS. The bits and the conditions they express for the NAM$L_FNB field are described in Table 5-2.

Table 5-2 NAM$L_FNB Status Bits

Field Offset	Description
NAM$V_CNCL_DEV	Device name is a concealed device.
NAM$V_DIR_LVLS	Indicates the number of subdirectory levels (value is 0 if there is a user file directory only); a 3-bit field (maximum 7).
NAM$V_DIR_LVLS_G7	Indicates that the number of directory levels are greater than 7. If this is set, NAM$V_DIR_LVLS is set to 7.
NAM$V_EXP_DEV	Device name is explicit in primary filespec.
NAM$V_EXP_DIR	Directory specification is explicit in primary filespec.
NAM$V_EXP_NAME	File name is explicit in primary filespec.
NAM$V_EXP_TYPE	File type is explicit in primary filespec.
NAM$V_EXP_VER	Version number is explicit in primary filespec.
NAM$V_GRP_MBR	Directory specification is in the group/member number format.
NAM$V_HIGHVER	A higher-numbered version of the file exists (output from Create and Enter services). For DECnet for OpenVMS operations, this bit is returned as a binary zero.
NAM$V_LOWVER	A lower-numbered version of the file exists (output from Create and Enter services). For DECnet for OpenVMS operations, this bit is returned as a binary zero.
NAM$V_NODE	File specification includes a node name.
NAM$V_PPF	File is indirectly accessed process-permanent file.
NAM$V_QUOTED	File specification includes a quoted string; indicates that the file name length and address field contains a quoted string file specification. Applies to network operations or magnetic tape devices only. 1
NAM$V_ROOT_DIR	Device name incorporates a root directory.
NAM$V_SEARCH_LIST	A search list logical name is present in the file specification.
NAM$V_WILDCARD	File specification string includes a wildcard; returned whenever any of the other wildcard bits is set.
NAM$V_WILD_DIR	Directory specification includes a wildcard character.
NAM$V_WILD_GRP	Group number contains a wildcard character.
NAM$V_WILD_MBR	Member number contains a wildcard character.
NAM$V_WILD_NAME	File name contains a wildcard character.
NAM$V_WILD_SFD1-- NAM$V_WILD_SFD7	Subdirectory 1 through 7 specification includes a wildcard character.
NAM$V_WILD_SFDG7	Indicates that a subdirectory greater than 7 contains a wildcard character.
NAM$V_WILD_TYPE	File type contains a wildcard character.
NAM$V_WILD_UFD	User file directory specification includes a wildcard character.
NAM$V_WILD_VER	Version number contains a wildcard character.

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.

5.16 NAM$B_NAME and NAM$L_NAME 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_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.

5.17 NAM$B_NMC

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.

The bits and the characteristics they describe are shown in the following table:

Field Offset	Meaning
NAM$V_DID	Set by RMS if it found a DID-compressed directory in the root or directory name component of an input directory.
NAM$V_FID	Set by RMS if it found a FID-compressed file name in an input file specification.
NAM$V_RES_DID	Set by RMS if there is a DID-compressed directory in the short resultant or expanded buffer.
NAM$V_RES_FID	Set by RMS if there is a FID-compressed name in the short resultant or expanded buffer.
NAM$V_RES_ESCAPE	Set by RMS if there are any escape characters (^) in the short resultant or expanded buffer.
NAM$V_RES_UNICODE	Set by RMS if there are one or more ^U sequences in the short resultant or expanded buffer.

5.18 NAM$B_NODE and NAM$L_NODE Fields

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.

5.19 NAM$B_NOP Field

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 Guide to OpenVMS File Applications for additional details on file specification parsing concepts.

5.21 NAM$L_RSA Field

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.

5.22 NAM$B_RSL Field

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.

5.23 NAM$B_RSS 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.

5.24 NAM$B_TYPE and NAM$L_TYPE 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_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.

5.25 NAM$B_VER and NAM$L_VER 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_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.

5.26 NAM$L_WCC Field

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.

	privacy and legal statement
4523PRO_008.HTML