complete file specifications to 255 bytes. $ CREATE This.File.Name.Has.A.Lot.Of.Periods.DAT $ CREATE - _$ ThisIsAVeryLongFileName^&ItWillKeepGoingForLotsAndLotsOfCha - _$ racters.ExceedingThe39^,39presentInPreviousVersionsOfOpenVMS $ DIRECTORY Directory TEST$ODS5:[TESTING] ThisIsAVeryLongFileName^&ItWillKeepGoingForLotsAndLotsOfCharac ters.ExceedingThe39^,39presentInPreviousVersionsOfOpenVMS;1 This^.File^.Name^.Has^.A^.Lot^.Of^.Periods.DAT;1 Total of 2 files. 4 Case_Preservation Mixed-case and lowercase file names are retained in their original form on ODS-5 volumes. However, the file system on OpenVMS preserves the case of file names as they are first entered. When you create more than one file with the same name differing only in case, DCL treats the subsequent files as versions, and converts them to the same case as the original file. For example, the following commands: $ CREATE CaPri.;1 $ CREATE CAPRI $ CREATE capri produce the resulting files: CaPri.;1 CaPri.;2 CaPri.;3 4 Using_Wildcards Single- and multiple-character wildcards still function as expected with ODS-5 files. A single-character wildcard represents exactly one character in either the file name or file type, but may not be used in the file version string. A multiple-character wildcard can represent any number of characters starting with zero in the file name or file type. A multiple-character wildcard can be used in place of a version string. 5 Wildcard_Characters The following characters are wildcard characters when working on any OpenVMS 7.2 or later volume: o The asterisk (*) is a multiple-character wildcard. o The percent sign (%) is a single-character wildcard. o The question mark (?) is a single-character wildcard. The percent sign (%) continues to be a single-character wildcard to maintain compatibility with existing applications. The percent sign (%) may be used as a literal character when preceded by the circumflex (^) and is also a literal character in Windows NT file names. Therefore, in addition to the percent sign, RMS also recognizes the question mark (?) as a single character wildcard. The question mark functions identically to the percent sign as a wildcard character on OpenVMS 7.2 and later. The percent sign and the question mark matches exactly one character in a search pattern. 5 Wildcard_Syntax Although DCL preserves the case of extended file names, wildcard matching is case blind. When you perform a search operation with wildcards it continues to match only against the corresponding character in the same part of the target specification. The following table contains examples of some wildcard searches. The pattern... matches... ...but doesn't match A*B;* AHAB.;1 A.B;1 A.*.B* A^.DISK.BLOCK;1 A^.C^.B.DAT;1 A?B.TXT;* A^.B.TXT;5 A^.^.B.TXT;1 *.DAT Lots^.of^.Periods.dat;1DAT.;1 Mil?no.dat Milano.dat;1 Millaano.dat;1 NAPOLI.?.DAT napoli.q.dat;1 napoli.abc77.dat;1 4 Case_Sensitivity_and_Blindness In prior versions of OpenVMS, DCL and RMS converted all file specifications to uppercase. When using Extended File Specifications, the case of all file names is preserved as created by the user. Files and directories can have mixed case names in extended file names. Original file name ODS-2 Volume ODS-5 Volume MILANO;1 MILANO.;1 MILANO.;1 SanRemo SANREMO.;1 SanRemo.;1 genoa..1 GENOA.;1 genoa.;1 3 Directory_Specification_Differences The following topics describe the deeper directory structures and extended naming syntax available with Extended File Specifications. It is now possible to go beyond the eight levels of directories previously supported in OpenVMS. See also the OpenVMS User's Manual and the Guide to OpenVMS File Applications for more information about directory specifications in Extended File Specifications. 4 Deep_Directory_Structures OpenVMS 7.2 and later supports deep nesting of up to 255 directories with the restriction that the total directory specification must be no longer than 512 8-bit or 16-bit characters. For example, a user can create the following directories on an ODS-2 or ODS-5 volume: $ CREATE/DIRECTORY [a.b.c.d.e.f.g.h.i.j.k.l.m] A user can create the following directory with a long name on an ODS-5 volume: $ CREATE/DIRECTORY - [.AVeryLongDirectoryNameWhichHasNothingToDoWithAnythingInParticular] 4 Directory_Naming_Syntax When using Extended File Specifications, directory names conform to most of the same conventions as file names when using the ISO Latin-1 character set. Periods and special characters may be present in the directory name, but they must be preceded by a circumflex (^) in order to be recognized as literal characters, as shown in the following table: CREATE/DIRECTORY. . . Result [Hi^&Bye] Hi^&Bye.DIR;1 [Lots^.Of^.Periods^.In^.ThisLots^.Of^.Periods^.In^.This^ .Name.DIR;1 4 Directory_ID_and_File_ID_Abbreviation Under some circumstances, a full file specification may contain more characters than the 255 bytes allowed by unmodified applications. If a file specification that such an application needs exceeds 255 bytes in length, RMS generates a shorter file specification by abbreviating the directory to a DID abbreviation, and if necessary, the filename to a FID abbreviation. When the file specification is too long, RMS first attempts to generate a shorter directory specification by identifying the directory with its directory ID. This shorter specification is referred to as a DID abbreviation. TEST$ODS5:[5953,9,0]Alghero.TXT;1 Note that this form of the directory name must have three numbers and two commas to avoid ambiguity with UIC format directory names. With the DIRECTORY command you can view the shorter DID abbreviation version as well as the full version of a file specification. 3 Working_in_Mixed_Environments If working in an environment which contains both OpenVMS Alpha and OpenVMS VAX systems, it becomes more important to know on which type of volume files are being created and on which type of volume your default directory resides. When accessing an ODS-5 volume, you need to set the parse style to EXTENDED to accept and display extended file specifications. The default setting is TRADITIONAL. To set the parse style, enter the command: $ SET PROCESS/PARSE_STYLE=EXTENDED When working in a mixed environment of OpenVMS VAX and OpenVMS Alpha, it is important for users to realize upon which system they are working. OpenVMS 7.2 and later allows VAX systems to mount ODS-5 volumes; however users on OpenVMS VAX systems can access only files with ODS-2-compliant file names. When working in a mixed environment of ODS-2 and ODS-5 volumes, keep in mind the restrictions of ODS-2 file names when creating files on ODS-5 volumes. If a file is created with special characters on an ODS-5 volume, the file must be given an ODS-2 compliant name if it is copied to an ODS-2 volume. 3 DCL_Command_Parameters Command procedures that use file names as parameters can produce different results in an ODS-5 environment. You can switch from the TRADITIONAL to the EXTENDED parse style, and this section describes the following areas that may be affected if you choose to do so: o Command procedure file specification o Case preservation and $FILE o Ampersand versus apostrophe substitution 3 Command_File_Specification If indirect command procedures are used, you may need to put quotes around file specifications. The following examples show the differences in output between TRADITIONAL and EXTENDED parse styles when using the same command file, SS.COM: $ create ss.com $ if p1 .nes. "" then write sys$output "p1 = ",p1 $ if p2 .nes. "" then write sys$output "p2 = ",p2 $ if p3 .nes. "" then write sys$output "p3 = ",p3 o Setting the parse style to an ODS-2 environment and running SS.COM, the following output occurs: $ set process/parse_style=traditional $ @ss ^ p2 p3 p1 = ^ p2 = P2 p3 = P3 Note that the circumflex (^) is the first argument, and that the case is not preserved for the p2 and p3 variables. o Setting the parse style to an ODS-5 environment, the following output occurs when running the same command procedure: $ set process/parse_style=extended $ @ss ^ p2 p3 p1 = ^ P2 p2 = P3 Note that the command procedure recognizes the circumflex (^) as the escape character, and "^ P2" is the first argument. o Adding quotes to the circumflex (^) produces the following outcome: $ @ss "^" p2 p3 p1 = ^ p2 = P2 p3 = P3 Because the circumflex (^) is within a quoted string, it is not treated as an escape character. o Adding quotes to the p3 variable produces the following outcome: $ @ss "^" p2 "p3" p1 = ^ p2 = P2 p3 = p3 Note that the case is preserved for the p3 variable. o In an ODS-2 environment, the following command treats the circumflex (^) and the p2 and p3 strings as arguments, and the command procedure produces the following results: $ set process/parse_style=traditional $ @ss^ p2 p3 p1 = ^ p2 = P2 p3 = P3 o In an ODS-5 environment, the circumflex (^) is treated as the escape character and DCL looks for the file "SS^_P2.COM", which results in the following error: $ set process/parse_style=extended $ @ss^ p2 p3 %DCL-E-OPENIN, error opening USER$DISK:[TEST]SS^_P2.COM; as input -RMS-E-ACC, ACP file access failed -SYSTEM-W-BADFILENAME, bad file name syntax 4 Case_Preservation_and_$FILE DCL attempts to preserve the casing of file specifications. It can do this only for commands defined with the Command Definition Utility (CDU). DCL preserves case for any item defined in the command definition file (.CLD) with the $FILE parse type. Refer to the Command Definition Utility manual for more information. 4 Ampersand_Versus_Apostrophe_Substitution You can use ampersand (&) substitution as opposed to apostrophe substitution, to preserve case during traditional parsing. The following traditional parsing example shows a series of commands that change the case of a character string: $ set process/parse_style=traditional $ x = "string" $ define y 'x' $ sho log y "Y" = "STRING" (LNM$PROCESS_TABLE) $ define y &x %DCL-I-SUPERSEDE, previous value of Y has been superseded $ sho log y "Y" = "string" (LNM$PROCESS_TABLE) Note that the use of the ampersand (&) preserved the case of the character string assigned to the x variable. Apostrophe substitution takes place before the command line is set to uppercase, and ampersand substitution takes place after the command line is set to uppercase. The following extended parsing example shows the same series of commands: $ set process/parse_style=extended $ define y 'x' %DCL-I-SUPERSEDE, previous value of Y has been superseded $ sho log y "Y" = "string" (LNM$PROCESS_TABLE) $ define y &x %DCL-I-SUPERSEDE, previous value of Y has been superseded $ sho log y "Y" = "string" (LNM$PROCESS_TABLE) Note that both character strings for the y variable are returned lowercase. This happens because the DEFINE command uses $FILE, which preserves the case. Ampersand substitution can therefore be used to specify EXTENDED file names even though the parse style is set to TRADITIONAL, as shown in the following example: $ set process/parse=extended $ cre file^ name.doc Contents of an ODS5 file Exit $ set process/parse=traditional $ a = "file^ name.doc" $ type file^ name.doc %DCL-W-PARMDEL, invalid parameter delimiter - check use of special characters \^NAME\ $ type 'a' %DCL-W-PARMDEL, invalid parameter delimiter - check use of special characters \^NAME\ $ type &a Contents of an ODS5 file NOTE Ampersand substitution does not work for foreign commands. 3 DECwindows_Output When using a DECwindows DECterm terminal emulator, you must select UPSS ISO Latin-1 from the General... submenu on the Options menu to display the full ISO Latin-1 character set correctly. F$EDIT assumes that the setting is 8-Bit Multinational Characters, as do many text editors. This can affect the output of ODS-5-compliant file specifications. 2 Programming The following topics describe how to evaluate an application's support for Extended File Specifications, and provides guidelines for upgrading that support. 3 Evaluating_Support_Status As part of testing OpenVMS Alpha Version 7.2 (and later), 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. Most unmodified OpenVMS applications fall into the default support category. Specifically, these applications use the traditional NAM block rather than the new NAML block when making RMS calls. 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. However, you can choose to upgrade these applications to full support, if necessary. However, any applications that are coded to undocumented interfaces, or include any of the following may fall into one of the no support categories: 1. Use of 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, valid file names could differ between interfaces. (No extended file name support) NOTE All XQP applications that receive file names from the XQP and encounter extended file names on a ODS-5 disk will see pseudonames returned in place of Unicode (UCS-2) or ISO Latin-1 names that are not ODS-2 compliant. This may cause applications to act in an unpredictable manner. 2. Assumptions about the syntax of file specifications, such as the placement of delimiters and legal characters. (No extended file name support) 3. Assumptions about the case of file specifications. Mixed and lowercase file specifications will not be converted to uppercase, which could affect string matching operations. (No extended file name support) 4. Dependence on the traditional directory depth (fewer than 8 levels). (No extended file name support) 5. Internal knowledge of the file system, which includes knowledge of the contents of a directory and how file header data is structured on a disk. (No ODS-5 support) You can choose either to modify these applications to support Extended File Specifications or not to use them under Extended File Specifications. 3 Upgrading_Support The following topics describe the changes necessary to upgrade the level of support for ODS-5. Note that you must first ensure that the application meets the default support level before you can upgrade it to the full support level. NOTE If you are not using the RMS or QIO interfaces to perform disk I/O, the Extended File Specifications support level of your application depends on whether the interface you are using (such as a language run-time library) provides full support. 4 Upgrading_to_Default_Support 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 the following topics 4 Supporting_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. These applications use physical or logical I/O to bypass the file system when they access the volume or access directory files or other metadata files directly, and therefore must be installed with privileges or run by a user who has privileges. 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. Recommendations: Applications should use documented interfaces and structures whenever possible. 4 Supporting_Long_File_Names If an application does not handle extended names successfully, examine the application for any the following: o 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. o 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. o 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. o 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. o 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. VSI recommends changing to this method to fix 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. 4 Upgrading_to_Full_Support 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 default FAB name buffer field (FAB$L_DNA), use the default NAML 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.