Document revision date: 19 July 1999

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.

On Alpha systems, the long name block (NAML) can optionally take the place of a NAM block (see Chapter 5). The NAML allows OpenVMS Alpha users to locate and use file specifications that are longer than 255 bytes.

6.1 Using the NAM and NAML Block

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.

6.2 Summary of Fields

The additional fields in the NAML data structure are summarized at the beginning of Table 6-1 and are described in Chapter 5. All the other NAML fields are exactly like their NAM counterparts described in Table 5-1, unless noted otherwise in this chapter.

Table 6-1 NAML Fields

Field Offset	Size (Bytes)	Corresponding NAM or FAB Field	Description
Alpha-Only NAML Fields Described in this Chapter:
NAML$B_BID	1	None	Block identifier
NAML$B_BLN	1	None	Block length
NAML$L_FILESYS_NAME	4	None	File system name buffer address.
NAML$L_FILESYS_NAME_ALLOC	4	None	File system name buffer allocated size
NAML$L_FILESYS_NAME_SIZE	4	None	File system name length
NAML$L_INPUT_FLAGS	4	None	Additional flags specified as input
NAML$L_LONG_DEFNAME	4	FAB$L_DNA	Long default file specification string address specified as input (used if FAB$L_DNA contains -1)
NAML$L_LONG_DEFNAME_SIZE	4	FAB$B_DNS	Long default file specification string size specified as input
NAML$L_LONG_DEV	4	NAM$L_DEV	Long device string address
NAML$L_LONG_DEV_SIZE	4	NAM$B_DEV	Long device string length
NAML$L_LONG_DIR	4	NAM$L_DIR	Long directory string address
NAML$L_LONG_DIR_SIZE	4	NAM$B_DIR	Long directory string length
NAML$L_LONG_EXPAND	4	NAM$L_ESA	Long expanded string area address
NAML$L_LONG_EXPAND_ALLOC	4	NAM$B_ESS	Long expanded string area size
NAML$L_LONG_EXPAND_SIZE	4	NAM$B_ESL	Long expanded string length
NAML$L_LONG_FILENAME	4	FAB$L_FNA	Long file specification string address
NAML$L_LONG_FILENAME_SIZE	4	FAB$B_FNS	Long file specification string size
NAML$L_LONG_NAME	4	NAM$L_NAME	Long file name string address
NAML$L_LONG_NAME_SIZE	4	NAM$B_NAME	Long file name string length
NAML$L_LONG_NODE	4	NAM$L_NODE	Long node name string address
NAML$L_LONG_NODE_SIZE	4	NAM$B_NODE	Long node name string length
NAML$L_LONG_RESULT	4	NAM$L_RSA	Long resultant string area address
NAML$L_LONG_RESULT_ALLOC	4	NAM$B_RSS	Long resultant string area size
NAML$L_LONG_RESULT_SIZE	4	NAM$B_RSL	Long resultant string length
NAML$L_LONG_TYPE	4	NAM$L_TYPE	Long file type string length
NAML$L_LONG_TYPE_SIZE	4	NAM$B_TYPE	Long file type string address
NAML$L_LONG_VER	4	NAM$L_VER	Long file version string address
NAML$L_LONG_VER_SIZE	4	NAM$B_VER	Long file version string length
NAML$L_OUTPUT_FLAGS	4	None	Additional status bits passed as output
NAML$L_USER_CONTEXT	8	None	User context
NAML Fields Equivalent to NAM Fields (Described in Chapter 5:)
NAML$B_DEV	1	NAM$B_DEV	Device string length
NAML$L_DEV	4	NAM$L_DEV	Device string address
NAML$W_DID	6	NAM$W_DID	Directory identification
NAML$B_DIR	1	NAM$B_DIR	Directory string length
NAML$L_DIR	4	NAM$L_DIR	Directory string address
NAML$T_DVI	16	NAM$T_DVI	Device identification
NAML$L_ESA	4	NAM$L_ESA	Expanded string area address
NAML$B_ESL	1	NAM$B_ESL	Expanded string length
NAML$B_ESS	1	NAM$B_ESS	Expanded string area size
NAML$W_FID	6	NAM$W_FID	File identification
NAML$W_FIRST_WILD_DIR	2	NAM$W_FIRST_WILD_DIR	The topmost directory level to contain a wildcard.
NAML$L_FNB	4	NAM$L_FNB	File name status bits
NAML$W_LONG_DIR_LEVELS	2	NAM$W_LONG_DIR_LEVELS	Total number directories
NAML$B_NAME	1	NAM$B_NAME	File name string length
NAML$L_NAME	4	NAM$L_NAME	File name string address
NAML$B_NMC	1	NAM$B_NMC	Name characteristics
NAML$B_NODE	1	NAM$B_NODE	Node name string length
NAML$L_NODE	4	NAM$L_NODE	Node name string address
NAML$B_NOP	1	NAM$B_NOP	Name block options
NAML$L_RLF 1	4	NAM$L_RLF	Related file NAM or NAML block address
NAML$L_RSA	4	NAM$L_RSA	Resultant string area address
NAML$B_RSL	1	NAM$B_RSL	Resultant string length
NAML$B_RSS	1	NAM$B_RSS	Resultant string area size
NAML$B_TYPE	1	NAM$L_TYPE	File type string length
NAML$L_TYPE	4	NAM$B_TYPE	File type string address
NAML$B_VER	1	NAM$B_VER	File version string length
NAML$L_VER	4	NAM$L_VER	File version string address
NAML$L_WCC	4	NAM$L_WCC	Wildcard context

	privacy and legal statement
4523PRO_008.HTML