VMS Help System Services, $CVT FILENAME (Alpha Only)  *Conan The Librarian (sorry for the slow response - running on an old VAX)

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

1 - Arguments

 cvttyp

    OpenVMS usage:unsigned_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by value
    Longword value that indicates whether the conversion is 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, that
    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 from RMS format to ACP-QIO format, srcstr
    is an ISO-Latin-1 or VTF-7-encoded character string. If the
    conversion is 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 the 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_       Input source string contains word-width
    CHARS                UCS-2 characters (ACPQIO_TO_RMS conversion
                         only).
    CVTFNM$V_NO_         Input source string should be treated as an
    DELIMITERS           arbitrary string (such as a subdirectory
                         name) rather than as a file name that
                         contains (or should contain) dots or
                         semicolons as type and version delimiters.
    CVTFNM$V_FORCE_      Causes this system service to convert each
    UPCASE               character to uppercase. (ACPQIO_TO_RMS
                         conversion only).

 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 on the characters in the
    source string. (If any character in the source string must be
    converted to UCS-2, then all characters in the output buffer will
    be converted to UCS-2.)

    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 contains 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 access 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 access 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 wide 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 access mode of the caller.