HP OpenVMS Systems Documentation

OpenVMS Utility Routines Manual

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.

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.

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.