Updated: 11 December 1998

OpenVMS Guide to Extended File Specifications

The PURGE command accepts the /STYLE qualifier to select the file name format for display purposes when performing the command.

$ PURGE/STYLE=(keyword)

In the following examples, the ellipsis (...) represents many characters within the file name. These examples use the CONFIRM qualifier to generate a system message.

PURGE using default (CONDENSED):

$ PURGE/CONFIRM DELETE TEST$ODS5:[23,1,0]abcdefg. . .QRSTUVWXY.abcdefg. . .tuvwxy;1 ? [N]: Y

When the full file specification is needed, use the PURGE command with the /STYLE qualifier and the EXPANDED keyword:

$ PURGE/CONFIRM/STYLE=EXPANDED DELETE TEST$ODS5:[TEST.RANDOMTESTING.RANDOM]abcdefg. . .QRSTUVWXY.ab cdefg. . .tuvwxy;1 ? [N]: Y

3.7 Displaying Extended File Names on a Terminal

When you want to display extended file names on a terminal, you must specify ISO Latin-1 as the character set for the terminal to display. Otherwise, the characters displayed on the terminal may not match those shown by a PC. The characters that differ between the DEC MCS and the ISO Latin-1 character sets are listed in Figure C-1.

To display the ISO Latin-1 character set correctly on a DECterm, select UPSS ISO Latin 1 from the General submenu on the Options menu.

To display the DEC Multinational character set correctly on a DECterm, select UPSS DEC Supplemental from the General submenu on the Options menu.

To display the ISO Latin-1 character set correctly on a VT320 or VT420, select UPSS ISO Latin 1 from the General submenu on the Setup menu.

To display the DEC Multinational character set correctly on a VT320 or VT420, select UPSS DEC Supplemental from the General submenu on the Setup menu.

This chapter describes how to evaluate an application's support for Extended File Specifications.

4.1 Evaluating Your Current Support Status

As part of testing OpenVMS Alpha Version 7.2, OpenVMS application developers should evaluate and test all existing applications to determine their current level of support for Extended File Specifications and whether that level is appropriate. See Section 2.1 for a description of the levels of support.

Any applications that are coded to undocumented interfaces may not provide support for either deep directories or extended file names. Section 4.1.2 lists additional application attributes that may prevent an application from supporting extended file names. Section 4.1.3 lists additional application attributes that may prevent an application from supporting ODS-5 volumes.

You can choose either to modify these applications to support Extended File Specifications or not to use them under Extended File Specifications. For information on how to modify an application to provide default support for Extended File Specifications, see Section 4.2.1. For information on how to upgrade an application to full support, see Section 4.2.2.

4.1.1 Default Support

Most unmodified OpenVMS applications fall into the default support category. Specifically, these applications use the traditional API rather than the new API when making RMS calls (see Section B.2 for details about the new RMS API). Applications that use high-level language calls to perform file operations will also fit into this category unless the language run-time libraries have been modified to full support.¹ In most cases, you will not need to modify these applications for them to function successfully under Extended File Specifications.

4.1.2 No Support for Extended File Names

An application that does any of the following may not support extended file names:

1. Uses the QIO interface to specify file names. Developers should examine all layered products and applications and evaluate any file name interaction between the RMS and the XQP interfaces. The format for extended file names varies for each interface. As a result, an application can no longer assume that it can use the same file name for both RMS and the XQP. In addition, the XQP does not allow an unmodified application to use extended file names. For more information about the changes made to the XQP to support extended file names, see Section B.3. Valid file names could differ between interfaces.
2. Makes assumptions about the syntax of file specifications, such as the placement of delimiters and legal characters.
3. Makes assumptions about the case of file specifications. RMS no longer converts mixed and lowercase file specifications to uppercase in all cases. This could affect string matching operations.
4. Depends on the traditional directory depth (fewer than 8 levels).

An application that uses internal knowledge of the file system, including knowledge of the contents of a directory and how file header data is structured on a disk cannot work correctly on an ODS-5 volume.

4.2 Upgrading an Application to Support Extended File Specifications

The following sections describe the changes necessary to upgrade the level of support for Extended File Specifications. Note that you must first ensure that the application meets the default support level before you can upgrade it to the full support level.

To upgrade an application to provide default support for Extended File Specifications, you must ensure that it minimally supports both the ODS-5 volume structure and extended file naming as recommended in Sections 4.2.1.1 and 4.2.1.2, respectively. Default support is defined in Section 2.1.2.

4.2.1.1 Providing Support for ODS-5

Applications that do not support the new ODS-5 volume structure do not operate successfully on these volumes even if they encounter only traditional file specifications.

If an application does not work properly on an ODS-5 volume, examine the application for the following:

• Does the application use physical or logical I/O to bypass the file system when accessing the volume, or does it access metadata files such as BITMAP.SYS directly? These applications are usually system programs, such as disk defragmenters, or programs that try to avoid overhead by accessing the disk directly. These applications rely on specific knowledge of the file or directory structure on the disk, which has changed with introduction of the ODS-5 structure.
  Recommendation: Applications should use documented interfaces and structures whenever possible.
• Does the application access and interpret the contents of directory files directly? If so, the application may fail when it encounters a directory that contains extended file names.
  Recommendation: Modify the application to use the search functions provided with the RMS² or QIO interface, or with LIBRTL routines such as LIB$FIND_FILE.

If an application does not handle extended names successfully, examine the application for any the following:

• Does the application attempt to parse or assume knowledge of the syntax of a file specification? For example, the application might search for a bracket ([) to locate the beginning of a directory specification, or for a space character to mark the end of a file specification.
  Recommendation: The application should rely on RMS to determine whether a file specification is legal rather than pretesting the actual name. Use the NAM$L_NODE, NAM$L_DEV, NAM$L_DIR, NAM$L_TYPE, and NAM$L_VER fields of the NAM block or SYS$FILESCAN to retrieve this information.
• Does the application attempt to determine if two file names are the same by doing a string comparison? Because file names are case-insensitive, and because there are several ways to represent some characters, a string compare may fail even though two strings represent the same file.
  Recommendation: See the example program [SYSHLP.EXAMPLES]FILENAME_COMPARE.C for a way to use the new system service $CVT_FILENAMES to compare filenames.
• Does the application depend on the NAM$V_DIR_LVLS bits in the NAM$L_FNB field to determine how many directory levels there are in the current file specification? Because there are only three bits in this field, it can only specify a maximum of eight levels. Applications seldom use these bits; they are mainly used by RMS when a NAM is specified as a related file specification.
  Recommendation: Starting with OpenVMS Version 7.2, there is a new larger field available in both the NAM and the NAML blocks, NAM$W_LONG_DIR_LEVELS. Use this field to locate the correct number of directory levels.
• Does the application rely on the NAM$V_WILD_UFD and SFD1 - SFD7 bits to determine where there are wildcard directories? Because there are only eight of these bits, they can only report wildcards in the first eight directory levels. Applications seldom use these bits; they are mainly used by RMS when a NAM is specified as a related file specification.
  Recommendation: Starting with OpenVMS Version 7.2, there is a new field available in both the NAM and NAML block, NAML$W_FIRST_WILD_DIR. Use this field to locate the highest directory level where a wildcard is to be found.
• Does the application use the QIO interface to the file system and specify or request a file name from QIO directly? The QIO interface requires that an application specify explicitly that it understands extended file names before it will accept or return the names. In addition, the file name format for extended file names is not identical between RMS and the QIO interface. Additionally, some file names may be specified in 2-byte Unicode (UCS-2) characters. Your application must be capable of dealing with 1 character that spans 2 bytes.
  Recommendations: Most applications that use the QIO interface also use RMS to parse file specifications and retrieve the file and directory ID for the file. They then use these ID values to access the file with the QIO interface. This method of access continues to work with extended names. Compaq recommends changing to this method to fix the problem.
  You can also obtain the name that the QIO system uses from the NAML$L_FILESYS_NAME field of a NAML block, or use the new system service (SYS$CVT_FILENAME) to convert between the RMS and the QIO file name. In this case, you will also need to provide an expanded FIB block to the QIO service to specify that your application understands extended names, expand your buffers to the maximum size, and prepare to deal with 2-byte Unicode characters.

Some OpenVMS applications, such as system or disk management utilities, may require full support for Extended File Specifications. Typically, these are utilities that must be able to view and manipulate all file specifications without DID or FID abbreviation. To upgrade an application so that it fully supports all the features of Extended File Specifications, do the following:

1. Convert all uses of the RMS NAM block to the new NAML block.
2. Expand the input and output file name buffers used by RMS. To do this, use the NAML long_expanded and long_resultant buffer pointers (NAML$L_LONG_EXPAND and NAML$L_LONG_RESULT) rather than the short buffer pointers (NAML$L_ESA and NAML$L_RSA), and increase the buffer sizes from NAM$C_MAXRSS to NAML$C_MAXRSS.
3. If long file names (greater than 255 bytes) are specified in the FAB file name buffer field (FAB$L_FNA), use the NAML long_filename buffer field (NAML$L_LONG_FILENAME) instead. If long file names are specified in the FAB default name buffer field (FAB$L_DNA), use the NAML default name buffer field (NAML$L_LONG_DEFNAME) instead.
4. If you use the LIB$FIND_FILE, LIB$RENAME or LIB$DELETE routines, set LIB$M_FIL_LONG_NAMES in the flags argument (flags is a new argument to the LIB$DELETE routine). Note that you can use the NAML block in place of the NAM block to pass information to LIB$FILE_SCAN without additional changes.
5. If you use the LIB$FID_TO_NAME routine, the descriptor for the returned file specification may need to be changed to take advantage of the increased maximum allowed of 4095 (NAML$C_MAXRSS) bytes.
6. If you use the FDL$CREATE, FDL$GENERATE, FDL$PARSE, or FDL$RELEASE routine, you must set FDL$M_LONG_NAMES in the flags argument.
7. Examine the source code for any additional assumptions made internally that a file specification is no longer than 255 8-bit bytes.

Extended File Specifications enables users to use Windows-style file specifications in an OpenVMS environment. Among the ways you can help users become accustomed to Extended File Specifications is to explain some differences they might see between ODS-2 and ODS-5 file names. These differences become most apparent when users change from ODS-2 to ODS-5 styles.

Following are usage notes that you, as system manager, might pass on to users. These notes have been divided into the following categories:

• New Extended File Specifications characteristics
• ODS-2 and ODS-5 used together
• Architecture-related notes

The following notes discuss issues related to new HSF characteristics that are unfamiliar to users.

Be Aware of Volume Structure

So that you can place ODS-5 files on ODS-5 volumes, make sure you know whether a disk is an ODS-2 or ODS-5 volume.

You can display the type of volume by issuing commands like the following:

$ SHOW DEVICE DKA500:/FULL Disk AABOUT$DKA500:, device type RZ25, is online, allocated, deallocate on dismount, mounted, file-oriented device, shareable. Error count 0 Operations completed 155 . . . Volume Status: ODS-5, subject to mount verification, file high-water marking, write-back caching enabled. $ SHOW DEVICE DKA200:/FULL Disk AABOUT$DKA200:, device type RZ25, is online, allocated, deallocate on dismount, mounted, file-oriented device, shareable. Error count 0 Operations completed 232 . . . Volume Status: ODS-2, subject to mount verification, file high-water marking, write-back caching enabled.

After each command, the "Volume Status:" displayed indicates whether the volume is ODS-5 or ODS-2.

Do Not Use Extended File Names on ODS-2 Volumes

You cannot create a file with an extended file name on an ODS-2 volume.

In the following example, DKA200 is an ODS-2 volume, and the parse style is EXTENDED, which causes RMS to return an error message.

$ SET DEFAULT DKA200:[TEST] $ CREATE x.x.x.x %CREATE-E-OPENOUT, error opening DAK200:[TEST]X^.X^.X.X; as output -RMS-E-CRE, ACP file create failed -SYSTEM-W-BADFILEVER, bad file version number

Case Is Determined by the First Instance of an Extended File Name

On an ODS-5 volume, the case for all versions of a file name is identical; the case is preserved as the file name was first created.

In the following example, DKA500 is an ODS-5 disk.

$ SET DEFAULT DKA500:[TEST] $ SET PROCESS /PARSE_STYLE=EXTENDED $ CREATE myfile.txt [Ctrl/Z] $ CREATE MYFILE.TXT [Ctrl/Z] $ DIRECTORY Directory DKA500:[TEST] myfile.txt;2 myfile.txt;1

Be Aware of Extended File Specifications Case Preservation and Case Blindness

Although an ODS-5 volume preserves the case of a file as it is first entered, file searches are performed in a case-blind manner. Similarly, users must also be careful when they do comparisons, such as when they use DCL string functions such as .EQS. and F$LOCATE in a DCL command procedure.

The following example demonstrates the importance of case-blind matching of file names in DCL. In the program, notice that you specify no argument to do a case-sensitive match but that you specify an argument to do a case-blind match.

This program uses F$SEARCH to find all files that have a file type of ".TXT." Because RMS (and thus F$SEARCH) does case-blind matching, F$SEARCH also finds files with the file type ".txt." F$SEARCH then uses F$LOCATE to search the file name for "TEST." Because F$LOCATE does case-sensitive comparisons, it fails to match unless you first change the string to uppercase.

$ case_blind = 0 $ if p1 .nes. "" then case_blind = 1 (1) $loop: $ file = f$search("*.TXT;") (2) $ if file .eqs. "" then goto not_found $ write sys$output "Search returns " + file $ if case_blind .eq. 1 then file = f$edit(file,"UPCASE") (3) $ if (f$locate("TEST",file) .ne. f$length(file)) then goto found (4) $ goto loop $found: $ write sys$output "Found a file matching TEST" $ exit $not_found: $ write sys$output "Did not find file matching TEST" $ exit

Following are explanations of the callouts in the example.

1. Set "case_blind" to 1 if there is an argument (which requests the program to do a case-blind comparison).
2. Get a file ending in ".TXT" or ".txt" (because F$SEARCH is case-blind).
3. If a case-blind comparison was selected in Step 1, change the file name to uppercase to make a case-blind comparison.
4. If F$LOCATE finds a file, it will go to "found:."

In the following example, the search program performs a case-sensitive search and does not find a match.

$ @test Search returns DKA300:[FISHER]test.txt;1 Did not find file matching TEST

In the following example, the search program performs a case-blind search and does find a match.

$ @test case-blind Search returns DKA300:[FISHER]test.txt;1 Found a file matching TEST

Abbreviated and Full Directories Listed Separately with CONDENSED File Names

Some system utilities and DCL commands, such as DIRECTORY, have a style switch to control how they display file names. If the style is CONDENSED, file names up to 255 bytes in length are displayed. When a file specification reaches the 255-byte limit, the directory name is abbreviated to a directory ID (DID).

The following example shows a CONDENSED directory name. The DIRECTORY command considers a DID abbreviated directory name as different from the unabbreviated directory name and therefore generates a separate header when the abbreviation occurs.

$ DIR/STYLE=CONDENSED Directory DKA300:[DEEPER.aaaa.bbbb.cccc.dddd.eeee.ffff.gggg.hhhh.iiii._ten.aaaa. bbbb.cccc.dddd.eeee.ffff.gggg.hhhh.iiii._ten.aaaa.bbbb.cccc.dddd.eeee.ffff.gggg. hhhh.iiii._ten.aaaa.bbbb.cccc.dddd.eeee.ffff.gggg.hhhh.iiii._ten](1) aaaa.txt;1 Total of 1 file. Directory DKA300:[528,7036,0](2) xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.txt;1 Total of 1 file. Grand total of 2 directories, 2 files.(3)

1. With the CONDENSED style, if the combination of the directory name and file name does not exceed 255 bytes, the directory name is not shortened to a DID.
2. With the CONDENSED style, if the combination of the directory name and file name exceeds 255 bytes, the directory name is shortened to a DID.
3. When you issue a DIRECTORY command that displays both a full and an abbreviated directory format for the same directory name, DIRECTORY counts these as two different directories.

For more information about DIRECTORY commands, see the OpenVMS DCL Dictionary.

Be Aware of Extended File Specifications as Equivalence Names

The Extended File Specifications escape character (^), is not used in a logical name equivalence string. When you define a logical name for an extended file name that requires escape characters, omit the escape characters from the extended file name in the DEFINE command. For example:

$ define xxx a&b $ dir xxx Directory DKA500:[EXTENDED_FILES] a^&b.txt;1 Total of 1 file.

A.2 ODS-2 and ODS-5 Used Together

The following notes discuss issues related to using ODS-2 and ODS-5 together in a cluster.

Use Traditional File Names in a Mixed-Volume Environment

To avoid ODS-2 and ODS-5 file name incompatibility if you are working with both ODS-2 and ODS-5 volumes, and to assure backward compatibility with prior versions of OpenVMS, use only ODS-2 traditional file names.

Error Messages Can Vary Depending on Parse Style

Error messages displayed to users might vary depending on the parse style. Syntax errors that were formerly detected at the DCL-level are now passed on to the file system level, RMS and XQP, for example, if the parse style is EXTENDED. As a result, the messages users receive for file syntax errors might be slightly different depending on the parse style and volume structure.

Following are examples of varying error messages.

• Examples of TRADITIONAL and EXTENDED styles on an ODS-5 volume:

  $ SHOW DEVICE DKA500:/FULL Disk AABOUT$DKA500:, device type RZ25, is online, allocated, deallocate on dismount, mounted, file-oriented device, shareable. Error count 0 Operations completed 155 . . . Volume Status: ODS-5, (1) subject to mount verification, file high-water marking, write-back caching enabled. $ SET PROCESS /PARSE_STYLE=TRADITIONAL (2) $ OPEN /WRITE FILE z.z.z.z %DCL-W-PARMDEL, invalid parameter delimiter - check use of special characters \.Z\ (3) $ SET PROCESS /PARSE_STYLE=EXTENDED (4) $ OPEN /WRITE FILE z.z.z.z $ (5)

  ---

  Previous

  Next

  Contents

  Index

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

  6536PRO_004.HTML