type: longword (unsigned) access: read only mechanism: by reference Address of the procedure value of a routine or the address of a collating sequence identification, depending on the usage argument. 3 Description Call SOR$DTYPE to define a key data type not normally supported by SORT/MERGE. If your SORT/MERGE application needs to compare dates (for example) that are stored in text form and that is the only key in the records, then use the user_compare argument to SOR$BEGIN_ SORT or SOR$BEGIN_MERGE. However, if the records contain several keys besides the dates in text form, it may be easier to call SOR$DTYPE to allocate a key data type code that can then be used in the the key_buffer argument to SOR$BEGIN_SORT or SOR$BEGIN_ MERGE. If your SORT/MERGE application has a string key that should be collated by a collating sequence defined by the NCS utility, the NCS$GET_CS routine can be used to fetch the collating sequence definition, and SOR$DTYPE can be called to allocate a key data type code for the collating sequence. This key data type code can then be used to describe keys that should be compared by this collating sequence. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. SOR$_NYI Not yet implemented. SOR$_SORT_ON Sort or merge routine called in incorrect order. 2 SOR$END_SORT The SOR$END_SORT routine performs cleanup functions, such as closing files and releasing memory. Format SOR$END_SORT [context] 3 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. 3 Argument context OpenVMS usage:context type: longword 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$END_SORT routine ends a sort or merge operation, either at the end of a successful process or between calls because of an error. If an error status is returned, you must call SOR$END_SORT to release all allocated resources. In addition, this routine can be called at any time to close files and release memory. The value of the optional context argument is cleared when the SOR$END_SORT routine completes its operation. 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. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. SOR$_CLOSEIN Error closing file as input. SOR$_CLOSEOUT Error closing file as output. SOR$_ENDDIAGS Completed with diagnostics. SOR$_END_SORT SORT/MERGE terminated, context = context. SOR$_SYSERROR System service error. 2 SOR$PASS_FILES The SOR$PASS_FILES routine passes the names of input and output files and output file characteristics to SORT or MERGE. Format SOR$PASS_FILES [inp_desc] [,out_desc] [,org] [,rfm] [,bks] [,bls] [,mrs] [,alq] [,fop] [,fsz] [,context] 3 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. 3 Arguments inp_desc OpenVMS usage:char_string type: character-coded text string access: read only mechanism: by descriptor Input file specification. The inp_desc argument is the address of a descriptor pointing to the file specification. In the file interface, you must call SOR$PASS_FILES to pass SORT the input file specifications. For multiple input files, call SOR$PASS_FILES once for each input file, passing one input file specification descriptor each time. In the mixed interface, if you are using the record interface on input, pass only the output file specification; do not pass any input file specifications. If you are using the record interface on output, pass only the input file specifications; do not pass an output file specification or any of the optional output file arguments. out_desc OpenVMS usage:char_string type: character-coded text string access: read only mechanism: by descriptor Output file specification. The out_desc argument is the address of a descriptor pointing to the file specification. In the file interface, when you call SOR$PASS_FILES, you must pass the output file specification. Specify the output file specification and characteristics only once, as part of the first call, as in the following: Call SOR$PASS_FILES(Input1,Output) Call SOR$PASS_FILES(Input2) Call SOR$PASS_FILES(Input3) In the mixed interface, if you are using the record interface on input, pass only the output file specification; do not pass any input file specifications. If you are using the record interface on output, pass only the input file specifications; do not pass an output file specification or any of the optional output file arguments. org OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference File organization of the output file, if different from the input file. The org argument is the address of a byte whose value specifies the organization of the output file; permissible values include the following: FAB$C_SEQ FAB$C_REL FAB$C_IDX For the record interface on input, the default value is sequential. For the file interface, the default value is the file organization of the first input file for record or tag sort and sequential for address and index sort. For more information about OpenVMS RMS file organizations, see the OpenVMS Record Management Services Reference Manual. rfm OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference Record format of the output file, if different from the input file. The rfm argument is the address of a byte whose value specifies the record format of the output file; permissible values include the following: FAB$C_FIX FAB$C_VAR FAB$C_VFC For the record interface on input, the default value is variable. For the file interface, the default value is the record format of the first input file for record or tag sort and fixed format for address or index sort. For the mixed interface with record interface on input, the default value is variable format. For more information about OpenVMS RMS record formats, see the OpenVMS Record Management Services Reference Manual. bks OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference Bucket size of the output file, if different from the first input file. The bks argument is the address of a byte containing this size. Use this argument with relative and indexed-sequential files only. If the bucket size of the output file is to differ from that of the first input file, specify a byte to indicate the bucket size. Acceptable values are from 1 to 32. If you do not pass this argument-and the output file organization is the same as that of the first input file-the bucket size defaults to the value of the first input file. If the file organizations differ or if the record interface is used on input, the default value is 1 block. bls OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Block size of a magnetic tape output file. The bls argument is the address of a word containing this size. Use this argument with magnetic tapes only. Permissible values range from 20 to 65,532. However, to ensure compatibility with non-VMS systems, ANSI standards require that the block size be less than or equal to 2048. The block size defaults to the block size of the input file magnetic tape. If the input file is not on magnetic tape, the output file block size defaults to the size used when the magnetic tape was mounted. mrs OpenVMS usage:word_unsigned type: word (unsigned) access: read only mechanism: by reference Maximum record size for the output file. The mrs argument is the address of a word specifying this size. Following are acceptable values for each type of file: File Organization Acceptable Value Sequential 0 to 32,767 Relative 0 to 16,383 Indexed 0 to 16,362 sequential If you omit this argument or if you specify a value of 0, SORT does not check maximum record size. If you do not specify this argument, the default is based on the output file organization and format, unless the organization is relative or the format is fixed. The longest output record length is based on the longest calculated input record length, the type of sort, and the record format. alq OpenVMS usage:longword_unsigned type: longword (unsigned) access: read only mechanism: by reference Number of preallocated output file blocks. The alq argument is the address of a longword specifying the number of blocks you want to preallocate to the output file. Acceptable values range from 1 to 4,294,967,295. Pass this argument if you know your output file allocation will be larger or smaller than that of your input files. The default value is the total allocation of all the input files. If the allocation cannot be obtained for any of the input files or if the record interface is used on input, the file allocation defaults to 1000 blocks. fop OpenVMS usage:mask_longword type: longword (unsigned) access: read only mechanism: by reference File-handling options. The fop argument is the address of a longword whose bit settings determine the options selected. For a list of valid file-handling options, see the description of the FAB$L_FOP field in the OpenVMS Record Management Services Reference Manual. By default, only the DFW (deferred write) option is set. If your output file is indexed, you should set the CIF (create if) option. fsz OpenVMS usage:byte_unsigned type: byte (unsigned) access: read only mechanism: by reference Size of the fixed portion of VFC records. The fsz argument is the address of a byte containing this size. If you do not pass this argument, the default is the size of the fixed portion of the first input file. If you specify the VFC size as 0, RMS defaults the value to 2 bytes. 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$PASS_FILES routine passes input and output file specifications to SORT. The SOR$PASS_FILES routine must be repeated for multiple input files. The output file name string and characteristics should be specified only in the first call to SOR$PASS_FILES. This routine also accepts optional arguments that specify characteristics for the output file. By default, the output file characteristics are the same as the first input file; specified output file characteristics are used to change these defaults. 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. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. SOR$_DUP_OUTPUT Output file has already been specified. SOR$_ENDDIAGS Completed with diagnostics. SOR$_INP_FILES Too many input files specified. SOR$_NYI Not yet implemented. SOR$_SORT_ON Sort or merge routine called in incorrect order. SOR$_SYSERROR System service error. 2 SOR$RELEASE_REC The SOR$RELEASE_REC routine is used with the record interface to pass one input record to SORT or MERGE. Format SOR$RELEASE_REC desc [,context] 3 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. 3 Arguments desc OpenVMS usage:char_string type: character-coded text string access: read only mechanism: by descriptor Input record buffer. The desc argument is the address of a descriptor pointing to the buffer containing the record to be sorted. If you use the record interface, this argument is required. context OpenVMS usage:context type: longword 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$RELEASE_REC to pass records to SORT or MERGE with the record interface. SOR$RELEASE_REC must be called once for each record to be sorted. 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. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. SOR$_BADLOGIC Internal logic error detected. SOR$_BAD_LRL Record length n greater than longest specified record length. SOR$_BAD_SRL Record length n too short to contain keys. SOR$_ENDDIAGS Completed with diagnostics. SOR$_EXTEND Unable to extend work file for needed space. SOR$_MISS_PARAM The desc argument is missing. SOR$_NO_WRK Work files required; cannot do sort in memory as requested. 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$_SORT_ON Sort or merge routines called in incorrect order. SOR$_SYSERROR System service error. SOR$_USE_ALT Using alternate file name. SOR$_WORK_DEV Work file name must be on random access local device. 2 SOR$RETURN_REC The SOR$RETURN_REC routine is used with the record interface to return one sorted or merged record to a program. Format SOR$RETURN_REC desc [,length] [,context] 3 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. 3 Arguments desc OpenVMS usage:char_string type: character-coded text string access: write only mechanism: by descriptor Output record buffer. The desc argument is the address of a descriptor pointing to the buffer that receives the sorted or merged record. length OpenVMS usage:word_unsigned type: word (unsigned) access: write only mechanism: by reference Length of the output record. The length argument is the address of a word receiving the length of the record returned from SORT/MERGE. 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 the SOR$RETURN_REC routine to release the sorted or merged records to a program. Call this routine once for each record to be returned. SOR$RETURN_REC places the record into a record buffer that you set up in the program's data area. After SORT has successfully returned all the records to the program, it returns the status code SS$_ENDOFFILE, which indicates that there are no more records to return. 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. 3 Condition_Values_Returned SS$_NORMAL Normal successful completion. SOR$_BADLOGIC Internal logic error detected. SOR$_ENDDIAGS Completed with diagnostics. SOR$_EXTEND Unable to extend work file for needed space. SOR$_MISS_PARAM A required subroutine argument is missing. SOR$_OPERFAIL Error requesting operator service. SOR$_READERR Error reading file. SOR$_REQ_ALT Specify alternate name file (or specify nothing to simply try again). SOR$_RTNERROR Unexpected error status from user-written routine. SOR$_SORT_ON Sort or merge routines called in incorrect order. SOR$_SYSERROR System service error. SOR$_USE_ALT Using alternate file name. SOR$_WORK_DEV Work file name must be on random access local device. 2 SOR$SORT_MERGE The SOR$SORT_MERGE routine sorts the input records. Format SOR$SORT_MERGE [context] 3 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. 3 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. 3 Description 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. 3 Condition_Values_Returned 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. 2 SOR$SPEC_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.) Format SOR$SPEC_FILE [spec_file] [,spec_buffer] [,context] 3 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. 3 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. 3 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. 2 SOR$STAT The SOR$STAT routine returns one statistic about the sort or merge operation to the user program. Format SOR$STAT code ,result [,context] 3 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. 3 Arguments 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_ Maximum merge order ORDER SOR$K_MRG_ Number of merge passes 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. 3 Description 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. 3 Condition_Values_Returned 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.