Updated: 11 December 1998

OpenVMS Guide to Extended File Specifications

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

Table B-1 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

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 characters² 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 characters³ or 124 16-bit characters⁴
• 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-2.

Table B-2 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-2.

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-3.

Table B-3 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.

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-4.

Table B-4 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-5 shows the minimum size that each buffer must be to contain all possible returned file specifications.

Table B-5 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-6 shows the attributes that are modified or restricted for files on ODS-5 volumes.

Table B-6 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.

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. ⁵

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.

B.4 Programming Utility Changes

The following sections describe changes specific to OpenVMS programming utilities and their routines to support Extended File Specifications.

B.4.1 File Definition Language (FDL) Routines

The File Definition Language (FDL) routines have been enhanced on OpenVMS Version 7.2 for Alpha to support Extended File Specifications. A new flag, FDL$V_LONG_NAMES, has been added to the flags argument of the following routines:

• FDL$CREATE
• FDL$GENERATE
• FDL$PARSE
• FDL$RELEASE

The following sections describe the FDL$V_LONG_NAMES flag as it relates to each FDL routine.

Copyright © Compaq Computer Corporation 1998. All rights reserved. Legal

6536PRO_007.HTML