SOR Routines, SOR$BEGIN_MERGE, Arguments
*Conan The Librarian
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 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.