.help caldflag Jun97 ftools.caltools 
.ih
NAME
caldbflag -- switches flag status of calibration files in a CIF
.ih
USAGE
.nf
   mission instrument alias inpfile flag1 switch1 flag2 switch2 flag3 switch3
     flag4 switch4 flag7 switch7 flag8 switch8 flag10 switch10 flag12 switch12
     origin flag13 swit13 flag14 swit14
     (calfexp) (chatter) (mode)
.fi
.ih
DESCRIPTION
This task is a maintenance task for CALDB managers. For a given calibration 
dataset listed within a local Calibration Index File (CIF), the task enables
1 or more CIF flags to be switched to requested values (at the EXTENSION level). THIS TASK SHOULD BE RUN FROM THE TOP LEVEL DIRECTORY TO THE CALDB i.e. from $CALDB. As input, the task requires :

(i) an ASCII file containing a list of calibration files whose flag status is 
to be changed. FOR EACH FILE the path to the file should be given AND the 
extension  i.e. 
data/xte/pca/bcf/e2c/pca_e2c_eo3v00.fits[1]
data/xte/pca/bcf/e2c/pca_e2c_eo3v00.fits[2]
data/xte/pca/bcf/e2c/pca_e2c_eo3v00.fits[5]

(ii) the mission & instrument whose CIF is to be updated.

(iii) the name of any alias for this instrument (doesnt matter which is entered)
      i.e. for ASCA XRT the aliases are XRT1, XRT2, XRT3, XRT4
           for ASCA SIS the aliases are SIS0, SIS1
           for ASCA XRT the aliases are GIS2, GIS3
           for ROSAT PSPC the aliases are PSPCB, PSPCC

If an instrument has no alias (i.e. XTE PCA) then just re-enter the 
name of the instrument (i.e. PCA). 

The alias info is required by a subroutine which determines the path to a CIF.

(iii) the names of the CIF flags (equivalent to CIF columns) to switch.

(iv) the NEW value for each CIF flag. 

The input ASCII file consists of one entry (filename[#extn]) per row. The task 
parses each entry, separating the filename[#extn] from any directory path. This i/p filename[#extn] is then compared to entries in the CIF. If a match is found then the status of the requested flag(s) for that file is updated appropriately in the CIF.

The CIF flags whose values (status) may be switched are:
.nf
flag1  (CIF column CAL_DEV)  On/off-line status
flag2  (CIF column CAL_CLAS) OGIP class
flag3  (CIF column CAL_DTYP) OGIP Caldb data type
flag4  (CIF column CAL_CNAM) OGIP data set
flag7  (CIF column CAL_VSD)  Validity Start Date
flag8  (CIF column CAL_VST)  Validity Start Time
flag10 (CIF column CAL_QUAL) Data quality flag
flag12 (CIF column CAL_DESC) Description string
...if CIF contains an extra column CAL_ORIG (indicated by `origin' input parameter set to .true.), then flag13
flag13 (CIF column CAL_ORIG) flag to indicate (place) origin of cal data
flag14 (CIF column DETNAM) Name of detector
.fi

Flags CAL_CLAS, CAL_DTYP, CAL_CNAM, CAL_VSD, CAL_VST, CAL_QUAL, CAL_DESC, CAL_ORIG, DETNAM:
the NEW input value merely replaces the old value.

Flag CAL_DEV slightly more complex : 
In cases when files are being taken off-line (the ASCII list should therefore contain ALL the [#extn] of that file), the path to (but NOT the name
of) the calibration file is removed from the CAL_DIR & CAL_FILE columns in
the CIF. This is to allow for the possibility that the file will be
restored back on-line in a different location. 

In cases when files are being put back on-line (the ASCII list should therefore contain ALL the [#extn] of that file), any path to the file given via the i/p ASCII file is compared to the current working directory.The task then attempts to determine the full path to the file and checks whether it exists. If so (meaning the task was indeed successfully able to determine the full path to the file), this path is written to the appropriate row(s) of the CAL_DIR column in the CIF.

General Points :
The i/p ASCII file may contain blank lines, which will be ignored. 
In addition, lines in the ASCII file starting with the character # will be 
considered comment cards and also be ignored. The calibration filenames may 
include local path names (since to determine filename matches, all files,
including those in the CIF, are stripped of their paths). Appropriate 
Errors & Warnings are issued if a calibration file given in the ASCII
file does not exist in the CIF, already has the flag status requested, or (in the case of switches to the CAL_DEV flag), when caldbflag is unable to determine the full path to the newly restored file.

.ih
PARAMETERS
.ls mission [character string]
 The user-supplied string for the mission name.
.le
.ls instrument [character string]
 The user-supplied string for the instrument name.
.le

.ls alias [character string]
 The name of the instrument alias
.le
.ls inpfile [character string]
 The name of the user ASCII file containing the calibration files whose CIF flag
 status is to be changed.
.le
.ls flag1 [logical]
 User-supplied request to switch CAL_DEV flag in CIF.
.ls switch1 [character string]
 New value supplied to CAL_DEV.
.le
.ls flag2 [logical]
 User-supplied request to switch CAL_CLAS flag in CIF.
.ls switch2 [character string]
 New value supplied to CAL_CLAS.
.le
.ls flag3 [logical]
 User-supplied request to switch CAL_DTYP flag in CIF.
.ls switch3 [character string]
 New value supplied to CAL_DTYP.
.le
.ls flag4 [logical]
 User-supplied request to switch CAL_CNAM flag in CIF.
.ls switch4 [character string]
 New value supplied to CAL_CNAM.
.le
.ls flag7 [logical]
 User-supplied request to switch CAL_VSD flag in CIF.
.ls switch7 [character string]
 New value supplied to CAL_VSD.
.le
.ls flag8 [logical]
 User-supplied request to switch CAL_VST flag in CIF.
.ls switch8 [character string]
 New value supplied to CAL_VST.
.le
.ls flag10 [logical]
 User-supplied request to switch CAL_QUAL flag in CIF.
.ls switch10 [character string]
 New value supplied to CAL_QUAL.
.le
.ls flag12 [logical]
 User-supplied request to switch CAL_DESC flag in CIF.
.ls switch12 [character string]
 New value supplied to CAL_DESC
.le
.ls origin [logical]
 User-supplied information as to whether CIF contains CAL_ORIG column.
.le
.ls flag13 [logical]
 User-supplied request to switch CAL_ORIG flag in CIF.
.ls switch13 [character string]
 New value supplied to CAL_ORIG
.le
.ls flag14 [logical]
 User-supplied request to switch DETNAM flag in CIF.
.ls switch14 [character string]
 New value supplied to DETNAM
.le
.ls (calfexp=CALDB) [character string] 
 The name of the environment variable.
.le
.ls (chatter = 9) [integer]
 Flag to indicate how chatty the task is at execution. A value of 9 is the
 default, with lower/higher values producing quieter/verbose output 
 respectively.
.le
.ls (mode = "ql") [character string]
.le 
.ih
BUGS
None known
.ih
LOG OF SIGNIFICANT CHANGES
.ls v1.0.0 (1996 Aug)
    original version (Lorraine Breedon)
    v1.1.0 (1997 Jan)
    adapted to account for file extensions (Lorraine Breedon)
    v1.2.0 (1997 Jun)
    adapted to account for extra CIF column CAL_ORIGIN (Lorraine Breedon)
    v1.3.0 (1997 Dec)
    included option to switch DETNAM flag (Lorraine Breedon)
.le

.ih
PRIMARY AUTHOR

.nf
Lorraine Breedon
HEASARC
NASA/GFSC
.fi
.endhelp

