HP OpenVMS System Manager's Manual, Volume 1:...

Using Files and Directories

Considerations Before Enabling ODS-5 Volumes

Understanding Extended File Specifications Features  

Feature	Description
New on-disk structure	Extended File Specifications support the latest volume On-Disk Structure (ODS): Level 5 (ODS-5). This volume structure provides the basis for creating and storing files with extended file names.
Additional character set support	A broader set of characters is available for naming files on OpenVMS. Extended File Specifications offers support for file names that use the 8-bit ISO Latin-1 character and 16-bit Unicode (UCS-2) character sets.
Extended file naming	File names can now exceed the traditional 39.39 character limit up to a maximum of 236 bytes.
Case preservation	Extended File Specifications preserve the case of file specifications created with ODS-5 attributes. However, the system still performs case-insensitive string matching.
Deep directory levels	To support deep directory levels, the length of directory specifications has been extended to a maximum of 512 characters.

For more information about each feature, refer to the OpenVMS User's Manual .

Using Extended File Specifications  

Beginning with OpenVMS Version 7.2, RMS allows you to use directory levels deeper than 8 as well as the new RMS API extensions on both ODS-2 and ODS-5 volumes by default. However, you can create extended file names only on an ODS-5 volume. Initializing a New Volume with ODS-5 Format and Converting from ODS-2 to ODS-5, respectively, explain how to create a new ODS-5 volume and how to convert an ODS-2 volume to an ODS-5 volume.

Once you change a volume to ODS-5, your programs can create and read extended file names. However, by default, DCL (as well as some applications) does not accept all extended names.¹ DCL also capitalizes any lowercase file names that users enter at the command line prompt.²

Enabling the Extended File Specifications Parsing Feature

For DCL to accept all extended file names, you must enable the Extended File Specifications file name parsing feature. On OpenVMS Alpha systems, you can instruct DCL to accept ODS-5 file names on a per-process basis by entering the following command:

$ SET PROCESS/PARSE_STYLE=EXTENDED

$ CREATE MY^[FILE

Ways to Enable Case Sensitivity

Traditionally, OpenVMS has stored all alphabetic characters in file name specifications as uppercase characters. In addition, file system operations using file name specifications were case insensitive.

The introduction of Extended File Specifications has allowed system tools and applications to store and display file specifications containing lowercase as well as uppercase alphabetic characters on ODS-5 volumes. File name specification operations, however, remained case-insensitive.

Beginning with OpenVMS Version 7.3-1, it has been possible for tools and applications to distinguish among file name specifications containing the same alphabetic characters that differ only in case.

You can set processes to ignore or notice the case sensitivity of file names.

Enable case sensitivity only when it is known to be supported by the layered product or application you are working with.

You can use any of three ways to enable case sensitivity on OpenVMS, as described in the following sections.

• Using the DCL Command SET PROCESS/CASE_LOOKUP=BLIND (or CASE_LOOKUP=SENSITIVE)

If you set your process to CASE_LOOKUP=BLIND and you create more than one file with the same name differing only in case, DCL treats these files as new versions of the older file and converts them to the same case as the original file.

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

$ SET DEFAULT DKA500:[TEST]

$ SET PROCESS /CASE_LOOKUP=BLIND/PARSE_STYLE=EXTENDED

$ CREATE NEWfile.txt

<Ctrl/z>

$ CREATE NEWFILE.txt

<Ctrl/z>

$ CREATE NeWFILE.txt

<Ctrl/z>

$ DIRECTORY

Directory DKA500:[TEST]

NEWfile.txt;3

NEWfile.txt;2

NEWfile.txt;1

If your process is set to CASE_LOOKUP=SENSITIVE and you create more than one file with the same name differing only in case, DCL treats subsequent files as new files and lists them as such.

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

$ SET DEFAULT DKA500:[TEST]

$ SET PROCESS /CASE_LOOKUP=SENSITIVE /PARSE_STYLE=EXTENDED

$ CREATE NEWfile.txt

<Ctrl/z>

$ CREATE NEWFILE.TXT

<Ctrl/z>

$ CREATE NeWfIlE.txt

<Ctrl/z>

$ DIRECTORY

NeWfIle.txt;1

NEWFILE.TXT;1

NEWfile.txt;1

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. Therefore, be careful when you do file comparisons, such as using DCL string functions like .EQS. and F$LOCATE, in a DCL command procedure.

If you are using an application that expects case sensitivity, or if you depend on case sensitivity in your environment, set your process to /CASE_LOOKUP=SENSITIVE. Be aware that using case sensitivity can create problems if you do not pay attention to your environment.

The default is SET PROCESS /CASE_LOOKUP=BLIND /PARSE_STYLE=EXTENDED. RMS uses this process default for case sensitivity.

• Setting an Option Within your Application in the NAML Block for Files Opened or Created Using RMS

The NAML block was introduced in OpenVMS Alpha Version 7.2 to support long file names. Beginning in OpenVMS Version 7.3-1, the NAML block has had a new field, NAML$V_CASE_LOOKUP, to override the process default case sensitivity.Within NAML$V_CASE_LOOKUP, you can set the following values for case sensitivity:

Table 1  Values for Case Sensitivity

Field Name	Description
NAML$C_CASE_LOOKUP_BLIND	Set by the user to tell RMS to ignore case when creating, deleting, or searching for files.
NAML$C_CASE_LOOKUP_SENSITIVE	Set by the user to tell RMS to include case as a criteria when creating, deleting, or searching for files.

If NAML$V_CASE_LOOKUP is zero, or if a NAML block is not used,the current process setting is used.

• Making a Call to Either $SET_PROCESS_PROPERTIES or $GETJPI Within Your Application

The $SET_PROCESS_PROPERTIES system service sets a simple valueassociated with a service. Beginning with Version 7.3-1, OpenVMS Alpha has supported the following new property codes for case sensitivity.

Table 2  Property Codes for Case Sensitivity

Property Code	Description
PPROP$C_CASE_LOOKUP_TEMP	Sets a value for only the life of the image. The value reverts to the permanent style on image rundown.Valid values are: PPROP$K_CASE_BLIND and PPROP$K_CASE_SENSITIVE.
PPROP$C_CASE_LOOKUP_PERM	Sets a value for the life of the process unless the style is set again. The value reverts to the permanent style on image rundown. Valid values are: PPROP$K_CASE_BLIND and PPROP$K_CASE_SENSITIVE.

The new item codes for the $GETJPI system service are the following:

JPI$CASE_LOOKUP_TEMP

JPI$CASE_LOOKUP_PERM

For more information about the $SET_PROCESS_PROPERTIESW systemservice, refer to the HP OpenVMS System Services Reference Manual.

These item codes return the values that are set by the system service $SET_PROCESS_PROPERTIESW, which can be either PROP$K_CASE_BLIND or PPROP$K_CASE_SENSITIVE.

Setting Users' Expectations of Extended File Specifications  

A system manager can help users become accustomed to Extended File Specifications by explaining the differences between ODS-2 and ODS-5 file names. These differences become most apparent when users change from ODS-2 to ODS-5 styles.

If you pass the following usage notes along, users might find them helpful. These notes are divided into the following categories:

• New Extended File Specifications characteristics



• ODS-2 and ODS-5 used together



• Architecture-related notes

New Extended File Specifications Characteristics  

The following notes discuss issues related to new Extended File Specifications characteristics that are unfamiliar to users.

Be Aware of Volume Structure

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

You can display the type of volume by entering commands similar to the following:

$ SHOW DEVICE DKA500:/FULL
 
  Disk AABOUT$DKA500:, device type DZ25 Disk, 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$DSA200:, device type RZ25 Disk, 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.

Do Not Use Extended File Names on ODS-2 Volumes

You cannot create a file with an ODS-5 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 DKA200:[TEST]X^.X^.X.X; as output
-RMS-E-CRE, ACP file create failed
-SYSTEM-W-BADFILEVER, bad file version number

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, the disk is ODS-5.

$ 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 

Keep in mind that although an ODS-5 disk preserves the case of a file as it is first entered, it searches for files in a case-blind manner. Similarly, users must also be careful when they do comparisons, such as when they use DCL string functions like .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 the files that have a file type of .TXT. Because RMS (and therefore F$SEARCH as well 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

1. Set case_blind to 1 if there is an argument (and a case-blind comparison can be made).
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:.

The following example shows the output when you run the program:

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

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



• If the style is EXPANDED, file names up to 4095 bytes in length are displayed.

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 abbreviation.
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 abbreviation.
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, refer to the HP OpenVMS DCL Dictionary.

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

The following examples show varying error messages.

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

  $ SHOW DEVICE DKA500:/FULL
   
    Disk AABOUT$DKA500:, device type RZ25 Disk, 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]  

  
  
  
  1. The volume is ODS-5.
  2. The parse style is set to TRADITIONAL.
  3. DCL returns an error on some ODS-5 file names such as this one.
  4. The parse style is set to EXTENDED.
  5. DCL creates the file.



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

   Disk AABOUT$DKA200:, device type RZ25 Disk, is online, allocated, deallocate
    on dismount, mounted, file-oriented device, shareable.
   
      Error count                    0    Operations completed 232
      .
      .
      .
   
    Volume Status:  ODS-2, [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
  %DCL-E-OPENIN, error opening 
  -RMS-E-CRE, ACP file create failed [5] 
  -SYSTEM-W-BADFILEVER, bad file version number 

  
  
  
  1. The volume is ODS-2.
  2. The parse style is set to TRADITIONAL.
  3. DCL returns an error message.
  4. The parse style is set to EXTENDED.
  5. DCL allows the file name, but XQP returns an error.



• Examples of different error messages for the same syntax error:

  $ SHOW DEVICE DKA500:/FULL
   
    Disk AABOUT$DKA500:, device type RZ25 Disk, 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] 
  $ CREATE a^<b.c
   
  %DCL-W-PARMDEL, invalid parameter delimiter - check use of special
  characters
   \^\ [3] 

  $ SET PROCESS /PARSE_STYLE=EXTENDED [4] 
  $ CREATE a^<b.c
   
  %CREATE-E-OPENOUT, error opening a^<b.c as output
  -RMS-F-SYN, file specification syntax error [5] 
  

  
  
  
  1. The volume is ODS-5.
  2. The parse style is set to TRADITIONAL.
  3. DCL returns an error message for a syntax error.
  4. The parse style is set to EXTENDED.
  5. RMS returns a different error message for the same syntax error.

Be Aware of Implicit File Name Output

Be wary of defaults when you allow utilities to create output files based on the file name being processed. Be sure you know where a file is being placed so you will not inadvertently try to place a file with an extended name on an ODS-2 volume.

The following examples show files being placed somewhere you might not expect:

• An error results if an application or a utility attempts to write an ODS-5 extended file name to an ODS-2 (DKA200:) volume; for example:

$ SHOW DEFAULT
  DKA200:[DOREO]
$ DUMP /OUTPUT DKA500:[DOREO]This^_is^_a^_file.Dat
%DUMP-E-OPENOUT, error opening DKA200:[DOREO]THIS^_IS^_A^_FILE.DMP;as output
-RMS-E-CRE, ACP file create failed
-SYSTEM-W-BADFILENAME, bad file name syntax

• A batch command file fails to execute if all of the following conditions are true:

  A log file is requested implicitly or explicitly.

  The implicit or explicit log file specification has an extended name (that is, the name is non-ODS-2-compliant).

  The log file is to be created on an ODS-2 volume.

  The batch command file does not execute because a log file cannot be created. Most frequently, this situation occurs when the logical name SYS$LOGIN refers to an ODS-2 volume; this is because log files are implicitly created on the SYS$LOGIN device. In addition, if notification is disabled, you are not notified that your batch job did not execute.
  
  To avoid the problem, use the /LOG= qualifier and an ODS-2-compliant log file specification when you submit command files with ODS-5 extended names.

Architecture-Related Notes  

The following notes discuss Extended File Specifications issues related to system architecture.

Extended File Names Are Not Visible from a VAX System

Although you can mount ODS-5 volumes on a VAX, if you log in to a VAX system, ODS-5 extended file names are not visible. In their place, you see a pseudoname:

• On VAX, if you attempt to display a file name that contains 2-byte Unicode characters, the pseudoname displayed is the following: \PUNICODE\.???



• Any other name that is not a legal ODS-2 name is displayed as \PISO_LATIN\.???

For example, the same directory listings as they appear on Alpha and VAX systems are:

• On an Alpha system:

  $ DIRECTORY DPA100:[TEST]
   
  Directory DPA100:[TEST]
   
  Accounting^_data.lis;1                  atest.txt;1




• On a VAX system:

  $ DIRECTORY DPA200:[TEST]
   
  Directory DPA200:[TEST]
   
  \PISO_LATIN\.???                       ATEST.TXT

In addition, the directory depth on a VAX is limited to 8 (or 16, using rooted logicals).

Physical Backups of ODS-5 Volumes on VAX Systems

On OpenVMS VAX systems, BACKUP supports ODS-5 volumes only when you specify the /PHYSICAL qualifier to back up a volume. The BACKUP /PHYSICAL command causes BACKUP to make a block-by-block physical backup of the disk, ignoring the structured contents of the disk.

On Alpha systems, you can use either the BACKUP /IMAGE or BACKUP /PHYSICAL command.

1	Even with the TRADITIONAL parse style, DCL allows some ODS-5 file names; for example, DCL accepts x.x.x.

2	Some applications also use DCL internally to read file names that users type after an application prompt.

( Number takes you back )

Considerations Before Enabling ODS-5 Volumes