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

    The SOR$DTYPE routine defines a key data type that is not
    normally supported by SORT/MERGE. (This routine is not currently
    supported by the high-performance Sort/Merge utility.) This
    routine returns a key data type code that can be used in the key_
    buffer argument to SOR$BEGIN_SORT or SOR$BEGIN_MERGE to describe
    special key data types (such as extended data types and National
    character set (NCS) collating sequences).

    Format

      SOR$DTYPE  [context] ,dtype_code ,usage ,p1

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

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       modify
    mechanism:    by reference
    Value that distinguishes between multiple, concurrent SORT/MERGE
    operations. The context argument is the address of a longword
    containing the context value. When your program makes its first
    call to a SORT/MERGE routine for a particular sort or merge
    operation, the context longword must equal zero. SORT/MERGE
    then stores a value in the longword to identify the operation
    just initiated. When you make subsequent routine calls for the
    same operation, you must pass the context value supplied by
    SORT/MERGE.

 dtype_code

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       write only
    mechanism:    by reference
    Returned key data type code. The dtype_code argument is the
    address of a word into which SORT/MERGE writes the key data type
    code that can be used in the key_buffer argument to SOR$BEGIN_
    SORT or SOR$BEGIN_MERGE.

 usage

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of a longword containing a code that indicates the
    interpretation of the p1 argument. The following table lists
    and describes the valid usage codes:

    Flag             Description

    SOR$K_ROUTINE    The p1 argument should be interpreted as the
                     address of the procedure value of a routine
                     that SORT/MERGE will call to compare keys
                     described by the dtype_code returned by the
                     call to SOR$DTYPE.
    SOR$K_NCS_TABLE  The p1 argument should be interpreted as the
                     address of a collating sequence identification
                     returned by a call to NCS$GET_CS. SORT/MERGE
                     will use this collating sequence to compare keys
                     described by the dtype_code returned by the call
                     to SOR$DTYPE.

    If SOR$K_ROUTINE is returned, SORT/MERGE will call this routine
    with five reference arguments-ADRS1, ADRS2, LENG1, LENG2, CNTX-
    corresponding to the addresses of the two keys to be compared,
    the lengths of the two keys, and the context longword.

    The comparison routine must return a 32-bit integer value:

    o  -1 if the first key collates before the second

    o  0 if the keys collate as equal

    o  +1 if the first key collates after the second

 p1

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Address of the procedure value of a routine or the address of
    a collating sequence identification, depending on the usage
    argument.

3 - Description

    Call SOR$DTYPE to define a key data type not normally supported
    by SORT/MERGE.

    If your SORT/MERGE application needs to compare dates (for
    example) that are stored in text form and that is the only key
    in the records, then use the user_compare argument to SOR$BEGIN_
    SORT or SOR$BEGIN_MERGE. However, if the records contain several
    keys besides the dates in text form, it may be easier to call
    SOR$DTYPE to allocate a key data type code that can then be used
    in the the key_buffer argument to SOR$BEGIN_SORT or SOR$BEGIN_
    MERGE.

    If your SORT/MERGE application has a string key that should be
    collated by a collating sequence defined by the NCS utility, the
    NCS$GET_CS routine can be used to fetch the collating sequence
    definition, and SOR$DTYPE can be called to allocate a key data
    type code for the collating sequence. This key data type code
    can then be used to describe keys that should be compared by this
    collating sequence.

4 - Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    SOR$_NYI           Not yet implemented.
    SOR$_SORT_ON       Sort or merge routine called in incorrect
                       order.