| Previous | Contents | Index |
The SOR$SORT_MERGE routine sorts the input records.
SOR$SORT_MERGE [context]
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.
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 supplied by SORT/MERGE.
After you have passed either the file names or the records to SORT, call the SOR$SORT_MERGE routine to sort the records. For file interface on input, the input files are opened and the records are released to the sort. For the record interface on input, the record must have already been released (by calls to SOR$RELEASE_REC). For file interface on output, the output records are reformatted and directed to the output file. For the record interface on output, SOR$RETURN_REC must be called to get the sorted records.
Some of the return 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.
SS$_NORMAL Normal successful completion. 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_LRL Record length n greater than longest specified record length. 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 as output. 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$_EXTEND Unable to extend work file for needed space. 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 inconsistent with the type or length of item. SOR$_INCNODATA Include specification references no data keyword, at line n. SOR$_INCNOKEY Include specification references no keys keyword, at line n. SOR$_IND_OVR Indexed output file must already exist. SOR$_KEYED Mismatch between SORT/MERGE keys and primary file key. SOR$_LRL_MISS Longest record length must be specified. SOR$_MISLENOFF Length and offset required. SOR$_MULTIDIM Invalid multidimensional OCCURS. SOR$_NOTRECORD Node name is a name, not a record definition. SOR$_NO_WRK Work files required, cannot do sort in memory as requested. SOR$_OPENIN Error opening file as input. SOR$_OPENOUT Error opening file as output. SOR$_OPERFAIL Error requesting operator service. SOR$_READERR Error reading file. SOR$_REQ_ALT Specify alternate name file (or nothing to try again). 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. Specification file is too complex. SOR$_SYSERROR System service error. SOR$_UNSUPLEVL Unsupported core level for record name. SOR$_USE_ALT Using alternate file name. SOR$_WORK_DEV Work file name must be on random access local device. SOR$_WRITEERR Error writing file.
The SOR$SPEC_FILE routine is used to pass a specification file or specification text to a sort or merge operation. (This routine is not currently supported by the high-performance Sort/Merge utility.)
SOR$SPEC_FILE [spec_file] [,spec_buffer] [,context]
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.
spec_file
OpenVMS usage: char_string type: character-coded text string access: read-only mechanism: by descriptor
Specification file name. The spec_file argument is the address of a descriptor pointing to the name of a file that contains the text of the options requested for the sort or merge. The specification file name string and the specification file buffer arguments are mutually exclusive.spec_buffer
OpenVMS usage: char_string type: character-coded text string access: read-only mechanism: by descriptor
Specification text buffer. The spec_buffer argument is the address of a descriptor pointing to a buffer containing specification text. This text has the same format as the text within the specification file. The specification file name string and the specification file buffer arguments are mutually exclusive.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 supplied by SORT/MERGE.
Call SOR$SPEC_FILE to pass a specification file name or a buffer with specification text to a sort or merge operation. Through the use of a specification file, you can selectively omit or include particular records from the sort or merge operation and specify the reformatting of the output records. (See the Sort Utility in the OpenVMS User's Manual for a complete description of specification files.)If you call the SOR$SPEC_FILE routine, you must do so before you call any other routines. You must pass either the spec_file or spec_buffer argument, but not both.
Some of the return 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.
SOR$_ENDDIAGS Completed with diagnostics. SOR$_NYI Not yet implemented. SOR$_SORT_ON Sort or merge routine called in incorrect order. SOR$_SYSERROR System service error.
The SOR$STAT routine returns one statistic about the sort or merge operation to the user program.
SOR$STAT code ,result [,context]
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.
code
OpenVMS usage: longword_unsigned type: longword (unsigned) access: read only mechanism: by reference
SORT/MERGE statistic code. The code argument is the address of a longword containing the code that identifies the statistic you want returned in the result argument. The following table describes the values that are accepted.Note: The high-performance Sort/Merge utility currently supports only the following subset of these values: SOR$K_REC_INP, SOR$K_REC_SOR, SOR$K_REC_OUT, SOR$K_LRL_INP.
Code Description SOR$K_IDENT Address of ASCII string for version number SOR$K_REC_INP Number of records input SOR$K_REC_SOR Records sorted SOR$K_REC_OUT Records output SOR$K_LRL_INP Longest record length (LRL) for input SOR$K_LRL_INT Internal LRL SOR$K_LRL_OUT LRL for output SOR$K_NODES Nodes in sort tree SOR$K_INI_RUNS Initial dispersion runs SOR$K_MRG_ORDER Maximum merge order SOR$K_MRG_PASSES Number of merge passes SOR$K_WRK_ALQ Work file allocation SOR$K_MBC_INP Multiblock count for input SOR$K_MBC_OUT Multiblock count for output SOR$K_MBF_INP Multibuffer count for input SOR$K_MBF_OUT Multibuffer count for output Note that performance statistics (such as direct I/O, buffered I/O, and elapsed and CPU times) are not available because user-written routines may affect those values. However, they are available if you call LIB$GETJPI.
result
OpenVMS usage: longword_unsigned type: longword (unsigned) access: write only mechanism: by reference
SORT/MERGE statistic value. The result argument is the address of a longword into which SORT/MERGE writes the value of the statistic identified by the code argument.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 supplied by SORT/MERGE.
The SOR$STAT routine returns one statistic about the sort or merge operation to your program. You can call the SOR$STAT routine at any time while the sort or merge is active.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.
SOR$_ENDDIAGS Completed with diagnostics. SOR$_MISS_PARAM A required subroutine argument is missing. SOR$_NYI Functionality is not yet implemented. SOR$_SYSERROR System service error.
| Previous | Next | Contents | Index |