VMS Help NCS Routines, NCS$CONVERT  *Conan The Librarian (sorry for the slow response - running on an old VAX)

    The NCS$CONVERT routine converts a string using the specified
    conversion function.

    Format

      NCS$CONVERT  cf_id ,source ,dest [,ret_length] [,not_cvt]

1 - Returns

    OpenVMS usage:cond_value
    type:         longword (unsigned)
    access:       write only
    mechanism:    by value

    Longword condition value. Most utility routines return a
    condition value in R0. Condition values that this routine can
    return are listed under Condition Values Returned.

2 - Arguments

 cf_id

    OpenVMS usage:identifier
    type:         longword integer (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword that NCS uses to identify a conversion
    function. The cf_id argument is required and can be obtained by a
    call to the NCS$GET_CF routine.

    All calls to the NCS$CONVERT routine and the call to the NCS$END_
    CF routine that terminates the conversion must pass this longword
    identifier. Upon completion, the NCS$END_CF routine releases the
    memory used to store the conversion function and sets the value
    of the longword identifier to 0.

 source

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Descriptor of source string.

 dest

    OpenVMS usage:char_string
    type:         character string
    access:       write only
    mechanism:    by descriptor
    Descriptor of destination string.

 ret_length

    OpenVMS usage:word unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Length of converted string.

 not_cvt

    OpenVMS usage:word unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Number of characters in the source string that were not fully
    converted.

3 - Description

    Using the specified conversion function, the NCS$CONVERT routine
    converts the source string and stores the result in the specified
    destination. Optionally, the calling program can request that the
    routine return the length of the converted string as well as the
    number of characters that were not fully converted.

4 - Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    NCS$_NOT_CF        Name of identifier does not refer to a
                       conversion function.
    STR$_TRU           Successful completion. However, the resultant
                       string was truncated because the storage
                       allocation for the destination string was
                       inadequate.

5 - Condition Values Signaled

    LBR messages (prefaced by an NCS message) might signal errors
    detected while the process is accessing the NCS library.
    Any value signaled by STR$COPY_DX or STR$ANALYZE_SDESC.