HP OpenVMS Systems Documentation
OpenVMS Guide to Extended File Specifications
B.22.214.171.124 Validating the NAML Block
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:
If any of these validation checks fail, a RMS$_NAML error status is
The NAML has fields that are equivalent to all the NAM fields, plus 28 additional fields to accommodate longer file specifications. There are no FDL attributes for the NAML 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 this way, 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 first attempts to abbreviate specifications to allow them to fit in the short fields. You can prevent the error on the short fields by setting the flag NAML$V_NO_SHORT_OUTPUT, which instructs RMS not to write into the short fields. 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. To cause RMS to read from the short fields, 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, because NAM$B_BLN contains the actual length of the
structure. If you use the symbol NAM$C_BLN, which is the length of a
NAM, it would be too short for a NAML.
Table B-7 shows the additional condition values returned for various RMS services when using the NAML block.
B.3 Files-11 XQP Changes
Files-11 Extended QIO Processor (XQP) file system has been enhanced to support extended file names through the $QIO interface. Note that in some cases, XQP file format rules differ from those that apply to other system services that accept file names, such as those provided by RMS. For a description of the new syntax and semantics used by RMS, see Section B.2.2.
The XQP enhancements support the following features of Extended File Specifications:
Prior to OpenVMS Version 7.2, valid file names supported by the Files-11 XQP were limited to 85 ASCII characters3 with both the file name and file type limited to 39 characters. In support of extended file names, these restrictions have been relaxed to allow the following:
These changes apply only to those volumes that have been initialized or
converted to the Files-11 ODS-5 format. Applications that rely on the
semantics and behavior currently exhibited by ODS-2 volumes should
continue to function as expected.
File specifications are passed to the file system by descriptor by using the QIO P2 parameter. The descriptor contains a pointer to the text of the specification and a length field, which is the total length in bytes of the file specification.
The format of the specification can be identified in the new FIB$B_NAME_FORMAT_IN field, which can take one of the values listed in Table B-8.
If the format specified is not one of those recognized by the file system, an SS$_BADPARAM error is returned. Otherwise, the file system attempts to parse the file specification according to the rules defined for the specified format. If the attempt to parse the name fails, an SS$_BADFILENAME or SS$_BADFILEVER error is returned.
If the FIB passed to the file system does not include the FIB$B_NAME_FORMAT_IN field, the file system assumes that the file specification supplied is in ODS-2 format. This is done to ensure compatibility with unchanged programs.
Before storing file specifications on the volume, the file system
converts them to the simplest compatible format. For example,
specifications supplied in
Unicode (UCS-2) format that do not contain character values greater
than 0x00FF are converted to ISO Latin-1 format before being stored on
When returning a file specification, the file system writes the file format into the new FIB$B_NAME_FORMAT_OUT field. The value used will be one of those listed in Table B-8.
However, not all programs may be able to handle all available naming formats. Callers of the QIO system service can select which formats are returned to them using the new FIB$W_NMCTL flags described in Table B-9.
These new flags control the format of returned file specifications as follows:
B.3.1.3 Wildcard Searches and Pseudonames
The file specification returned by a file system operation is normally in a format that the calling program understands. This is not necessarily the case for operations where the input specification contains wildcard characters. For example, the wildcard in the following ODS-2 compliant file specification:
could now correspond to the following ISO Latin-1 file specification:
Applications that assume that returned file specifications contain only one delimiting period could fail to perform correctly. Rather than return a file specification that would cause the calling program to fail, the file system returns a pseudoname in its place. The actual pseudoname returned depends on the type of name it represents, as shown in the following table.
The file system determines which formats the calling program can understand from the settings of the FIB$V_NAMES_8BIT and FIB$V_NAMES_16BIT flags. These flags control the format of the returned name as shown in Table B-10.
When returning a pseudoname, the file system notifies the user or calling application of the file without allowing direct file access. For this reason, pseudonames include characters that are not legal for input file specifications. Any attempt to use a pseudoname to manipulate a file will return a SYSTEM-F-BADFILENAME error.
Table B-11 shows the minimum size that each buffer must be to contain all possible returned file specifications.
The limit for a particular application depends on which formats it supports. Note that the minimum for the XQP is lower than the general limit for other file systems that use the QIO interface. This is because of the 236-byte size restriction for file specifications imposed by XQP.
If a file specification is longer than the supplied buffer, the file
system truncates the returned specification without generating an
error. If the file specification is shorter than the supplied buffer,
the additional space from the end of the specification to the end of
the buffer is filled with zeros.
Any application that is not modified to take advantage of the new features of the QIO interface will, by default, receive only ODS-2 compatible file specifications or pseudonames provided they:
File specifications that contain lowercase characters, which would otherwise be ODS-2 legal, are converted to uppercase before being returned.
File specifications supplied as input parameters by unchanged
applications are interpreted as 8-bit ODS-2 names. The name is
validated using the existing ODS-2 parsing rules. On an ODS-5 volume,
the file specification is not converted to uppercase before it is
stored on the disk. Unchanged applications will see the file
specification in uppercase because of the conversion described above.
Applications that set one of the new FIB flags will, however, see the
specification in mixed case.
The following sections describe the new file attributes introduced with
ODS-5 and any changes to the semantics of existing attributes.
Table B-12 shows the attributes that are modified or restricted for files on ODS-5 volumes.
The ATR$C_ASCNAME attribute allows the file specification stored in a file's primary file header to be read and written.
For ODS-2 volumes, the ASCNAME attribute is returned as before. For ODS-5 volumes, the file specification is returned in the supplied buffer, and the name format is returned in the new FIB$B_ASCNAME_FORMAT cell.
The format in which the name is returned is controlled by the settings of the FIB$V_NAMES_8BIT and FIB$V_NAMES_16BIT flags in the same way as the output file specification parameter. A pseudoname can be returned in place of the actual file specification if the format is not one of those the calling program can accept.
Unlike the output file specification parameter, the length of a file specification contained in the ASCNAME attribute is not passed back explicitly. To determine the length of the file specification, the calling program must search the attribute buffer for the first occurrence of the padding character. If neither the FIB$V_NAMES_8BIT nor the FIB$V_NAMES_16BIT flag is set, the buffer is padded with space (note that only ODS-2 format names are returned in this case). If one or more of the flags are set, the attribute buffer is padded with zeros.
The ASCNAME attribute can only be written for files on ODS-2 or ODS-5 volumes provided that the FIB$V_NAMES_8BIT and FIB$V_NAMES_16BIT flags are clear.
The ability to write this attribute is only intended to provide compatibility with existing applications that do so. New and modified programs should not write this attribute. Changing its value can prevent a file from being permanently deleted.
In those cases where it is legal to write the attribute, the contents of the attribute buffer (up to 252 bytes) are copied to the file name field in the file header. For ODS-5 headers, the format is set to ODS-2, and the file name length is set to the offset of the first space character. This can be 252 bytes or the length of the supplied buffer, whichever is the least.
The FILE_SPEC attribute is a read-only attribute that returns the physical file specification in the form:
The file name returned is that from the file header, which may be different from that in the directory. The specification may be incomplete if any errors are encountered while reading the file headers of any of the directories in the path.
For files on ODS-5 volumes, the path may contain file names that are in any of the three name formats. This creates a number of problems; for instance, the presence of periods in a directory name could return an ambiguous path specification. To avoid this and other problems, the file system makes use of services provided by RMS to translate the file specification and the components of the path to their escaped form. 6
If the escaped form of the path is longer than can be accommodated by the buffer for the attribute, one or more directories in the path may be replaced by the DID of the rightmost of those replaced. This process is identical to that performed by RMS and is described in more detail in Section B.2. However, if the file specification, even after DID abbreviation, is longer than can be accommodated by the buffer, the file name is truncated. The file specification string returned to the user buffer has a 2-byte count prefix. The count contains the number of bytes for the untruncated file specification. If the count is greater than the size of the user buffer (minus the two bytes that contain the count), the user can conclude that the returned file specification has been truncated.
The first two of these attributes allow the file name and file type to be read and written using Radix-50 encoding. This encoding scheme enables 3 characters to be packed into a 16-bit word. Only 38 characters in the ODS-2 format set are valid for Radix-50 names, with the exceptions being dash (-) and underscore (_).
The maximum component lengths of a Radix-50 encoded file specification are:
The file system only attempts to read or write the three attributes if the format of the existing file name in the file header is ODS-2. If this is not the case, a NORAD50 error will be returned. If the existing file name is in ODS-2 format, but is incompatible with the Radix-50 encoding or the length limits on Radix-50 file names, a BADFILENAME error will be returned.
The ATR$C_FILVER attribute allows the file version number in the file header to be read or written as a 2-byte integer. As the process requires the existing file name to be converted into a Radix-50 file name, the above restriction also applies to this attribute.