Indentifier   mask

 Purpose       To mark specified data points as bad

 Synopsis      status = mask, struc_in, struc_out, bad_list [, /unmask]


 Arguments     Name      I/O  Type     Description
               --------------------------------------------------------

               struc_in  I    struct   Input structure (AAR)

               struc_out O    struct   Output structure (AAR)
                                       (unchanged if fatal error)

               bad_list  I    intarr   Array containing the index numbers
                                       of the points to be masked.
                                       (must be integers between 0 and N-1)

               unmask    I    int      optional flag to clear the mask bits
                                       (un-setting them)

 Returns       0 if OK   1 if fatal error

 Description   For every point in the bad list, the "mask" bit in the
               flag tag will be set to indicate that this point 
               contains bad data.


 Examples

               In the following example, the output is returned in an AAR
               structure named AAR_FLAGGED.

               To set the mask bit on the 3rd (index 2)

                      stat = mask (AAR_ORIG, AAR_MASKED, 2])

               To CLEAR the mask bit on the 2nd and 4th (index 1 and 3)

                      stat = mask (AAR_ORIG, AAR_MASKED, [1, 3], /unmask)

               This routine may also be used to add a flag tag to AAR_NOFLAG

                      stat = mask (AAR_NOFLAG, AAR_WITHFLAG, 0, /unmask)

 Dependencies   CALLS: kwd_notset, redo_hdr, sap_error, update_history
                CALLED FROM: sap_rfits, IA

 Category      ISAP

 Filename      mask.pro

 Author        R. Narron (IPAC)

 Version       1.1

 History       definition of requirements - rewrite of E. Sturm's
               first draft by B. Swinyard 7/8/95

               0.1  950905 --> R. Narron (IPAC)  Prototype
               0.2  951010 --> R. Narron (IPAC)  New AAR definition
               1.0  951027 --> R. Narron (IPAC)  New parameter checking
               1.1  951106 --> R. Narron (IPAC)  Update FITS header if add
                                                  flag tag

 Copyright (C) 1995, California Institute of Technology.
 U.S. Government Sponsorship under NASA Contract NAS7-918 is acknowledged.
******************************************************************************