The SOR$BEGIN_MERGE routine initializes the merge operation by
opening the input and output files and by providing the number of
input files, the key specifications, and the merge options.
Format
SOR$BEGIN_MERGE [key-buffer] [,lrl] [,options] [,merge_order]
[,user_compare] [,user_equal] [,user_input]
[,context]
1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most Sort/Merge 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 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(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 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.
3 – Description
The SOR$BEGIN_MERGE routine initializes the merge process by
passing arguments that provide the number of input streams, the
key specifications, and any merge options.
You must define the key by passing either the key buffer address
argument or your own comparison routine address. (You can also
define the key in a specification file and call the SOR$SPEC_FILE
routine.)
The SOR$BEGIN_MERGE routine initializes the merge process in
the file, record, and mixed interfaces. For record interface
on input, you must also pass the merge order, the input routine
address, and the longest record length. For files not on disk,
you must pass the longest record length.
Some of the following condition values are used with different
severities, depending on whether SORT/MERGE can recover. Thus,
you should use LIB$MATCH_COND if you want to check for a specific
status.
4 – Condition Values Returned
SS$_NORMAL Success.
SOR$_BADDTYPE Invalid or unsupported CDD data type.
SOR$_BADLENOFF Length and offset must be multiples of 8 bits.
SOR$_BADLOGIC Internal logic error detected.
SOR$_BADOCCURS Invalid OCCURS clause.
SOR$_BADOVRLAY Invalid overlay structure.
SOR$_BADPROTCL Node is an invalid CDD object.
SOR$_BAD_KEY Invalid key specification.
SOR$_BAD_LRL Record length n greater than specified longest
record length.
SOR$_BAD_MERGE Number of input files must be between 0 and
10. (For the high-performance Sort/Merge
utility, the maximum number is 12.)
SOR$_BAD_ORDER Merge input is out of order.
SOR$_BAD_SRL Record length n is too short to contain keys.
SOR$_BAD_TYPE Invalid sort process specified.
SOR$_CDDERROR CDD error at node name.
SOR$_CLOSEIN Error closing file as input.
SOR$_CLOSEOUT Error closing file.
SOR$_COL_CHAR Invalid character definition.
SOR$_COL_CMPLX Collating sequence is too complex.
SOR$_COL_PAD Invalid pad character.
SOR$_COL_THREE Cannot define 3-byte collating values.
SOR$_ENDDIAGS Completed with diagnostics.
SOR$_ILLBASE Nondecimal base is invalid.
SOR$_ILLLITERL Record containing symbolic literals is
unsupported.
SOR$_ILLSCALE Nonzero scale invalid for floating-point data
item.
SOR$_INCDIGITS Number of digits is not consistent with the
type or length of item.
SOR$_INCNODATA Include specification references no data, at
line n.
SOR$_INCNOKEY Include specification references no keys, at
line n.
SOR$_IND_OVR Indexed output file must already exist.
SOR$_KEYAMBINC Key specification is ambiguous or
inconsistent.
SOR$_KEYED Mismatch between SORT/MERGE keys and primary
file key.
SOR$_KEY_LEN Invalid key length, key number n, length n.
SOR$_LRL_MISS Longest record length must be specified.
SOR$_MISLENOFF Length and offset required.
SOR$_MISS_PARAM A required subroutine argument is missing.
SOR$_MULTIDIM Invalid multidimensional OCCURS.
SOR$_NODUPEXC Equal-key routine and no-duplicates option
cannot both be specified.
SOR$_NOTRECORD Node name is a name, not a record definition.
SOR$_NUM_KEY Too many keys specified.
SOR$_NYI Not yet implemented.
SOR$_OPENIN Error opening file as input.
SOR$_OPENOUT Error opening file as output.
SOR$_READERR Error reading file.
SOR$_RTNERROR Unexpected error status from user-written
routine.
SOR$_SIGNCOMPQ Absolute Date and Time data type represented
in 1-second units.
SOR$_SORT_ON Sort or merge routines called in incorrect
order.
SOR$_SPCIVC Invalid collating sequence specification at
line n.
SOR$_SPCIVD Invalid data type at line n.
SOR$_SPCIVF Invalid field specification at line n.
SOR$_SPCIVI Invalid include or omit specification at line
n.
SOR$_SPCIVK Invalid key or data specification at line n.
SOR$_SPCIVP Invalid sort process at line n.
SOR$_SPCIVS Invalid specification at line n.
SOR$_SPCIVX Invalid condition specification at line n.
SOR$_SPCMIS Invalid merge specification at line n.
SOR$_SPCOVR Overridden specification at line n.
SOR$_SPCSIS Invalid sort specification at line n.
SOR$_SRTIWA Insufficient space. The specification file is
too complex.
SOR$_STABLEEX Equal-key routine and stable option cannot
both be specified.
SOR$_SYSERROR System service error.
SOR$_UNDOPTION Undefined option flag was set.
SOR$_UNSUPLEVL Unsupported core level for record name.
SOR$_WRITEERR Error writing file.