HP OpenVMS Systems Documentation

Content starts here

OpenVMS Utility Routines Manual


Previous Contents Index


SOR$SORT_MERGE

The SOR$SORT_MERGE routine sorts the input records.

Format

SOR$SORT_MERGE [context]


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.


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.

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.


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.

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]


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.


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.

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.


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.

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]


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.


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_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.

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.


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.


Index Contents