/sys$common/syshlp/helplib.hlb SOR Routines, SOR$BEGIN_MERGE, Arguments  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 key_buffer

    OpenVMS usage:vector_word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference
    Array of words describing the keys on which you plan to merge.
    The key_buffer argument is the address of an array containing the
    key descriptions.

    The first word of this array contains the number of keys
    described (up to 255). Following the first word, each key is
    described (in order of priority) in blocks of four words. The
    four words specify the key's data type, order, offset, and
    length, respectively.

    The first word of the block specifies the key's data type. The
    following data types are accepted:

    DSC$K_DTYPE_Z     Unspecified (uninfluenced by collating
                      sequence)
    DSC$K_DTYPE_B     Byte integer (signed)
    DSC$K_DTYPE_BU    Byte (unsigned)
    DSC$K_DTYPE_W     Word integer (signed)
    DSC$K_DTYPE_WU    Word (unsigned)
    DSC$K_DTYPE_L     Longword integer (signed)
    DSC$K_DTYPE_LU    Longword (unsigned)
    DSC$K_DTYPE_Q     Quadword integer (signed)
    DSC$K_DTYPE_QU    Quadword (unsigned)
    DSC$K_DTYPE_O     Octaword integer (signed)
    DSC$K_DTYPE_OU    Octaword (unsigned)
    DSC$K_DTYPE_F     Single-precision floating
    DSC$K_DTYPE_D     Double-precision floating
    DSC$K_DTYPE_G     G-format floating
    DSC$K_DTYPE_H     H-format floating
    DSC$K_DTYPE_FS    IEEE single-precision S floating
    DSC$K_DTYPE_FT    IEEE double-precision T floating
    DSC$K_DTYPE_T     Text (may be influenced by collating sequence)
    DSC$K_DTYPE_NU    Numeric string, unsigned
    DSC$K_DTYPE_NL    Numeric string, left separate sign
    DSC$K_DTYPE_NLO   Numeric string, left overpunched sign
    DSC$K_DTYPE_NR    Numeric string, right separate sign
    DSC$K_DTYPE_NRO   Numeric string, right overpunched sign
    DSC$K_DTYPE_NZ    Numeric string, zoned sign
    DSC$K_DTYPE_P     Packed decimal string

    The OpenVMS Programming Interfaces: Calling a System Routine
    manual describes each of these data types.

    The second word of the block specifies the key order: 0 for
    ascending order, 1 for descending order. The third word of the
    block specifies the relative offset of the key in the record.
    (Note that the first byte in the record is at position 0.) The
    fourth word of the block specifies the key length in bytes (in
    digits for packed decimal-DSC$K_DTYPE_P).

    If you do not specify the key_buffer argument, you must pass
    either a key comparison routine or use a specification file to
    define the key.

 lrl

    OpenVMS usage:word_unsigned
    type:         word (unsigned)
    access:       read only
    mechanism:    by reference
    Length of the longest record that will be released for merging.
    The lrl (longest record length) argument is the address of a
    word containing the length. If the input file is on a disk,
    this argument is not required. It is required when you use the
    record interface. For Vertical Format Control (VFC) records, this
    length must include the length of the fixed-length portion of the
    record.

 options

    OpenVMS usage:mask_longword
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Flags that identify merge options. The options argument is the
    address of a longword bit mask whose settings determine the merge
    options selected.

    The following table lists and describes the bit mask values
    available:

    Flag            Description

    SOR$M_STABLE    Keeps records with equal keys in the same order
                    as they appeared on input.
    SOR$M_EBCDIC    Orders ASCII character keys according to EBCDIC
                    collating sequence. No translation takes place.
    SOR$M_MULTI     Orders character keys according to the
                    multinational collating sequence, which collates
                    the international character set.
    SOR$M_          Returns a status code instead of signaling
    NOSIGNAL        errors.
    SOR$M_NODUPS    Omits records with duplicate keys. You cannot
                    use this option if you specify your own equal-key
                    routine.
    SOR$M_SEQ_      Requests an "out of order" error return if
    CHECK           an input file is not already in sequence. By
                    default, this check is not done. You must request
                    sequence checking if you specify an equal-key
                    routine.

    All other bits in the longword are reserved and must be zero.

 merge_order

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference
    Number of input streams to be merged. The merge_order argument is
    the address of a byte containing the number of files (1 through
    10) to be merged. (The high-performance Sort/Merge utility allows
    you to specify 1 through 12 files.) When you use the record
    interface on input, this argument is required.

 user_compare

    OpenVMS usage:procedure
    type:         procedure value
    access:       function call
    mechanism:    by reference
    Routine that compares records to determine their merge order.
    (This routine is not currently supported by the high-performance
    Sort/Merge utility.) The user_compare argument is the address of
    the procedure value for this user-written routine. If you do not
    specify the key_buffer argument or if you define key information
    in a specification file, this argument is required.

    MERGE calls the comparison routine with five reference arguments-
    ADRS1, ADRS2, LENG1, LENG2, CNTX-corresponding to the addresses
    of the two records to be compared, the lengths of these two
    records, and the context longword.

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

    o  -1 if the first record collates before the second

    o  0 if the records collate as equal

    o  1 if the first record collates after the second

 user_equal

    OpenVMS usage:procedure
    type:         procedure value
    access:       function call
    mechanism:    by reference
    Routine that resolves the merge order when records have duplicate
    keys. (This routine is not currently supported by the high-
    performance Sort/Merge utility.) The user_equal argument is the
    address of the procedure value for this user-written routine. If
    you specify SOR$M_STABLE or SOR$M_NODUPS in the options argument,
    do not use this argument.

    MERGE calls the duplicate key routine with five reference
    arguments-ADRS1, ADRS2, LENG1, LENG2, CNTX-corresponding to the
    addresses of the two records that compare equally, the lengths of
    the two records that compare equally, and the context longword.

    The routine must return one of the following 32-bit condition
    codes:

    Code         Description

    SOR$_        Delete the first record from the merge.
    DELETE1
    SOR$_        Delete the second record from the merge.
    DELETE2
    SOR$_        Delete both records from the merge.
    DELBOTH
    SS$_NORMAL   Keep both records in the merge.

    Any other failure value causes the error to be signaled or
    returned. Any other success value causes an undefined result.

 user_input

    OpenVMS usage:procedure
    type:         procedure value
    access:       function call
    mechanism:    by reference
    Routine that releases records to the merge operation. The user_
    input argument is the address of the procedure value for this
    user-written routine. SOR$BEGIN_MERGE and SOR$RETURN_REC call
    this routine until all records have been passed.

    This input routine must read (or construct) a record, place it in
    a record buffer, store its length in an output argument, and then
    return control to MERGE.

    The input routine must accept the following four arguments:

    o  A descriptor of the buffer where the routine must place the
       record

    o  A longword, passed by reference, containing the stream number
       from which to input a record (the first file is 1, the second
       2, and so on)

    o  A word, passed by reference, where the routine must return the
       actual length of the record

    o  The context longword, passed by reference

    The input routine must also return one of the following status
    values:

    o  SS$_NORMAL or any other success status causes the merge
       operation to continue.

    o  SS$_ENDOFFILE indicates that no more records are in the file.
       The contents of the buffer are ignored.

    o  Any other error status terminates the merge operation and
       passes the status value back to the caller of SOR$BEGIN_MERGE
       or SOR$RETURN_REC.

 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 that was supplied by
    SORT/MERGE.