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]
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 – 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.
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.
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.