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

    The NCS$GET_CF routine retrieves the definition of the named
    conversion function from the NCS library.

    Format

      NCS$GET_CF  cf_id [,cfname] [,librar]

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:       modify
    mechanism:    by reference
    Address of a longword used by NCS to identify a conversion
    function. The calling program must ensure that the longword
    contains 0 before invoking the NCS$GET_CF routine because the
    routine stores a nonzero value in the longword. The nonzero value
    identifies the conversion function. All subsequent calls to the
    NCS$CONVERT routine and the call to the NCS$END_CF routine to
    terminate the conversion function pass the longword identifier.
    When it completes the conversion, the NCS$END_CF routine releases
    the memory used to store the conversion function and sets the
    value of the longword identifier to 0.

    The conversion function identifier enhances modular programming
    and permits concurrent use of multiple conversion functions
    within a program.

    The calling program should not attempt to interpret the contents
    of the longword identifier.

    The cf_id argument is required.

 cfname

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Name of the conversion function being retrieved.

 librar

    OpenVMS usage:char_string
    type:         character string
    access:       read only
    mechanism:    by descriptor
    Name of the library where the conversion function is stored.

3 - Description

    The NCS$GET_CF routine extracts the named conversion function
    from the specified NCS library.

    If the calling program omits the cfname argument, an "identity"
    conversion function padded with NUL characters (hex 0) is
    provided. The identity conversion function effectively leaves
    each character unchanged by converting each character to itself.
    For example, A becomes A, B becomes B, C becomes C, and so forth.

    If the calling program omits the librar argument, NCS accesses
    the default NCS library.

4 - Condition Values Returned

    NCS$_DIAG          Operation completed with signaled diagnostics.
    NCS$_NOT_CF        Name of identifier does not refer to a
                       conversion function.
    NCS$_NOT_FOUND     Name of identifier not found in the NCS
                       library.

5 - Condition Values Signaled

    LBR messages (prefaced by an NCS message) might signal errors
    detected while the process is accessing the NCS library.