HP OpenVMS Systems Documentation

OpenVMS Record Management Services Reference Manual

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.

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:

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.