Document revision date: 15 July 2002

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 starting with Section 6.4. 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

If the name block passed to RMS (see FAB$L_NAM) contains a block identifier (see NAML$B_BID) equal to NAML$C_BID, RMS performs the following validation checks:

1. NAML$B_BLN field is exactly equal to NAML$C_BLN.
2. NAML$L_LONG_RESULT_ALLOC and NAML$L_LONG_EXPAND_ALLOC are less than or equal to NAML$C_MAXRSS.
3. All unused fields (which have a symbolic name containing MBZ) contain zero. You can clear the entire structure before initializing any fields to meet this requirement.

If any of these validation checks fail, a RMS$_NAML error status is returned.

6.4 NAML$B_BID Field

The block identifier (BID) field is a static field that identifies this control block as a NAML 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 NAML$C_BID (this is done by the $NAML macro).

6.5 NAML$B_BLN Field

The block length (BLN) field is a static field that defines the length of the NAML 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 NAML$C_BLN (this is done by the $NAML macro).

6.6 NAML$L_FILESYS_NAME Field

This field contains the address of a user buffer that receives the file name, type, and version in a form appropriate for specifying directly to the file system by the SYS$QIO system service.

6.7 NAML$L_FILESYS_NAME_ALLOC Field

This field contains the size of the user-allocated buffer whose address is contained in the NAML$L_FILESYS_NAME field.

6.8 NAML$L_FILESYS_NAME_SIZE Field

RMS sets this field to indicate the length, in bytes, of the name string returned in NAML$L_FILESYS_NAME.

6.9 NAML$L_INPUT_FLAGS Field

The NAML$L_INPUT_FLAGS field contains the following flags:

Flag	Meaning
NAML$V_NO_SHORT_OUTPUT	Set by the user to tell RMS not to fill in the NAM$L_ESA or NAM$L_RSA buffer.
NAML$V_CASE_LOOKUP	Value may be specified in this 2-bit field by user to indicate case sensitivity preference for a file on an ODS--5 disk on Alpha systems. Table 6-2 contains the alternative values that may be specified for this option. If NAML$V_CASE_LOOKUP is zero, the current process case sensitivity setting is used (see DCL SET PROCESS/CASE_LOOKUP command or SYS$SET_PROCESS_PROPERTIESW system service). This option is restricted to files on an ODS--5 disk on Alpha systems and is ignored on non-ODS--5 disks.

Table 6-2 shows the values and their meanings for this option.

Table 6-2 NAML$V_CASE_LOOKUP Values

Values	Meaning
NAML$C_CASE_LOOKUP_BLIND	Set by the user to tell RMS to ignore case when creating, deleting, and searching for files on an ODS--5 disk on Alpha systems.
NAML$C_CASE_LOOKUP_SENSITIVE	Set by the user to tell RMS to include case as a criteria when creating, deleting, and searching for files on an ODS--5 disk on Alpha systems.

6.10 NAML$L_LONG_DEFNAME and NAML$L_LONG_DEFNAME_SIZE Fields

These fields can be used to replace the FAB$L_DNA and FAB$B_DNS fields in the FAB. Using these NAML fields allows you to specify a default name string longer than the 255 bytes allowed by FAB$B_DNS.

RMS uses the NAML$L_LONG_DEFNAME and NAML$L_LONG_DEFNAME_SIZE fields in place of the FAB$L_DNA and FAB$L_DNS fields if FAB$L_DNA contains a -1 and FAB$B_DNS contains 0.

The following table illustrates this procedure:

To use this field:	Put a -1 in this field:	Use this size field:	Put a 0 in this field:
NAML$L_LONG_DEFNAME	FAB$L_DNA	NAML$L_LONG_DEFNAME_SIZE	FAB$B_DNS

6.11 NAML$L_LONG_DEV and NAML$L_LONG_DEV_SIZE Fields

RMS fills this field with a pointer into either the expanded string buffer specified by NAML$L_LONG_EXPAND or the resultant string buffer specified by NAML$L_LONG_RESULT. The pointer in NAML$L_LONG_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 NAML$L_LONG_RESULT_SIZE. If NAML$L_LONG_RESULT_SIZE is 0, this field points into the buffer specified by NAML$L_LONG_EXPAND. Otherwise, it points into the buffer specified by NAML$L_LONG_RESULT. The device name is always returned with uppercase letters.

For NAML$L_LONG_DEV_SIZE, RMS fills this field with the length, in bytes, of the device name pointed to by NAML$L_LONG_DEV, including the ":".

6.12 NAML$L_LONG_DIR and NAML$L_LONG_DIR_SIZE Fields

RMS fills this field with a pointer into either the expanded string buffer specified by NAML$L_LONG_EXPAND or the resultant string buffer specified by NAML$L_LONG_RESULT. The pointer in NAML$L_LONG_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 NAML$L_LONG_RESULT_SIZE. If NAML$L_LONG_RESULT_SIZE is 0, this field points into the buffer specified by NAML$L_LONG_EXPAND. Otherwise, it points into the buffer specified by NAML$L_LONG_EXPAND.

For NAML$L_LONG_DIR_SIZE, RMS fills this field with the length, in bytes, of the directory pointed to by NAML$L_LONG_DIR, including the delimiter ] or >.

6.13 NAML$L_LONG_EXPAND Field

The expanded string area address 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.

The NAML$L_LONG_EXPAND field's corresponding short field, NAML$L_ESA, can be specified as well, but a separate buffer must be allocated for it.

6.14 NAML$L_LONG_EXPAND_ALLOC Field

The expanded string area allocation size field contains the size of the user-allocated buffer whose address is contained in the NAML$L_LONG_EXPAND 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 4095.

The symbolic value NAML$C_MAXRSS defines the maximum possible length of an expanded file specification string.

6.15 NAML$L_LONG_EXPAND_SIZE Field

RMS sets the expanded string size 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 NAML$L_LONG_EXPAND field.

	privacy and legal statement
4523PRO_009.HTML