Updated: 11 December 1998 |
OpenVMS Record Management Services Reference
Manual
Previous | Contents | Index |
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.
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. |
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.
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.
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 |
Previous | Next | Contents | Index |
Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal |
4523PRO_008.HTML
|