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.) Format SOR$SPEC_FILE [spec_file] [,spec_buffer] [,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
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.
3 – Description
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.
4 – Condition Values Returned
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.