ORDERS (3sciport)

Internally sorts fixed length records

SYNOPSIS

  Call ORDERS( mode, work, data, index, n, record, key [, radix] )

ARGUMENTS

  mode            Integer.
                  An input/output integer field.
                  On input, mode describes the type of key and indicates
                  ordering as follows:

                  0  Keys are 64 bit unsigned integers or binary characters
                  1  Keys are 64 bit signed integers
                  2  Keys are 64 bit IEEE floating point numbers
                  10 Same as mode = 0, but index contains initial ordering
                  11 Same as mode = 1, but index contains initial ordering
                  12 Same as mode = 2, but index contains initial ordering

                  On output, a value < 0 is returned in mode if an error is
                  encountered.  Otherwise, mode is not changed. Error codes
                  are interpreted as follows:

                  -3 record must be greater than zero
                  -4 key must be in closed interval [1,8]
                  -8 mode must be 0, 1, 2, 10, 11, or 12
                  -9 key must be eight for mode 1, 2, 11, or 12.

  work            Integer.
                  A vestigial argument not used by this routine.

  data            Integer, Logical, or Real matrix.
                  An input matrix of dimension data( record,n ). Matrix data
                  comprises n records each of length record.

  index           Integer vector.
                  An input/output integer vector. If mode = 10, 11, or 12,
                  index hold the permutation vector for data, the input
                  matrix. When mode = 0, 1, or 2, the key field of the i'th
                  record is located at data( 1,i ).  When mode = 10, 11, or
                  12, the key field of the i'th record is located at data(
                  1,index( i ) ). Vector index is overwritten by the new
                  permutation vector on output.

  n               Integer.
                  The number of records to be sorted.

  record          Integer.
                  The length, in eight byte words, of each record. The value
                  of record must be positive.

                  WARNING! In this implementation, record is NOT optional.

  key             Integer.
                  The length of each key in bytes. If mode is 1, 2, 11, or
                  12, key must be eight. Otherwise, key must be in the closed
                  interval [1,8].

                  WARNING! In this implementation, key is NOT optional.
                  WARNING! In this implementation, key cannot be greater
                           than eight.

  radix           Integer.
                  An optional argument ignored by this implementation even if
                  present. The routine ORDERS selects its radix.

DESCRIPTION

  Routine ORDERS sorts fixed length records using an internal radix sort
  algorithm. Radix techniques are attractive for several reasons.

  First, radix sorts are stable. This means that records with identical keys
  retain their positions relative to each other, permitting multi-pass
  sorting on different keys.

  Second, the time to sort data increases linearly with the number of data
  records to be sorted. Using any other technique, sort time increases
  superlinearly with the number of records. Thus, radix sorts are fast!

  Except for the fact that arguments record and key are required, this
  version of ORDERS may be used exactly like the Cray version for sorting
  records on boolean (eight byte unsigned integers), integer (signed), or
  real keys.

  However, because of machine endian issues, care must be taken when sorting
  character data. Because of endian considerations, the range of the key
  argument has been limited to the closed interval [1,8]. The example.f
  program, contained in the distribution kit, shows how you can use of a
  multi-pass sort on character data. The same program shows how you can use a
  multi-byte single pass sort on the same data. The program, example.f,
  should function correctly on both Cray and Alpha machines.

  For equations and other information, see Volume 3: UNICOS Math and
  Scientific Library Reference Manual SR-2081 7.0, Cray Research, Inc.