HP OpenVMS Systems Documentation
OpenVMS Guide to Extended File Specifications
A.2 ODS-2 and ODS-5 Used Together
The following notes discuss issues related to using ODS-2 and ODS-5 together in a cluster.
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 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.
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:
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.3 Architecture-Related Notes
The following notes discuss Extended File Specifications issues related to system architecture.
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:
For example, following are listings of the same directory as they appear on Alpha and VAX systems:
In addition, the directory depth on a VAX is limited to 8 (or 16, using
The following topic describes a restriction when using extended file names.
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:
int sys$set_process_properties( unsigned int mbz1, unsigned int mbz2, unsigned int mbz3, unsigned int property, unsigned __int64 value, unsigned __int64 *prev_value);
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.
|PPROP$C_PARSE_STYLE_TEMP:||The type of command parsing to use. This value will be set only for the life of the image. The value will revert to the permanent style on image rundown. Valid values are: PARSE_STYLE$C_TRADITIONAL and PARSE_STYLE$C_EXTENDED.|
|PPROP$C_PARSE_STYLE_PERM:||The type of command parsing to use. This value will be set for the life of the process unless the style is set again. Valid values are: PARSE_STYLE$C_TRADITIONAL and PARSE_STYLE$C_EXTENDED.|
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.
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.
SYS$CVT_FILENAME cvttyp ,srcstr ,inflags ,outbuf ,outlen ,outflags
int sys$cvt_filename (unsigned int cvttyp, void *srcstr, unsigned int inflags, void *outbuf, unsigned short int *outlen, unsigned int *outflags);
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.
|CVTFNM$V_WORD_CHARS||Input source string contains word-width UCS-2 characters (ACPQIO_TO_RMS).|
|CVTFNM$V_NO_DELIMITERS||Input source string should be treated as an arbitrary string (such as a subdirectory name) rather than as a filename that contains (or should contain) dots or semicolons as type and version delimiters.|
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.
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.)
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.
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 (^).
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.
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.