HP OpenVMS Systems Documentation

OpenVMS Record Management Services Reference Manual

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.

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:

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

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:

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.