 |
OpenVMS Utility Routines Manual
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]
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
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+
|
Octaword integer (signed)
|
|
DSC$K_DTYPE_OU+
|
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+
|
H-format floating
|
|
DSC$K_DTYPE_FS++
|
IEEE single-precision S floating
|
|
DSC$K_DTYPE_FT++
|
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+
|
Numeric string, zoned sign
|
|
DSC$K_DTYPE_P
|
Packed decimal string
|
+Data type is not currently supported by the high-performance
Sort/Merge utility.
++Data type is Alpha specific.
The OpenVMS Programming Interfaces: Calling a System Routine 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_NOSIGNAL
|
Returns a status code instead of signaling errors.
|
|
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:
- --1 if the first record collates before the second
- 0 if the records collate as equal
- 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$_DELETE1
|
Delete the first record from the sort.
|
|
SOR$_DELETE2
|
Delete the second record from the sort.
|
|
SOR$_DELBOTH
|
Delete both records from the sort.
|
|
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:
- SOR$GK_RECORD (record sort)
- SOR$GK_TAG (tag sort)
- SOR$GK_ADDRESS (address sort)
- 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.
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.
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.
|
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
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
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:
- --1 if the first key collates before the second
- 0 if the keys collate as equal
- +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.
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.
Condition Values Returned
|
SS$_NORMAL
|
Normal successful completion.
|
|
SOR$_NYI
|
Not yet implemented.
|
|
SOR$_SORT_ON
|
Sort or merge routine called in incorrect order.
|
|
