The following topics describe how to evaluate an application's
support for Extended File Specifications, and provides guidelines
for upgrading that support.
1 – 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.
2 – 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.
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 the following topics
2.2 – 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.
2.3 – 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.
2.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.