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

    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]

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

 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.

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

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