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

    The SOR$BEGIN_SORT routine initializes a sort operation by
    opening input and output files and by passing the key information
    and any sort options.

    Format

      SOR$BEGIN_SORT  [key_buffer] [,lrl] [,options] [,file_alloc]

                      [,user_compare] [,user_equal] [,sort_process]

                      [,work_files] [,context]

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

 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 sort. 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 data type of the key.
    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
    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).

    The key_buffer argument specifies the address of the key buffer
    in the data area. If you do not specify this argument, you must
    either pass 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 sorting.
    The lrl argument is the address of a word containing the length.
    This argument is not required if the input files are on disk but
    is required when you use the record interface. For 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 sort 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.

    Flags          Description

    SOR$M_STABLE   Keeps records with equal keys in the same order in
                   which they appeared on input. With multiple input
                   files that have records that collate as equal,
                   records from the first input file are placed
                   before the records from the second input file,
                   and so on.
    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 errors.
    NOSIGNAL
    SOR$M_NODUPS   Omits records with duplicate keys. You cannot
                   use this option if you specify your own equal-key
                   routine.

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

 file_alloc

    OpenVMS usage:longword_unsigned
    type:         longword (unsigned)
    access:       read only
    mechanism:    by reference
    Input file size in blocks. The file_alloc argument is the
    address of a longword containing the size of the input file.
    This argument is optional because, by default, SORT uses the
    allocation of the input files. If you are using the record
    interface, or if the input files are not on disk, the default is
    1000 blocks.(The high-performance Sort/Merge utility determines
    the default based on the size of the input file, or if input is
    not from files, on available memory.) When you specify the input
    size with this argument, it overrides the default size.

    This optional argument is useful when you are using the record
    interface and you have a good idea of the total input size. You
    can use this argument to improve the efficiency of the sort by
    adjusting the amount of resources the sort process allocates to
    match the input size.

 user_compare

    OpenVMS usage:procedure
    type:         procedure value
    access:       function call
    mechanism:    by reference
    User-written routine that compares records to determine their
    sort order. (This argument 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.

    SORT/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 LENG1 and LENG2
    arguments are addresses that point to 16-bit word structures that
    contain the length information.

    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
    User-written routine that resolves the sort order when records
    have duplicate keys. (This argument 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.

    SORT/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 LENG1 and LENG2 arguments are addresses that point to 16-bit
    word structures that contain the length information.

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

    Code         Description

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

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

 sort_process

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference
    Code indicating the type of sort process. The sort_process
    argument is the address of a byte whose value indicates whether
    the sort type is record, tag, index, or address. (The high-
    performance Sort/Merge utility supports only the record process.
    Implementation of the tag, address, and index processes is
    deferred to a future OpenVMS Alpha release.) The default is
    record. If you select the record interface on input, you can
    use only a record sort process.

    To specify a byte containing the value for the type of sort
    process you want, enter one of the following:

    o  SOR$GK_RECORD (record sort)

    o  SOR$GK_TAG (tag sort)

    o  SOR$GK_ADDRESS (address sort)

    o  SOR$GK_INDEX (index sort)

 work_files

    OpenVMS usage:byte_unsigned
    type:         byte (unsigned)
    access:       read only
    mechanism:    by reference
    Number of work files to be used in the sorting process. The work_
    files argument is the address of a byte containing the number of
    work files; permissible values for SORT range from 0 through 10.
    (For the high-performance Sort/Merge utility, you can specify
    from 1 through 255 work files. The default is 2.)

    By default, SORT creates two temporary work files when it needs
    them and determines their size from the size of your input files.
    By increasing the number of work files, you can reduce their
    individual size so that each fits into less disk space. You can
    also assign each of them to different disk-structured devices
    (highly recommended).

 context

    OpenVMS usage:context
    type:         longword (unsigned)
    access:       write only
    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.

3 - Description

    The SOR$BEGIN_SORT routine initializes the sort process by
    setting up sort work areas and provides key specification and
    sort options.

    Specify the key information with the key_buffer argument, with
    the user_compare argument, or in a specification file. If no key
    information is specified, the default (character for the entire
    record) is used.

    You must use the SOR$BEGIN_SORT routine to initialize the sort
    process for the file, record, and mixed interfaces. For record
    interface on input, you must use the lrl (longest record length)
    argument.

    Some of the following condition values are used with different
    severities, depending on whether SORT/MERGE can recover. Thus,
    if you want to check for a specific status, you should use
    LIB$MATCH_COND.

4 - Condition Values Returned

    SS$_NORMAL         Normal successful completion.
    SOR$_BADLOGIC      Internal logic error detected.
    SOR$_BAD_KEY       Invalid key specification.
    SOR$_BAD_LRL       Record length n greater than specified longest
                       record length.
    SOR$_BAD_MERGE     Number of work files must be between 0 and 10.
                       (For the high-performance Sort/Merge utility,
                       the maximum number is 255.)
    SOR$_BAD_TYPE      Invalid sort process specified.
    SOR$_ENDDIAGS      Completed with diagnostics.
    SOR$_INSVIRMEM     Insufficient virtual memory.
    SOR$_KEYAMBINC     Key specification is ambiguous or
                       inconsistent.
    SOR$_KEY_LEN       Invalid key length, key number n, length n.
    SOR$_LRL_MISS      Longest record length must be specified.
    SOR$_NODUPEXC      Equal-key routine and no-duplicates option
                       cannot both be specified.
    SOR$_NUM_KEY       Too many keys specified.
    SOR$_NYI           Not yet implemented.
    SOR$_RTNERROR      Unexpected error status from user-written
                       routine.
    SOR$_SORT_ON       Sort or merge routine called in incorrect
                       order.
    SOR$_STABLEEXC     Equal-key routine and stable option cannot
                       both be specified.
    SOR$_SYSERROR      System service error.
    SOR$_UNDOPTION     Undefined option flag was set.