quzcif HEADAS help file

NAME

QUZCIF -- Returns the name and location of calibration files

USAGE

quzcif mission instrument detector filter codename date time expr

DESCRIPTION

This task is a command-line interface to the Calibration Database access software. It writes to the standard output datasets in the Database which meet the selection criteria as specified by the input parameters. The number of datasets returned and displayed to standard output can be restricted using the MAXRET parameter.

Quzcif prints the filename field (with the complete directory path) and the extension number of each row in the calibration index file which satisfies the specified criteria. If the user is accessing the HEASARC CALDB using remote access, the full URL of the files is returned.

Any datasets which are stored off-line (on magnetic tapes, for example) will be displayed with the word 'OFFLINE' and the off-line media will appear before the filename and extension number.

Datasets which are located on the HEASARC server can be accessed if the user's CALDB environment variable is set to https://heasarc.gsfc.nasa.gov/FTP/caldb and can be optionally downloaded to the user's current working directory (if the retrieve parameter is set to "yes").

If no datasets are found which satisfy the specified criteria, then the message "No datasets found matching selection criteria" is displayed, as long as the chatter parameter is greater than 0.

Before using this task, the 'CALDB' and 'CALDBCONFIG' environment variables (logicals) must be set. See the Caldb Installation Guide for details.

PARAMETERS

mission [string]

The name of the mission for which selected datasets should be valid (for example "rosat", "asca", "halosat"). The mission parameter is matched against the TELESCOP keyword in the calibration file extensions.

instrument [string]

The name of the instrument for which the selected datasets should be valid. The instrument value specified will be matched against the value of the INSTRUME keywords in the calibration file extensions.

detector [string]

The name of the detector for which the selected datasets should be valid. If a "-" character is input, this parameter will not be used in the selection process. The detector parameter is compared against the DETNAM keyword in the calibration file extensions

filter [string]

The name of the filter for which the selected datasets should be valid. If a "-" character is input, this parameter will not be used in the selection process. The filter parameter is compared against the FILTER keyword in the calibration file extensions

codename [string]

The OGIP codename for the requested data. The value input for this parameter corresponds to the CCNM0001, CCNM0002, ... keyword values found in all CALDB calibration files. Also, the NASA OGIP Memo CAL/GEN/92-011 contains a list of valid codenames and their meanings. This memo can be obtained from https://heasarc.gsfc.nasa.gov/FTP/caldb/docs/memos/cal_gen_92_011/cal_gen_92_011.html.

date [string]

The date portion of the time for which the selected datasets should be valid, in UT. The date and time specified by the user will be added together and converted to MJD, and compared to the MJDs of the validity start date/time of the files in the CALDB. The latest calibration datasets which match other specifications and which have a validity start date/time less than or equal to the specified date and time are returned. The date should be specified as a value in yyyy-mm-dd format, with days and months given as 2-digit integers with leading zeroes. Two special values are allowed:

If the date is specified as "now", the current system date is used for the selection.
If the date is given as a single dash ("-"), then the date check is bypassed (and the value of time is ignored).

time [string]

The time portion of the time for which the selected datasets should be valid, in UT. The date and time specified by the user will be added together and converted to MJD, and compared to the MJDs of the validity start date/time of the files in the CALDB. The latest calibration datasets which match other specifications and which have a validity start date/time less than or equal to the specified date and time are returned. The time should be specified in hh:mm:ss format, with hours, minutes and seconds given as 2-digit integers with leading zeroes. One special value is allowed:

If the date is specified as "now", the current system time is used for the selection.

Note that if the date is given as a single dash ("-"), then the check of the validity start dates is bypassed (and the value of time is ignored).

expr [string]

A boolean selection expression for Calibration Boundary parameters. These parameters can be used to restrict the data selection using additional criteria, like intrument temperature, off-axis angle and other criteria. If no expr selection is required, a "-" character should be input at the prompt. The boolean expression syntax only allows the arithmetic operator ".eq." and the logical operator ".and.". For example, a value of expr = theta.eq.10.and.energy.eq.5 would select calibration datasets whose theta boundary equals 10 and whose energy boundary equals 5, in the units specified by the CALDB boundary keyword values. See Section B of "Required and Recommended FITS keywords for Calibration Files, Section B" for more information, expression syntax and examples.

(maxret=-1) [integer]

An integer indicating the maximum number of datasets to return to the screen. If set to -1 all found datasets will be returned. The user will be warned if more datasets were found than were returned, if maxret is a positive integer.

(quality=0) [integer]

An integer giving the desired value of the CAL_QUAL flag of the caldb files. A value of quality = 0 will return the standard "good" calibration files for the specified search. A list of other quality values that have been used historically is available in Section 3 of the Calibration Index Files document (Calibration Memo CAL/GEN/92-008) available at https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/caldb_doc.html

(retrieve) [boolean]

If set to "yes", and the user is accessing the caldb remotely (as opposed to accessing the caldb from a locally mounted disk) identified calibration data file which match the selection criteria are downloaded to the user's current working directory. If set to "no", files are not downloaded. This parameter has no effect if the user is accessing a local version of the caldb.

(nfound) [integer]

An integer, returned after the successful completion of this task, which indicates the number of datasets found matching the selection criteria. If this parameter is greater than maxret (and maxret is positive), a warning message will be displayed.

EXAMPLES

1. Find the location of the ASCALIN dataset for the SIS0 instrument of the ASCA mission valid for Jun 20, 1994, via remote access to the HEASARC CALDB

    % setenv CALDB https://heasarc.gsfc.nasa.gov/FTP/caldb
    % quzcif asca sis0 - - ascalin 1994-06-20 12:00:00 -
    https://heasarc.gsfc.nasa.gov/FTP/caldb/data/asca/sis/bcf/s0_teldef_070294.fits   0

2. Find the ALIGNMENT dataset for the FPM instrument of the NuSTAR mission for the optical axis, from the HEASARC CALDB:

    % quzcif nustar fpm  - - alignment now now TYPE.eq.OPTICAL
    https://heasarc.gsfc.nasa.gov/FTP/caldb/data/nustar/fpm/bcf/align/nuCalign20200901v001.fits   3

3. Find the ALIGNMENT dataset for the FPM instrument of the NuSTAR mission for the optical axis, from the HEASARC CALDB, and retrieve the file using retrieve=yes, and overwrite the file if it exists in the current working directory, with verbose output:


    % quzcif nustar fpm - - alignment now now TYPE.eq.OPTICAL retrieve=yes chatter=1 clobber=yes maxret=-1
    ...... environ-var/logical CALDB defined
    .........   CALDB path = https://heasarc.gsfc.nasa.gov/FTP/caldb
    ...... environ-var/logical CALDBCONFIG defined
    .........   CALDBCONFIG file = /Users/mcorcora/software/caldb/caldb.config
    ...... environ-var/logical CALDBALIAS defined
    .........   CALDBALIAS file = /Users/mcorcora/software/caldb/alias_config.fits
    ...... CALDB is configured for the FPM instrument onboard NUSTAR
    ......... Cal Index File: https://heasarc.gsfc.nasa.gov/FTP/caldb/data/nustar/fpm/caldb.indx
    ......... Instrument directory: https://heasarc.gsfc.nasa.gov/FTP/caldb/data/nustar/fpm
    gtcalf 1.2.3  : Searching CALDB for quality values =  0
    ...... Searching for CAL_QUAL =          0
    ...... Quality: Found        527 matches out of       1071 rows
    ...... Telescope: Found        527 matches out of        527 rows
    ...... Instrument: Found         88 matches out of        527 rows
    ...... Detector: Found         88 matches out of         88 rows
    ...... Filter: Found         88 matches out of         88 rows
    ...... CAL_CNAME: Found         66 matches out of         88 rows
    ...... Checking boundary expression =TYPE.EQ.OPTICAL
    ...... Boundary: Found         11 matches out of         66 rows
    ...... Time check: Found         11 matches out of         11 rows
    ... Found          1 rows after time selection
    nuCalign20200901v001.fits   3
    % ls ./nuCalign20200901v001.fits
    nuCalign20200901v001.fits

4. Return the files which have CAL_QUAL value of 5 for the Swift XRT MATRIX files

% quzcif swift xrt - - matrix now now - chatter = 1 quality = 5

 ...... environ-var/logical CALDB defined
 .........   CALDB path = https://heasarc.gsfc.nasa.gov/FTP/caldb
 ...... environ-var/logical CALDBCONFIG defined
 .........   CALDBCONFIG file = /Users/mcorcora/software/caldb/caldb.config
 ...... environ-var/logical CALDBALIAS defined
 .........   CALDBALIAS file = /Users/mcorcora/software/caldb/alias_config.fits
 ...... CALDB is configured for the XRT instrument onboard SWIFT
 ......... Cal Index File: https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xr
           t/caldb.indx
 ......... Instrument directory: https://heasarc.gsfc.nasa.gov/FTP/caldb/data/sw
           ift/xrt
gtcalf 1.2.3  : Searching CALDB for quality values =  5
 ...... Searching for CAL_QUAL =          5
 ...... Quality: Found        383 matches out of        719 rows
 ...... Telescope: Found        383 matches out of        383 rows
 ...... Instrument: Found        383 matches out of        383 rows
 ...... Detector: Found        383 matches out of        383 rows
 ...... Filter: Found        383 matches out of        383 rows
 ...... CAL_CNAME: Found         63 matches out of        383 rows
 ...... Boundary: Found         63 matches out of         63 rows
 ...... Time check: Found         63 matches out of         63 rows
https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxwt0s0_20070901v011.rmf   1
https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxwt0s6_20070901v011.rmf   1
https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxwt0to2s0_20070901v011.rmf   1
https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxwt0to2s6_20070901v011.rmf   1
https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxpc0s0_20070901v011.rmf   1
https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxpc0s6_20070901v011.rmf   1
https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxpc0to12s0_20070901v011.rmf   1
https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxpc0to12s6_20070901v011.rmf   1
https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxwt0s6_20070901v012.rmf   1
https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xrt/cpf/rmf/swxwt0to2s6_20070901v012.rmf   1

5. Search for a non-valid codename with chatter = 0 (with remote access to the HEASARC CALDB):

 % quzcif swift xrt - - matrix1 now now - chatter = 0 quality = 5
 ERROR - cifsl3 1.0: No match for CAL_CNAM = MATRIX1 in https://heasarc.gsfc.nas
         a.gov/FTP/caldb/data/swift/xrt/caldb.indx

6. Search for a non-valid codename with chatter = 2 (with remote access to the HEASARC CALDB):

% quzcif swift xrt - - matrix1 now now - chatter = 2 quality = 0
 ...... environ-var/logical CALDB defined
 .........   CALDB path = https://heasarc.gsfc.nasa.gov/FTP/caldb
 ...... environ-var/logical CALDBCONFIG defined
 .........   CALDBCONFIG file = /Users/mcorcora/software/caldb/caldb.config
 ...... environ-var/logical CALDBALIAS defined
 .........   CALDBALIAS file = /Users/mcorcora/software/caldb/alias_config.fits
 ...... CALDB is configured for the XRT instrument onboard SWIFT
 ......... Cal Index File: https://heasarc.gsfc.nasa.gov/FTP/caldb/data/swift/xr
           t/caldb.indx
 ......... Instrument directory: https://heasarc.gsfc.nasa.gov/FTP/caldb/data/sw
           ift/xrt
gtcalf 1.2.3  : Searching CALDB for quality values =  0
 ...  using cifsl3 1.0
 ...... Searching for CAL_QUAL =          0
 ...... Quality: Found        336 matches out of        719 rows
 ...... Telescope: Found        336 matches out of        336 rows
 ...... Instrument: Found        336 matches out of        336 rows
 ...... Detector: Found        336 matches out of        336 rows
 ...... Filter: Found        336 matches out of        336 rows
 ERROR - cifsl3 1.0: No match for CAL_CNAM = MATRIX1 in https://heasarc.gsfc.nas
         a.gov/FTP/caldb/data/swift/xrt/caldb.indx
 ... Allowed Values of CAL_CNAM are:
 ...  using rcnfig 2.0.2
 ... RATEDN2FLUX          EEF                  EVTRANGE
     HKCONV               HKRANGE              BIAS                 MKFCONF
     SPECRESP             TDPOSERR             POSERR
     TDPOSDATA            POSDA
 ERROR - cifsl3 1.0: STOPPING
 ERROR - gtcalf 1.2.3: Fatal - STOPPING

7. Specify date= '-'

% quzcif 'mission=MAXI' 'instrume=GSC_2' 'detector=-' 'filter=-' 'codename=HVBITHIST' 'date=-' 'time=-' 'expr=-'
https://heasarc.gsfc.nasa.gov/FTP/caldb/data/maxi/gsc/bcf/mx_gsc2_hvhist_20180213.fits   1

BUGS

The current expr parser cannot precheck the expression well. Subexpressions such as "cor.eq.7.and.and.energy.eq.5" will be incorrectly interpreted as "cor=7" and "and.energy=5".

LOG OF SIGNIFICANT CHANGES

Ron Zellar (1993 Feb 3), original version

Ron Zellar (1993 Jun 14), added trinst subroutine

Ron Zellar (1993 Jun 14), added prscreen param

Ron Zellar (1994 Jan 20), Moved qzcif out of quzcif Moved ftupch calls to qzcif Moved gcfdir call to qzcif

Ron Zellar (1994 Jul 15), Reconfigured to use gtcal subroutine. Moved "now" feature to gtcal, added params detector, filter, expr, maxret and nfound. Removed params prscreen, path, and extno.

Lorraine Breedon 24 Jun 1998 - modifications for y2k problem version 1.2

Jeff Guerber (1999-03-26), Removed Lorraine's date parameter format check and reprompt loop (gpqzcf), which rejected old-style dates and looped forever if the bad date had been entered on the command line; lower-level routines (eg. dt2mjd) check the format anyway. Increased sizes of date and time strings. Version 1.3.

PDW (1999-08-11), Replaced gtcal with gtcalf and added chatter parameter

MFC (2008-12-09) VERSION 1.3 added "retrieve" parameter to allow user option of downloading remote files via ftp or http

MFC (2009-09-15) version 1.4.1 if retrieve="yes" fecho the name of the local file (with the http://... stripped off)

MFC (2009-10-07) version 1.4.2 fixed bug where retrieve="yes" gave an empty string if local caldb used

MFC (2009-10-09) version 1.4.3 initialized "lun" variable to fix a segfault in Centos linux

MFC (2009-10-12) version 1.4.3.1 restored behavior from 1.4.1 which was lost in 1.4.2 and 1.4.3, namely: retrieve+ with remote CALDB access: downloads file, reports root file name (with url stripped off); retrieve- with remote CALDB access: does not download but reports full url to file; retrieve+, retrieve- using a local CALDB installation: no download, reports full path to file

MFC (2009-10-13) version 1.4.4 - added clobber param

MFC (2017-05-01) version 1.4.5 - added quality param so users can search for caldb files where quality is not 0. this is useful for seeing the number of "bad" files in a cif, or for setting a non-zero quality to use if a calfile normally should not be used but may be appropriate in certain circumstances

MFC: added https support when retrieve+; updated version to 1.46

MFC (03/17/21), version 1.6: updated calibration file selection library routine cifsl to cifsl3, which returns alerts the user which selection criteria failed if no valid selections are found. If codename parameter is not matched, quzcif will return a list of valid CODENAMEs for the specified mission/instrument if chatter >= 2. Also, a date specified as a dash (i.e. "date = '-'") causes the date check to be bypassed.

PRIMARY CONTACT

Mike Corcoran

HEASARC