
                           Sort Subroutine Interface

    The SORTS module is provided as an FCS replacement  for  the  DEC  Sort-11
    subroutine interface, providing the same functionality  without  requiring
    the overhead of RMS-11.  The user calls  the  five  entry  points  (RSORT,
    RELES, MERGE, RETRN, and ENDS) just as he does in  Sort-11,  although  the
    calling parameters are slightly  different.  Limitations  and  differences
    from Sort-11 are as follows:
    
    1) all records and sort keys are treated as fullword integer data  (it  is
       possible to sort data with character (byte) keys by swapping the  bytes
       in each word of the sort key before releasing the record to  the  sort,
       and swapping them back upon return)
    2) the sort key must be part of the record to  be  sorted  (it  cannot  be
       external to it)
    3) sort records are limited to 256 words in length
    4) keys are examined from left to right in making comparisons, rather than
       the weird right to left approach in Sort-11
    5) at least 3 and no more than 8 scratch files must be specified
    
    Calling sequences are as follows:

     CALL RSORT(RECSIZ,KEYSIZ,KEYLOC,WORK,WORKSZ,KEYBUF,IFILES,FIRLUN,STATUS)
       RECSIZ - size of the records to be sorted in words
       KEYSIZ - size of the sort key in words
       KEYLOC - relative location of the key in the record. (e.g., if the  key
                is the leftmost KEYSIZ words of the record, KEYLOC=0)
       WORK   - work area as in Sort-11. must be dimensioned as integer  array
                (the bigger this array is made, the faster the sort)
       WORKSZ - size of work area in words
       KEYBUF - an array provided by you to be used internally by SORTS.  must
                be dimensioned as integer, with a size equal to KEYSIZ
       IFILES - number of scratch files to use (recommend four)
       FIRLUN - first lun to be used for scratch files (luns are  assigned  in
                ascending sequence from this one)
       STATUS - error return STATUS (see below)

     CALL RELES(RECORD,WORK,KEYBUF,STATUS)
       RECORD - record to be sorted
       WORK   - same array as specified in RSORT call
       KEYBUF - same array as specified in RSORT call
       STATUS - return status (see below)

     CALL MERGE(WORK,KEYBUF,STATUS)
       WORK   - same array as specified in RSORT call
       KEYBUF - same array as specified in RSORT call
       STATUS - return status (see below)

     CALL RETRN(RECORD,WORK,KEYBUF,STATUS)
       RECORD - array into which to return next sorted record
       WORK   - same array as specified in RSORT call
       KEYBUF - same array as specified in RSORT call
       STATUS - return status (see below)

     CALL ENDS(STATUS)
       STATUS - return status (see below)



    Return statuses:

    00 - no errors
    06 - not enough work area (must be at least (IFILES-1)*RECSIZ*2 words)
    10 - sort routine called out of order
    12 - invalid keysize (must be positive and <= record size)
    13 - invalid record size (must be in range 1-256 words)
    14 - key location is invalid (must be in range 0 - recordsize-1)
    15 - record address invalid (must be on a fullword boundary)
    17 - too few scratch files specified (must be at least 3)
    20 - too many scratch files specified (must be less than 8)

    -1 - no more records (returned by RETRN)


    Memory requirements for this sort module are approximately 2000 words of
    memory for instructions and local  data,  plus  whatever  work  area  is
    specified for it.

    To include this sort in a task, the modules SORTS and COMP must be input
    to the task builder.  They are distributed in a system library.    Thus:

    task=xxx,yyy,zzz,LB:[1,1]SORTLIB/LB:SORTS:COMP
    /
    SUPLIB=FCSFSL:SV
    ACTFIL=n  (be sure to set high enough to include SORTS scratch files)
    UNITS=n   (be sure to set high enough to include SORTS scratch files)
    MAXBUF=n  (must be at least as large as records to sort)
    ASG=SY:n:n:n  (all scratch files used by SORTS must be assigned to disk)
    //
