[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

Content starts here

HP OpenVMS Utility Routines Manual


Previous Contents Index


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


Previous Next Contents Index