Selections

In CAT a selection is a set of rows in a catalogue which satisfy some criteria. Every selection that you create has a unique identifier. Once you have obtained a selection identifier it can be passed to CAT_RGET instead of a catalogue identifier, and CAT_RGET will operate on just the rows in the selection, rather than all the rows in the catalogue.

There are two routines for creating selections (that is, generating selection identifiers): CAT_SELCT and CAT_SFND$<$t$>$. CAT_SELCT allows selections to be made on complex criteria whereas CAT_SFND$<$t$>$ selects values in a simple range for a given sorted column. CAT_SFND$<$t$>$ will usually be faster than CAT_SELCT (a useful mnemonic is F for Fast and Find, S for Slow and Select), but is much less flexible. Both these routines optionally allow you to create a second selection comprising the rejected rows, as well as the primary selection of selected rows.

Suppose a catalogue was sorted on column DEC of data type REAL and you wished to find the rows for which DEC was in the range 10.0 to 20.0. Because this is a simple range selection on a sorted column routine CAT_SFND$<$t$>$ can be used.

      INTEGER
     :  CI,      ! Catalogue identifier.
     :  FI,      ! Identifier for column DEC.
     :  SI,      ! Selection identifier for selected rows.
     :  NUMSEL,  ! Number of selected rows.
     :  SIR,     ! Selection identifier for rejected rows.
     :  NUMREJ,  ! Number of rejected rows.
     :  ROW      ! Current row.
      REAL
     :  DECVAL   ! Value read for DEC from current row in selection.
      LOGICAL
     :  NULFLG   ! Null value flag.
       .
       .
       .

First get an identifier for column DEC.

      CALL CAT_TIDNT (CI, 'DEC', FI, STATUS)

Next create the selection and get an identifier for it. Note that because column DEC is of type REAL, the REAL version of CAT_SFND$<$t$>$, CAT_SFNDR, is used, and in this example the optional second selection, comprising the rejected rows, is not generated.

      CALL CAT_SFNDR (CI, FI, 10.0, 20.0, .FALSE., SI, NUMSEL,
     :  SIR, NUMREJ, STATUS)

Loop through all the rows in the selection, getting values for column DEC. Note how the selection identifier, SI, rather than the catalogue identifier, is passed to routine CAT_RGET.

      DO ROW = 1, NUMSEL
         CALL CAT_RGET (SI, ROW, STATUS)

         CALL CAT_EGT0R (FI, DECVAL, NULFLG, STATUS)
           .
           .
           .

      END DO

As a second example, suppose that the catalogue was not sorted on column DEC. CAT_SFND$<$t$>$ could not now be used to create the selection, and CAT_SELCT would have to be used instead. The procedure would then be as follows.

      INTEGER
     :  CI,      ! Catalogue identifier.
     :  FI,      ! Identifier for column DEC.
     :  EI,      ! Expression identifier.
     :  SI,      ! Selection identifier for selected rows.
     :  NUMSEL,  ! Number of selected rows.
     :  SIR,     ! Selection identifier for rejected rows.
     :  NUMREJ,  ! Number of rejected rows.
     :  ROW      ! Current row.
      REAL
     :  DECVAL   ! Value read for DEC from current row in selection.
      LOGICAL
     :  NULFLG   ! Null value flag.
       .
       .
       .

First CAT_EIDNT is used to get an expression identifier for the expression representing the criteria. This identifier is then passed to CAT_SELCT. Remember that the criterion is that DEC should be in the range 10.0 to 20.0.

      CAT_EIDNT (CI, '(DEC >= 10.0) & (DEC <= 20.0)', EI, STATUS)

      CAT_SELCT (CI, EI, .FALSE., SI, NUMSEL, SIR, NUMREJ, STATUS)

Next get an identifier for column DEC, then loop through all the rows in the selection, getting values for DEC. Again note how the selection identifier, SI, rather than the catalogue identifier, is passed to routine CAT_RGET.

      CAT_TIDNT (CI, 'DEC', FI, STATUS)

      DO ROW = 1, NUMSEL
         CALL CAT_RGET (SI, ROW, STATUS)

         CALL CAT_EGT0R (FI, DECVAL, NULFLG, STATUS)
           .
           .
           .

      END DO