The Sort/Merge (SOR) routines allow you to integrate a sort or
merge operation into a program application. Using these callable
routines, you can process records, sort or merge them, and then
process them again.
1 – SOR$BEGIN_MERGE
The SOR$BEGIN_MERGE routine initializes the merge operation by
opening the input and output files and by providing the number of
input files, the key specifications, and the merge options.
Format
SOR$BEGIN_MERGE [key-buffer] [,lrl] [,options] [,merge_order]
[,user_compare] [,user_equal] [,user_input]
[,context]
1.1 – Returns
OpenVMS usage:cond_value
type: longword (unsigned)
access: write only
mechanism: by value
Longword condition value. Most Sort/Merge utility routines return
a condition value in R0. Condition values that this routine can
return are listed under Condition Values Returned.
1.2 – Arguments
key_buffer
OpenVMS usage:vector_word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Array of words describing the keys on which you plan to merge.
The key_buffer argument is the address of an array containing the
key descriptions.
The first word of this array contains the number of keys
described (up to 255). Following the first word, each key is
described (in order of priority) in blocks of four words. The
four words specify the key's data type, order, offset, and
length, respectively.
The first word of the block specifies the key's data type. The
following data types are accepted:
DSC$K_DTYPE_Z Unspecified (uninfluenced by collating
sequence)
DSC$K_DTYPE_B Byte integer (signed)
DSC$K_DTYPE_BU Byte (unsigned)
DSC$K_DTYPE_W Word integer (signed)
DSC$K_DTYPE_WU Word (unsigned)
DSC$K_DTYPE_L Longword integer (signed)
DSC$K_DTYPE_LU Longword (unsigned)
DSC$K_DTYPE_Q Quadword integer (signed)
DSC$K_DTYPE_QU Quadword (unsigned)
DSC$K_DTYPE_O(1) Octaword integer (signed)
DSC$K_DTYPE_OU(1) Octaword (unsigned)
DSC$K_DTYPE_F Single-precision floating
DSC$K_DTYPE_D Double-precision floating
DSC$K_DTYPE_G G-format floating
DSC$K_DTYPE_H(1) H-format floating
DSC$K_DTYPE_FS(2) IEEE single-precision S floating
DSC$K_DTYPE_FT(2) IEEE double-precision T floating
DSC$K_DTYPE_T Text (may be influenced by collating
sequence)
DSC$K_DTYPE_NU Numeric string, unsigned
DSC$K_DTYPE_NL Numeric string, left separate sign
DSC$K_DTYPE_NLO Numeric string, left overpunched sign
DSC$K_DTYPE_NR Numeric string, right separate sign
DSC$K_DTYPE_NRO Numeric string, right overpunched sign
DSC$K_DTYPE_NZ(1) Numeric string, zoned sign
DSC$K_DTYPE_P Packed decimal string
Footnotes:
1. Data type is not currently supported by the high-performance
Sort/Merge utility.
2. Data type is Alpha specific.
The VSI OpenVMS Programming Concepts Manual manual describes each
of these data types.
The second word of the block specifies the key order: 0 for
ascending order, 1 for descending order. The third word of the
block specifies the relative offset of the key in the record.
(Note that the first byte in the record is at position 0.) The
fourth word of the block specifies the key length in bytes (in
digits for packed decimal-DSC$K_DTYPE_P).
If you do not specify the key_buffer argument, you must pass
either a key comparison routine or use a specification file to
define the key.
lrl
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Length of the longest record that will be released for merging.
The lrl (longest record length) argument is the address of a
word containing the length. If the input file is on a disk,
this argument is not required. It is required when you use the
record interface. For Vertical Format Control (VFC) records, this
length must include the length of the fixed-length portion of the
record.
options
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Flags that identify merge options. The options argument is the
address of a longword bit mask whose settings determine the merge
options selected.
The following table lists and describes the bit mask values
available:
Flag Description
SOR$M_STABLE Keeps records with equal keys in the same order
as they appeared on input.
SOR$M_EBCDIC Orders ASCII character keys according to EBCDIC
collating sequence. No translation takes place.
SOR$M_MULTI Orders character keys according to the
multinational collating sequence, which collates
the international character set.
SOR$M_ Returns a status code instead of signaling
NOSIGNAL errors.
SOR$M_NODUPS Omits records with duplicate keys. You cannot
use this option if you specify your own equal-key
routine.
SOR$M_SEQ_ Requests an "out of order" error return if
CHECK an input file is not already in sequence. By
default, this check is not done. You must request
sequence checking if you specify an equal-key
routine.
All other bits in the longword are reserved and must be zero.
merge_order
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Number of input streams to be merged. The merge_order argument is
the address of a byte containing the number of files (1 through
10) to be merged. (The high-performance Sort/Merge utility allows
you to specify 1 through 12 files.) When you use the record
interface on input, this argument is required.
user_compare
OpenVMS usage:procedure
type: procedure value
access: function call
mechanism: by reference
Routine that compares records to determine their merge order.
(This routine is not currently supported by the high-performance
Sort/Merge utility.) The user_compare argument is the address of
the procedure value for this user-written routine. If you do not
specify the key_buffer argument or if you define key information
in a specification file, this argument is required.
MERGE calls the comparison routine with five reference arguments-
ADRS1, ADRS2, LENG1, LENG2, CNTX-corresponding to the addresses
of the two records to be compared, the lengths of these two
records, and the context longword.
The comparison routine must return a 32-bit integer value:
o -1 if the first record collates before the second
o 0 if the records collate as equal
o 1 if the first record collates after the second
user_equal
OpenVMS usage:procedure
type: procedure value
access: function call
mechanism: by reference
Routine that resolves the merge order when records have duplicate
keys. (This routine is not currently supported by the high-
performance Sort/Merge utility.) The user_equal argument is the
address of the procedure value for this user-written routine. If
you specify SOR$M_STABLE or SOR$M_NODUPS in the options argument,
do not use this argument.
MERGE calls the duplicate key routine with five reference
arguments-ADRS1, ADRS2, LENG1, LENG2, CNTX-corresponding to the
addresses of the two records that compare equally, the lengths of
the two records that compare equally, and the context longword.
The routine must return one of the following 32-bit condition
codes:
Code Description
SOR$_ Delete the first record from the merge.
DELETE1
SOR$_ Delete the second record from the merge.
DELETE2
SOR$_ Delete both records from the merge.
DELBOTH
SS$_NORMAL Keep both records in the merge.
Any other failure value causes the error to be signaled or
returned. Any other success value causes an undefined result.
user_input
OpenVMS usage:procedure
type: procedure value
access: function call
mechanism: by reference
Routine that releases records to the merge operation. The user_
input argument is the address of the procedure value for this
user-written routine. SOR$BEGIN_MERGE and SOR$RETURN_REC call
this routine until all records have been passed.
This input routine must read (or construct) a record, place it in
a record buffer, store its length in an output argument, and then
return control to MERGE.
The input routine must accept the following four arguments:
o A descriptor of the buffer where the routine must place the
record
o A longword, passed by reference, containing the stream number
from which to input a record (the first file is 1, the second
2, and so on)
o A word, passed by reference, where the routine must return the
actual length of the record
o The context longword, passed by reference
The input routine must also return one of the following status
values:
o SS$_NORMAL or any other success status causes the merge
operation to continue.
o SS$_ENDOFFILE indicates that no more records are in the file.
The contents of the buffer are ignored.
o Any other error status terminates the merge operation and
passes the status value back to the caller of SOR$BEGIN_MERGE
or SOR$RETURN_REC.
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 that was supplied by
SORT/MERGE.
1.3 – Description
The SOR$BEGIN_MERGE routine initializes the merge process by
passing arguments that provide the number of input streams, the
key specifications, and any merge options.
You must define the key by passing either the key buffer address
argument or your own comparison routine address. (You can also
define the key in a specification file and call the SOR$SPEC_FILE
routine.)
The SOR$BEGIN_MERGE routine initializes the merge process in
the file, record, and mixed interfaces. For record interface
on input, you must also pass the merge order, the input routine
address, and the longest record length. For files not on disk,
you must pass the longest record length.
Some of the following condition values are used with different
severities, depending on whether SORT/MERGE can recover. Thus,
you should use LIB$MATCH_COND if you want to check for a specific
status.
1.4 – Condition Values Returned
SS$_NORMAL Success.
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_KEY Invalid key specification.
SOR$_BAD_LRL Record length n greater than specified longest
record length.
SOR$_BAD_MERGE Number of input files must be between 0 and
10. (For the high-performance Sort/Merge
utility, the maximum number is 12.)
SOR$_BAD_ORDER Merge input is out of order.
SOR$_BAD_SRL Record length n is too short to contain keys.
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.
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$_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 not consistent with the
type or length of item.
SOR$_INCNODATA Include specification references no data, at
line n.
SOR$_INCNOKEY Include specification references no keys, at
line n.
SOR$_IND_OVR Indexed output file must already exist.
SOR$_KEYAMBINC Key specification is ambiguous or
inconsistent.
SOR$_KEYED Mismatch between SORT/MERGE keys and primary
file key.
SOR$_KEY_LEN Invalid key length, key number n, length n.
SOR$_LRL_MISS Longest record length must be specified.
SOR$_MISLENOFF Length and offset required.
SOR$_MISS_PARAM A required subroutine argument is missing.
SOR$_MULTIDIM Invalid multidimensional OCCURS.
SOR$_NODUPEXC Equal-key routine and no-duplicates option
cannot both be specified.
SOR$_NOTRECORD Node name is a name, not a record definition.
SOR$_NUM_KEY Too many keys specified.
SOR$_NYI Not yet implemented.
SOR$_OPENIN Error opening file as input.
SOR$_OPENOUT Error opening file as output.
SOR$_READERR Error reading file.
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. The specification file is
too complex.
SOR$_STABLEEX Equal-key routine and stable option cannot
both be specified.
SOR$_SYSERROR System service error.
SOR$_UNDOPTION Undefined option flag was set.
SOR$_UNSUPLEVL Unsupported core level for record name.
SOR$_WRITEERR Error writing file.
2 – SOR$BEGIN_SORT
The SOR$BEGIN_SORT routine initializes a sort operation by
opening input and output files and by passing the key information
and any sort options.
Format
SOR$BEGIN_SORT [key_buffer] [,lrl] [,options] [,file_alloc]
[,user_compare] [,user_equal] [,sort_process]
[,work_files] [,context]
2.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.2 – Arguments
key_buffer
OpenVMS usage:vector_word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Array of words describing the keys on which you plan to sort. The
key_buffer argument is the address of an array containing the key
descriptions.
The first word of this array contains the number of keys
described (up to 255). Following the first word, each key is
described (in order of priority) in blocks of four words. The
four words specify the key's data type, order, offset, and
length, respectively.
The first word of the block specifies the data type of the key.
The following data types are accepted:
DSC$K_DTYPE_Z Unspecified (uninfluenced by collating
sequence)
DSC$K_DTYPE_B Byte integer (signed)
DSC$K_DTYPE_BU Byte (unsigned)
DSC$K_DTYPE_W Word integer (signed)
DSC$K_DTYPE_WU Word (unsigned)
DSC$K_DTYPE_L Longword integer (signed)
DSC$K_DTYPE_LU Longword (unsigned)
DSC$K_DTYPE_Q Quadword integer (signed)
DSC$K_DTYPE_QU Quadword (unsigned)
DSC$K_DTYPE_O(1) Octaword integer (signed)
DSC$K_DTYPE_OU(1) Octaword (unsigned)
DSC$K_DTYPE_F Single-precision floating
DSC$K_DTYPE_D Double-precision floating
DSC$K_DTYPE_G G-format floating
DSC$K_DTYPE_H(1) H-format floating
DSC$K_DTYPE_FS(2) IEEE single-precision S floating
DSC$K_DTYPE_FT(2) IEEE double-precision T floating
DSC$K_DTYPE_T Text (may be influenced by collating
sequence)
DSC$K_DTYPE_NU Numeric string, unsigned
DSC$K_DTYPE_NL Numeric string, left separate sign
DSC$K_DTYPE_NLO Numeric string, left overpunched sign
DSC$K_DTYPE_NR Numeric string, right separate sign
DSC$K_DTYPE_NRO Numeric string, right overpunched sign
DSC$K_DTYPE_NZ(1) Numeric string, zoned sign
DSC$K_DTYPE_P Packed decimal string
Footnotes:
1. Data type is not currently supported by the high-performance
Sort/Merge utility.
2. Data type is Alpha specific.
The VSI OpenVMS Programming Concepts Manual describes each of
these data types.
The second word of the block specifies the key order: 0 for
ascending order, 1 for descending order. The third word of the
block specifies the relative offset of the key in the record.
Note that the first byte in the record is at position 0. The
fourth word of the block specifies the key length in bytes (in
digits for packed decimal-DSC$K_DTYPE_P).
The key_buffer argument specifies the address of the key buffer
in the data area. If you do not specify this argument, you must
either pass a key comparison routine or use a specification file
to define the key.
lrl
OpenVMS usage:word_unsigned
type: word (unsigned)
access: read only
mechanism: by reference
Length of the longest record that will be released for sorting.
The lrl argument is the address of a word containing the length.
This argument is not required if the input files are on disk but
is required when you use the record interface. For VFC records,
this length must include the length of the fixed-length portion
of the record.
options
OpenVMS usage:mask_longword
type: longword (unsigned)
access: read only
mechanism: by reference
Flags that identify sort options. The options argument is the
address of a longword bit mask whose settings determine the merge
options selected. The following table lists and describes the bit
mask values available.
Flags Description
SOR$M_STABLE Keeps records with equal keys in the same order in
which they appeared on input. With multiple input
files that have records that collate as equal,
records from the first input file are placed
before the records from the second input file,
and so on.
SOR$M_EBCDIC Orders ASCII character keys according to EBCDIC
collating sequence. No translation takes place.
SOR$M_MULTI Orders character keys according to the
multinational collating sequence, which collates
the international character set.
SOR$M_ Returns a status code instead of signaling errors.
NOSIGNAL
SOR$M_NODUPS Omits records with duplicate keys. You cannot
use this option if you specify your own equal-key
routine.
All other bits in the longword are reserved and must be zero.
file_alloc
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Input file size in blocks. The file_alloc argument is the
address of a longword containing the size of the input file.
This argument is optional because, by default, SORT uses the
allocation of the input files. If you are using the record
interface, or if the input files are not on disk, the default is
1000 blocks.(The high-performance Sort/Merge utility determines
the default based on the size of the input file, or if input is
not from files, on available memory.) When you specify the input
size with this argument, it overrides the default size.
This optional argument is useful when you are using the record
interface and you have a good idea of the total input size. You
can use this argument to improve the efficiency of the sort by
adjusting the amount of resources the sort process allocates to
match the input size.
user_compare
OpenVMS usage:procedure
type: procedure value
access: function call
mechanism: by reference
User-written routine that compares records to determine their
sort order. (This argument is not currently supported by the
high-performance Sort/Merge utility.) The user_compare argument
is the address of the procedure value for this user-written
routine. If you do not specify the key_buffer argument or if
you define key information in a specification file, this argument
is required.
SORT/MERGE calls the comparison routine with five reference
arguments-ADRS1, ADRS2, LENG1, LENG2, CNTX-corresponding to
the addresses of the two records to be compared, the lengths of
these two records, and the context longword. The LENG1 and LENG2
arguments are addresses that point to 16-bit word structures that
contain the length information.
The comparison routine must return a 32-bit integer value:
o -1 if the first record collates before the second
o 0 if the records collate as equal
o 1 if the first record collates after the second
user_equal
OpenVMS usage:procedure
type: procedure value
access: function call
mechanism: by reference
User-written routine that resolves the sort order when records
have duplicate keys. (This argument is not currently supported
by the high-performance Sort/Merge utility.) The user_equal
argument is the address of the procedure value for this user-
written routine. If you specify SOR$M_STABLE or SOR$M_NODUPS in
the options argument, do not use this argument.
SORT/MERGE calls the duplicate key routine with five reference
arguments-ADRS1, ADRS2, LENG1, LENG2, CNTX-corresponding to the
addresses of the two records that compare equally, the lengths of
the two records that compare equally, and the context longword.
The LENG1 and LENG2 arguments are addresses that point to 16-bit
word structures that contain the length information.
The routine must return one of the following 32-bit integer
condition codes:
Code Description
SOR$_ Delete the first record from the sort.
DELETE1
SOR$_ Delete the second record from the sort.
DELETE2
SOR$_ Delete both records from the sort.
DELBOTH
SS$_NORMAL Keep both records in the sort.
Any other failure value causes the error to be signaled or
returned. Any other success value causes an undefined result.
sort_process
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Code indicating the type of sort process. The sort_process
argument is the address of a byte whose value indicates whether
the sort type is record, tag, index, or address. (The high-
performance Sort/Merge utility supports only the record process.
Implementation of the tag, address, and index processes is
deferred to a future OpenVMS Alpha release.) The default is
record. If you select the record interface on input, you can
use only a record sort process.
To specify a byte containing the value for the type of sort
process you want, enter one of the following:
o SOR$GK_RECORD (record sort)
o SOR$GK_TAG (tag sort)
o SOR$GK_ADDRESS (address sort)
o SOR$GK_INDEX (index sort)
work_files
OpenVMS usage:byte_unsigned
type: byte (unsigned)
access: read only
mechanism: by reference
Number of work files to be used in the sorting process. The work_
files argument is the address of a byte containing the number of
work files; permissible values for SORT range from 0 through 10.
(For the high-performance Sort/Merge utility, you can specify
from 1 through 255 work files. The default is 2.)
By default, SORT creates two temporary work files when it needs
them and determines their size from the size of your input files.
By increasing the number of work files, you can reduce their
individual size so that each fits into less disk space. You can
also assign each of them to different disk-structured devices
(highly recommended).
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.
2.3 – Description
The SOR$BEGIN_SORT routine initializes the sort process by
setting up sort work areas and provides key specification and
sort options.
Specify the key information with the key_buffer argument, with
the user_compare argument, or in a specification file. If no key
information is specified, the default (character for the entire
record) is used.
You must use the SOR$BEGIN_SORT routine to initialize the sort
process for the file, record, and mixed interfaces. For record
interface on input, you must use the lrl (longest record length)
argument.
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.
2.4 – Condition Values Returned
SS$_NORMAL Normal successful completion.
SOR$_BADLOGIC Internal logic error detected.
SOR$_BAD_KEY Invalid key specification.
SOR$_BAD_LRL Record length n greater than specified longest
record length.
SOR$_BAD_MERGE Number of work files must be between 0 and 10.
(For the high-performance Sort/Merge utility,
the maximum number is 255.)
SOR$_BAD_TYPE Invalid sort process specified.
SOR$_ENDDIAGS Completed with diagnostics.
SOR$_INSVIRMEM Insufficient virtual memory.
SOR$_KEYAMBINC Key specification is ambiguous or
inconsistent.
SOR$_KEY_LEN Invalid key length, key number n, length n.
SOR$_LRL_MISS Longest record length must be specified.
SOR$_NODUPEXC Equal-key routine and no-duplicates option
cannot both be specified.
SOR$_NUM_KEY Too many keys specified.
SOR$_NYI Not yet implemented.
SOR$_RTNERROR Unexpected error status from user-written
routine.
SOR$_SORT_ON Sort or merge routine called in incorrect
order.
SOR$_STABLEEXC Equal-key routine and stable option cannot
both be specified.
SOR$_SYSERROR System service error.
SOR$_UNDOPTION Undefined option flag was set.
3 – SOR$DTYPE
The SOR$DTYPE routine defines a key data type that is not
normally supported by SORT/MERGE. (This routine is not currently
supported by the high-performance Sort/Merge utility.) This
routine returns a key data type code that can be used in the key_
buffer argument to SOR$BEGIN_SORT or SOR$BEGIN_MERGE to describe
special key data types (such as extended data types and National
character set (NCS) collating sequences).
Format
SOR$DTYPE [context] ,dtype_code ,usage ,p1
3.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.
3.2 – Arguments
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.
dtype_code
OpenVMS usage:word_unsigned
type: word (unsigned)
access: write only
mechanism: by reference
Returned key data type code. The dtype_code argument is the
address of a word into which SORT/MERGE writes the key data type
code that can be used in the key_buffer argument to SOR$BEGIN_
SORT or SOR$BEGIN_MERGE.
usage
OpenVMS usage:longword_unsigned
type: longword (unsigned)
access: read only
mechanism: by reference
Address of a longword containing a code that indicates the
interpretation of the p1 argument. The following table lists
and describes the valid usage codes:
Flag Description
SOR$K_ROUTINE The p1 argument should be interpreted as the
address of the procedure value of a routine
that SORT/MERGE will call to compare keys
described by the dtype_code returned by the
call to SOR$DTYPE.
SOR$K_NCS_TABLE The p1 argument should be interpreted as the
address of a collating sequence identification
returned by a call to NCS$GET_CS. SORT/MERGE
will use this collating sequence to compare keys
described by the dtype_code returned by the call
to SOR$DTYPE.
If SOR$K_ROUTINE is returned, SORT/MERGE will call this routine
with five reference arguments-ADRS1, ADRS2, LENG1, LENG2, CNTX-
corresponding to the addresses of the two keys to be compared,
the lengths of the two keys, and the context longword.
The comparison routine must return a 32-bit integer value:
o -1 if the first key collates before the second
o 0 if the keys collate as equal
o +1 if the first key collates after the second
p1
OpenVMS usage:longword_unsigned
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.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.4 – Condition Values Returned
SS$_NORMAL Normal successful completion.
SOR$_NYI Not yet implemented.
SOR$_SORT_ON Sort or merge routine called in incorrect
order.
4 – SOR$END_SORT
The SOR$END_SORT routine performs cleanup functions, such as
closing files and releasing memory.
Format
SOR$END_SORT [context]
4.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.
4.2 – 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.
4.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.
4.4 – 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.
5 – 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]
5.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.
5.2 – 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.
5.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.
5.4 – 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.
6 – 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]
6.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.
6.2 – 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.
6.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.
6.4 – 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.
7 – 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]
7.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.
7.2 – 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.
7.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.
7.4 – 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.
8 – SOR$SORT_MERGE
The SOR$SORT_MERGE routine sorts the input records.
Format
SOR$SORT_MERGE [context]
8.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.
8.2 – 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.
8.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.
8.4 – 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.
9 – 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]
9.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.
9.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.
9.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.
9.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.
10 – 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]
10.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.
10.2 – 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.
10.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.
10.4 – 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.