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(1) Octaword integer (signed)
DSC$K_DTYPE_OU(1) 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(1) H-format floating
DSC$K_DTYPE_FS(2) IEEE single-precision S floating
DSC$K_DTYPE_FT(2) 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(1) Numeric string, zoned sign
DSC$K_DTYPE_P Packed decimal string
Footnotes:
1. Data type is not currently supported by the high-performance
Sort/Merge utility.
2. Data type is Alpha specific.
The VSI OpenVMS Programming Concepts 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).
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.