[OpenVMS documentation]
[Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
Updated: 11 December 1998

OpenVMS Guide to Extended File Specifications


Previous Contents Index

  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:


    $ 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.3 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, 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 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 DEC 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 DEC CRTL functions accept OpenVMS extended file names and require this syntax for a leading tilde (~) in the file specification:


    Appendix B
    Technical Information

    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:

    B.1.1 $SET_PROCESS_PROPERTIESW System Service (Alpha Only)

    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 follows:
    Property Code Description
    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 set the property to.


    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. 
    

    B.1.2 $CVT_FILENAME System Service (Alpha Only)

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

    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. 
    

    B.1.3 $GETJPI System Service

    There are two new item codes for this system service. They are:

    JPI$_PARSE_STYLE_PERM
    JPI$_PARSE_STYLE_IMAGE

    These return the values that were set by $SET_PROCESS_PROPERTIES, that can be either PARSE_STYLE$C_TRADITIONAL or PARSE_STYLE$C_EXTENDED. Return length is one byte for each one.

    B.1.4 $CREPRC System Service

    There is a new flag allowed in the stsflg parameter:

    PRC$M_PARSE_EXPANDED

    This sets the PARSE_STYLE_PERM and the PARSE_STYLE_IMAGE properties for the new process to EXPANDED.

    B.1.5 $SETDDIR System Service

    The following text has been added to the system service description:

    On Alpha systems, the Set Default Directory service attempts to replace the default directory string with a DID if the length of the resulting default directory exceeds 255 bytes. If this happens, then in addition to the normal syntax check, the entire path to that specification, including the device, is verified and must exist for the call to succeed.


    Previous Next Contents Index

    [Site home] [Send comments] [Help with this site] [How to order documentation] [OpenVMS site] [Compaq site]
    [OpenVMS documentation]

    Copyright © Compaq Computer Corporation 1998. All rights reserved.

    Legal
    6536PRO_005.HTML