|
OpenVMS Guide to Extended File Specifications
3.6.3 DELETE Command
The DELETE command accepts the /STYLE qualifier to select the file name
format for display purposes when performing the command.
In the following examples, the ellipsis (...) represents many
characters within the file name. These examples use the CONFIRM
qualifier to generate a system message.
DELETE using default (CONDENSED):
$ DELETE/CONFIRM abc*.*.*
DELETE TEST$ODS5:[TEST.RANDOMTESTING.RANDOM]abcAlphabet.stuff;1 ? [N]: Y
DELETE TEST$ODS5:[23,1,0] abcdefg. . .QRSTUVWXY.abcdefg. . .tuvw
xy;1 ? [N]: Y
|
When the full file specification is required, use the DELETE command
with the /STYLE qualifier and the EXPANDED keyword:
$ DELETE/CONFIRM/STYLE=EXPANDED abc*.*.*
DELETE TEST$ODS5:[TEST.RANDOMTESTING.RANDOM]abcAlphabet.stuff;1 ? [N]: Y
DELETE TEST$ODS5:[TEST.RANDOMTESTING.RANDOM]abcdefg. . .QRSTUVWX
Y.abcdefg. . .tuvwxy;1 ? [N]: Y
|
3.6.4 PURGE Command
The PURGE command accepts the /STYLE qualifier to select the file name
format for display purposes when performing the command.
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.
Chapter 4 Extended File Naming Considerations for OpenVMS Application Developers
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.1 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:
- 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.
- Makes assumptions about the syntax of file specifications, such as
the placement of delimiters and legal characters.
- 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.
- Depends on the traditional directory depth (fewer than 8 levels).
4.1.3 No Support for ODS-5 Volumes
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.
Note
1 As of OpenVMS Version 7.2, no
language RTLs have been upgraded to full support.
|
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.
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.2.1 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
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 RMS2 or
QIO interface, or with LIBRTL routines such as LIB$FIND_FILE.
4.2.1.2 Providing Support for Extended File Naming
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.
4.2.2 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:
- Convert all uses of the RMS NAM block to the new NAML block.
- 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.
- 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.
- 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.
- 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.
- 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.
- Examine the source code for any additional assumptions made
internally that a file specification is no longer than 255 8-bit bytes.
Note
2 RMS directory caching size has
drastically increased on OpenVMS Alpha Version 7.2, greatly improving
performance of the $SEARCH system service with large directories.
|
Appendix A Setting Users' Expectations of Extended File Specifications
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
A.1 New Extended File Specifications Characteristics
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.
- Set "case_blind" to 1 if there is an
argument (which requests the program to do a case-blind comparison).
- Get a file ending in ".TXT" or
".txt" (because F$SEARCH is case-blind).
- If a case-blind comparison was selected in
Step 1, change the file name to uppercase to make a case-blind
comparison.
- 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)
|
- 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.
- 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.
- 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.
|
|