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

    The SOR$SPEC_FILE routine is used to pass a specification file
    or specification text to a sort or merge operation. (This routine
    is not currently supported by the high-performance Sort/Merge
    utility.)

    Format

      SOR$SPEC_FILE  [spec_file] [,spec_buffer] [,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

 spec_file

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read-only
    mechanism:    by descriptor
    Specification file name. The spec_file argument is the address
    of a descriptor pointing to the name of a file that contains
    the text of the options requested for the sort or merge. The
    specification file name string and the specification file buffer
    arguments are mutually exclusive.

 spec_buffer

    OpenVMS usage:char_string
    type:         character-coded text string
    access:       read-only
    mechanism:    by descriptor
    Specification text buffer. The spec_buffer argument is the
    address of a descriptor pointing to a buffer containing
    specification text. This text has the same format as the text
    within the specification file. The specification file name
    string and the specification file buffer arguments are mutually
    exclusive.

 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.

3 - Description

    Call SOR$SPEC_FILE to pass a specification file name or a buffer
    with specification text to a sort or merge operation. Through
    the use of a specification file, you can selectively omit or
    include particular records from the sort or merge operation and
    specify the reformatting of the output records. (See the Sort
    Utility in the OpenVMS User's Manual for a complete description
    of specification files.)

    If you call the SOR$SPEC_FILE routine, you must do so before you
    call any other routines. You must pass either the spec_file or
    spec_buffer argument, but not both.

    Some of the return 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

    SOR$_ENDDIAGS      Completed with diagnostics.
    SOR$_NYI           Not yet implemented.
    SOR$_SORT_ON       Sort or merge routine called in incorrect
                       order.
    SOR$_SYSERROR      System service error.