HP OpenVMS Systems Documentation

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)

  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, 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, 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 ("<" is not allowed even in an extended file name).

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 an extended file 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

The output file specified with the /OUTPUT qualifier defaults to the same name as the input file, with .DMP as the file type, in the default directory. While the input file specification is an extended name on an ODS-5 volume, the .DMP file must have a traditional name, because it will be written to an ODS-2 volume. As a result, an error occurs.

• A batch command file will fail to execute if the following conditions apply:
  • a log file was requested implicitly or explicitly and
  • the implicit or explicit log file specification would have an extended file name (that is, the name would be non-ODS-2-compliant) and
  • the log file would 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 extended file names.

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, extended file names are not visible. In their place, you will see a pseudoname:

• On VAX, if you attempt to display a file name that contains 2-byte Unicode characters, the pseudoname displayed is \PUNICODE\.???
• Any other name that is not a legal ODS-2 name is displayed as
  \PISO_LATIN\.???

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

• On an Alpha system:

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

• On an 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).

A.4 Restrictions

The following topic describes a restriction when using extended file names.

Tilde (~) As First Character in a File Name

The Compaq C Run Time Library (CRTL) allows a programmer to specify both Unix-style and VMS-style file specifications to routines such as creat() and fopen().

In Unix file specifications, a tilde (~) in the first character of a pathname represents the user's home directory. However, in an OpenVMS extended file name, a tilde is legal anywhere in a file name or directory name.

To preserve backward compatibility, the CRTL will continue to interpret a leading tilde (~) to mean the user's home directory. To pass an OpenVMS file name that begins with a tilde (~) to a CRTL routine that accepts Unix-style file specifications, specify the tilde preceded by the escape character (^). For example, ^~.

The following Compaq CRTL functions accept OpenVMS extended file names and require this syntax for a leading tilde (~) in the file specification:

.create
.fopen
.freopen
.open
.stat

This appendix duplicates technical information that appears in other parts of the OpenVMS documentation.

B.1 System Services Changes

This section describes the following system services:

• New services:
  • $SET_PROCESS_PROPERTIESW
  • $CVT_FILENAME
• Changed services:
  • $CREPRC
  • $GETJPI
  • $SETDDIR

The $SET_PROCESS_PROPERTIESW system service sets a simple value associated with a process.

Format

$SET_PROCESS_PROPERTIESW mbz1 ,mbz2 ,mbz3 ,property ,value, prev_value

C Prototype:

int sys$set_process_properties(
        unsigned int mbz1,
        unsigned int mbz2,
        unsigned int mbz3,
        unsigned int property,
        unsigned __int64 value,
        unsigned __int64 *prev_value);

Arguments

mbz1,mbz2,mbz3

Reserved for future use by Compaq. Must be specified as 0.

property
OpenVMS usage: integer
type:          longword (unsigned)
access:        read only
mechanism:     by value

A constant that selects which property to set.

Valid values for property are defined by the $PPROPDEF macro as shown in Table B-1.

value
OpenVMS usage: integer
type:          quadword (unsigned)
access:        read
mechanism:     by value

A quadword value to which to set the property.

prev_value
OpenVMS usage: access_mode
type:          quadword (unsigned) address of a quadword value
access:        write
mechanism:     by reference

The address of a quadword that will receive the previous value of the property.

Required Access or Privileges

None.

Required Quota

None.

Related Services

$GETJPI

Condition Values Returned

SS$NORMAL       The service completed successfully.
SS$ACCVIO       Access violation.

Converts a string from RMS format to file-system (ACP-QIO) format or from file-system (ACP-QIO) format to RMS format.

Format

SYS$CVT_FILENAME cvttyp ,srcstr ,inflags ,outbuf ,outlen ,outflags

C Prototype:

int sys$cvt_filename (unsigned int cvttyp,
                      void *srcstr,
                      unsigned int inflags,
                      void *outbuf,
                      unsigned short int *outlen,
                      unsigned int *outflags);

Arguments

cvttyp
OpenVMS usage: unsigned_longword
type:          longword (unsigned)
access:        read only
mechanism:     by value

Longword value that indicates whether the conversion is to be from RMS format to ACP-QIO format or vice versa.

There are two legal values for this parameter, represented by the symbols CVTFNM$C_ACPQIO_TO_RMS and CVTFNM$C_RMS_TO_ACPQIO, which are defined by the $CVTFNMDEF macro.

srcstr
OpenVMS usage: string of bytes or words
type:          string of bytes or words
access:        read only
mechanism:     by 32-bit descriptor--fixed length string descriptor

String to be converted by the service.

If the conversion is to be from RMS format to ACP-QIO format, srcstr is an ISO Latin-1 or VTF-7-encoded character string. If the conversion is to be from ACP-QIO format to RMS format, srcstr is a string of byte-width or word-width characters.

The descriptor length field indicates the length of the input string in bytes, whether the characters are byte-width or word-width.

The srcstr argument is the 32-bit address of a descriptor that points to this string.

inflags
OpenVMS usage: mask_longword
type:          longword (unsigned)
access:        read only
mechanism:     by value

Longword flag mask indicating characteristics of the input string.

For conversion from RMS format to ACP-QIO format, only the CVTFNM$V_NO_DELIMITERS flag is valid.

For conversion from ACP-QIO format to RMS format, legal flags are CVTFNM$V_WORD_CHARS and CVTFNM$V_NO_DELIMITERS (defined by the $CVTFNMDEF macro). The flag descriptions are shown in Table B-2.

outbuf
OpenVMS usage: string of bytes or words
type:          string of bytes or words
access:        write only
mechanism:     by 32-bit descriptor--fixed-length string descriptor

The buffer into which the converted string is to be written.

If the conversion is from RMS format to ACP-QIO format, the string may consist of byte-width ISO Latin-1 characters or word-width UCS-2 characters, depending upon the characters in the source string. (If any character in the source string requires a word to represent, then all characters in the output buffer will be of word width.)

If the conversion is from ACP-QIO format to RMS format, then the output string will consist of ISO Latin-1 and VTF-7 characters, in RMS canonical form. (Refer to the Guide to OpenVMS File Applications.)

For ACPQIO_TO_RMS conversion, if the output string is composed of word-width characters, the CVTFNM$V_WORD_CHARS flag in the outflags flag mask will be set.

The outbuf argument is the 32-bit address of a descriptor pointing to a buffer writable in the mode of the caller.

outlen
OpenVMS usage: word_unsigned
type:          word (unsigned)
access:        write only
mechanism:     by 32-bit reference

The outlen argument is the 32-bit address of a (16-bit) word writable in the mode of the caller.

outflags
OpenVMS usage: mask_longword
type:          longword (unsigned)
access:        write only
mechanism:     by 32-bit reference

Longword flag mask in which the service sets or clears flags to indicate characteristics of the output string.

For an RMS_TO_ACPQIO conversion, SYS$CVT_FILENAME sets the bit corresponding to CVTFNM$V_WORD_CHARS (defined by the $CVTFNMDEF macro) if the characters of the converted string are one word (rather than one byte) wide. If the characters of the converted string are one byte wide, the service clears the CVTFNM$V_WORD_CHARS bit. All other bits are cleared by an RMS_TO_ACPQIO conversion.

The outflags argument is the 32-bit address of a 32-bit flag mask writable in the mode of the caller.

Description

This service is intended to provide conversion of a filename(1) or of a subdirectory name(2) between the RMS format (as seen at the RMS interface) and ACP-QIO format (as stored on-disk). Prior to Version 7.2, these representations were the same. This is not necessarily the case for extended (ODS-5) filenames. (Refer to the Guide to OpenVMS File Applications for details on ODS-5 file specifications.)

1. A filename consists of a file name, a file type, and a file version.
2. A subdirectory name is a string to which ".DIR;1" may be appended to form a directory file name, as stored on-disk.

Depending upon the value of cvttyp, the service will perform conversion of a string from RMS format to ACP-QIO format or from ACP-QIO format to RMS format.

The source string is described by the argument srcstr, the output buffer is described by the argument outbuf, and the resultant string length is written to the argument outlen.

If any of the source string falls within the address range of the output buffer, the output string is unpredictable.

RMS-to-ACPQIO Conversion:

A string described by the srcstr descriptor argument is converted to an ISO Latin-1 or UCS-2 string with each character represented in a form that can be passed to the ACP-QIO via the $QIO service.

If the CVTFNM$V_NO_DELIMITERS input flag is clear, the source string will be scanned, and, if necessary, a dot and a semicolon will be inserted or appended as though a $PARSE were done with no default name, type, or version fields supplied. If the scan detects any delimiters indicating the presence of fields other than name (without FID), type, or version, a syntax error will be returned.

If the CVTFNM$V_NO_DELIMITERS input flag is set, individual characters will be validated and converted to their on-disk form. However, no scan is done to determine if type and version delimiters are present, and no delimiters are added.

A percent sign (%) that is not preceded by the escape character (^) is converted to a question mark. An ISO Latin-1 character that is preceded by the escape character (^) is converted to the corresponding ISO Latin-1 character. A VTF-7 character (for example, ^U1234) that is preceded by the escape character (^) is converted to a UCS-2 character (for example, 0x1234).

If any character requires UCS-2 (word-width character) representation, all characters are represented in the output string with UCS-2. If no character requires word-width character representation, all characters are represented in the output string with ISO Latin-1 (byte-width) characters.

Valid characters are those that are legal in an RMS filename (file name, file type, and file version) or in an RMS subdirectory name. For example, directory delimiters "[" and "]" are not legal, unless preceded by the escape character (^).

ACPQIO-to-RMS Conversion:

The string described by the srcstr descriptor argument is converted to the RMS canonical form for that string.

If the CVTFNM$V_NO_DELIMITERS input flag is clear, the source string must contain at least one semicolon, and, to the left of the semicolon, at least one dot. If it does not, RMS$_SYN (syntax error) is returned. In the output string, all dots and semicolons other than those two are preceded by the RMS escape character (^).

If the CVTFNM$V_NO_DELIMITERS input flag is set, any dot or semicolon encountered is preceded in the output string by the RMS escape character (^).

The CVTFNM$V_WORD_CHARS flag of the inflags argument indicates whether the input string is to be interpreted as having byte-width (ISO Latin-1) or word-width (UCS-2) characters. If the argument indicates word-width characters, but the input length value is an odd number, a syntax error is returned.

Question marks are converted to percent signs; percent signs are preceded by the escape character (^). UCS-2 characters are converted to VTF-7 characters. All characters will be represented in RMS canonical form.

Required Access or Privileges

None.

Required Quota

None.

Related Services

None.

Condition Values Returned

SS$NORMAL           The service completed successfully.
SS$_BADPARAM        Unrecognized conversion type, extraneous input
                    flags set, or zero-length input string.
SS$_INSFARG         Not enough arguments provided.
SS$_TOO_MANY_ARGS   Too many arguments provided.
RMS$_SYN            The service could not translate one or more
                    characters in the strings described by the
                    srcstr argument, the input string has word-width
                    characters but odd byte-length (ACPQIO_TO_RMS
                    only), or the CVTFNM$V_NO_DELIMITERS input flag
                    was clear and the input string did not contain
                    both type and version delimiters.
SS$_BUFFEROVF       The output buffer was not large enough
                    to accommodate the converted string.