 |
OpenVMS Utility Routines Manual
SOR$END_SORT
The SOR$END_SORT routine performs cleanup functions, such as closing
files and releasing memory.
Format
SOR$END_SORT [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 |
| 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$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.
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.
|
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]
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
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-Digital 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 sequential
|
0 to 16,362
|
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.
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.
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.
|
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]
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
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.
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.
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.
|
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]
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
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.
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.
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.
|
|
