Document revision date: 30 March 2001

## OpenVMS Guide to Extended File Specifications

Previous | Contents | Index

##### B.2.3.2.1 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:

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.

##### B.2.3.2.2 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. 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.

##### B.2.3.2.3 Condition Values Returned

Table B-7 shows the additional condition values returned for various RMS services when using the NAML block.

Table B-7 RMS Condition Values Returned When Using NAML Block
RMS Service | Condition Value Returned
--- | ---
$CREATE | RMS$_NAML RMS$_NAMLESS RMS$_NAMLFSINV RMS$_NAMLFSSIZ RMS$_NAMLRSS
$DISPLAY | RMS$_NAMLESS RMS$_NAMLFSINV RMS$_NAMLFSSIZ
$ENTER | RMS$_NAML RMS$_NAMLFSINV RMS$_NAMLFSSIZ RMS$_NAMLRSS
$ERASE | RMS$_NAML RMS$_NAMLESS RMS$_NAMLFSINV RMS$_NAMLFSSIZ RMS$_NAMLRSS
$OPEN | RMS$_NAML RMS$_NAMLESS RMS$_NAMLFSINV RMS$_NAMLFSSIZ RMS$_NAMLRSS
$PARSE | RMS$_NAML RMS$_NAMLESS RMS$_NAMLFSINV RMS$_NAMLFSSIZ
$REMOVE | RMS$_NAML RMS$_NALFSINV RMS$_NAMLFSSIZ RMS$_NAMLRSS
$RENAME | RMS$_NAML RMS$_NAMLESS RMS$_NAMLFSINV RMS$_NAMLFSSIZ RMS$_NAMLRSS
$SEARCH | RMS$_NAML RMS$_NAMLFSINV RMS$_NAMLFSSIZ RMS$_NAMLRSS

## B.3 Files-11 XQP Changes

Note The information about the file system contained in this section currently appears only in this document.

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:

- Use of more characters, including those from the 8-bit ISO Latin-1 character set, and the 16-bit Unicode (UCS-2) character set
- Longer file names
- Preservation of case (as first created) within file names

The rest of Section B.3 describes the changes made to the Files-11 XQP file system and $QIO interface in more detail.

### B.3.1 File Naming and Format Changes

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:

- Use of most characters in the 8-bit ISO Latin-1 multinational character set (of which ASCII is a subset) in file names with the following exceptions:

  > The C0 control set (hexadecimal 00 through 1F)
  > Left angle bracket (<)
  > Right angle bracket (>)
  > Colon (:)
  > Slash (/)
  > Backslash (\)
  > Vertical bar (|)
  > Question mark (?)
  > Asterisk (*)

  Note that this explicitly includes both the C1 character set (hex 80-9F) as well as graphical and other characters between 9F and FF.
- Periods (.) within file names
- File and directory specifications encoded using 16-bit Unicode characters (UCS-2)
- Longer lengths for file names and file types, with the restriction that the file name and file type can total 236 8-bit or 118 16-bit characters, including a 1-character delimiter (.)
- File specifications up to 242 8-bit characters4 or 124 16-bit characters5
- Mixed or lowercase input file specifications stored on disk without conversion to uppercase (also known as case preservation)

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.

#### B.3.1.1 Specifying the Format of the Input File Name

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.

Table B-8 FIB Constants for File Formats
Format Value | Format Type
--- | ---
FIB$C_ODS2 | ODS-2 Format
FIB$C_ISO_LATIN | ISO Latin-1 Format
FIB$C_UCS2 | Unicode (UCS-2) Format

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 the volume.

#### B.3.1.2 Controlling the Format of Returned File Names

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.

Table B-9 New FIB$W_NMCTL Flags
Flag Name | Interpretation
--- | ---
FIB$V_NAMES_8BIT | Caller can accept (8-bit) ODS-2 and ISO Latin-1 formats
FIB$V_NAMES_16BIT | Caller can accept (16-bit) Unicode (UCS-2) format.

These new flags control the format of returned file specifications as follows:

- Both flags clear
  Only ODS-2 format names are returned. Note that this includes specifications that were originally in ISO Latin-1 format or Unicode (UCS-2) format but converted to ODS-2 format before being stored on the volume. All specifications are converted to uppercase before being returned.
- FIB$V_ NAMES_8BIT set
  FIB$V_ NAMES_16BIT clear
  Only those file specifications stored in ODS-2 and ISO Latin-1 formats are returned. The value in the FIB$B_NAME_FORMAT_OUT field indicates the format of the particular name being returned. ODS-2 format file specifications are not converted to uppercase before being returned.
- FIB$V_ NAMES_8BIT clear
  FIB$V_ NAMES_16BIT set
  All file specifications are returned in Unicode (UCS-2) format.
- Both flags set
  File specifications are returned in the format stored on the volume. This is the simplest format compatible with the file name syntax and the characters it contains. For example, a specification originally in Unicode format that only contains characters that are part of the ISO Latin-1 character set, are returned in ISO Latin-1 format.

#### 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:

            A*.DOC

could now correspond to the following ISO Latin-1 file specification:

            A sample name with periods.and.other;punctuation#in the name.doc;1

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.

File Format | Sample Pseudoname
--- | ---
ISO Latin-1 (FIB$C_ISL1) | \pISO_LATIN\.???
Unicode (FIB$C_UCS2) | \pUNICODE\.???

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.

Table B-10 FIB Flag Settings and Format of Related Returned Names
FIB Flag Settings | File Formats
--- | ---
8BIT | 16BIT | ODS-2 | ISO Latin-1 | Unicode
false | false | ODS-2 | pseudoname | pseudoname
true | false | ODS-2 | ISO Latin-1 | pseudoname
false | true | UCS-2 | UCS-2 | UCS-2
true | true | ODS-2 | ISO Latin-1 | UCS-2

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.

Buffer Sizes

Table B-11 shows the minimum size that each buffer must be to contain all possible returned file specifications.

Table B-11 Safe Buffer Sizes for Each File Format (in Bytes)
File Format | QIO Minimum | XQP Minimum
--- | --- | ---
ODS-2 | 86 | 86
ISO Latin-1 | 264 | 243
Unicode | 538 | 486

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.

#### B.3.1.4 Compatibility with Unchanged Applications

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:

- Leave the FIB$V_NAMES_8BIT and _16BIT flags clear, or
- Supply a FIB that does not include the new FIB$B_NAME_FORMAT_IN and FIB$B_NAME_FORMAT_OUT fields.

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.

### B.3.2 File Attribute Changes

The following sections describe the new file attributes introduced with ODS-5 and any changes to the semantics of existing attributes.

#### B.3.2.1 Modified File Attributes

Table B-12 shows the attributes that are modified or restricted for files on ODS-5 volumes.

Table B-12 Modified Attribute Codes
Attribute Name | Max Size (bytes) | Meaning
--- | --- | ---
ATR$C_ASCNAME | 252 | File specification stored in file header
ATR$C_FILE_SPEC | 4098 | Device, best try path, and file specification
ATR$C_FILNAM | 10 | Radix-50 file name
ATR$C_FILTYP | 4 | Radix-50 file type
ATR$C_FILVER | 2 | Radix-50 file version

ATR$C_ASCNAME

The ATR$C_ASCNAME attribute allows the file specification stored in a file's primary file header to be read and written.

Reading the ATR$C_ASCNAME Attribute

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.

Note The file system does not enforce a minimum length on the attribute buffer. If the file specification is longer than the attribute buffer, the value returned is truncated without signaling an error or warning. In contrast, the file system does enforce a maximum size for the attribute buffer. Supplying a larger buffer returns a BADPARAM error.

Writing the ATR$C_ASCNAME Attribute

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.

ATR$C_FILE_SPEC

The FILE_SPEC attribute is a read-only attribute that returns the physical file specification in the form:

            DDnn:[DIR1.DIR2_DIRn]name.type;1

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.

ATR$C_FILNAM, ATR$C_FILTYP, and ATR$C_FILVER

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:

- File name: 15 characters (10 bytes)
- File type: 6 characters (4 bytes)

As a result of the additional character and length restrictions, only a subset of legal ODS-2 file names is expressible in the Radix-50 encoding.

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.

Note ##### 3 39-character file name + 1-character delimiter (.) + 39-character file type + 1-character delimiter (;) + 5-character version number = 85 characters. ##### 4 236-character file name, delimiter (.), file type + 1-character delimiter (;) + 5-character version number = 242 characters. ##### 5 118-character file name, delimiter (.), file type + 1-character delimiter (;) + 5-character version number = 124 characters. ##### 6 When you access files on an ODS-5 volume from a VAX system in a mixed architecture OpenVMS system, no escaped forms are returned. For an ODS-2 or ISO Latin-1 file format, the name stored in the file header is returned. For a UCS-2 file format, a pseudoname is returned, followed by the file identifier in parentheses. For example:
`DKA100:[ABC]\pUNICODE\.??? (10095,5,0)`

Previous | Next | Contents | Index

| privacy and legal statement |
6536PRO_007.HTML