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.
For each dataset which satisifies the specified criteria, the filename field (with the complete directory path) and the extension number is printed. 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".
SEE ALSO
udcif, crcif, caldb
CATEGORY
ftools.caltools
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
|