VMS Help SOR Routines, SOR$PASS_FILES  *Conan The Librarian (sorry for the slow response - running on an old VAX)

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