SUBROUTINE
/* C or C++*/
int HDgtcalf(const char* tele, const char* instr,
const char* detnam, const char* filt,
const char* codenam, const char* strtdate,
const char* strtime, const char* stpdate, const char* stptime,
const char* expr, int* maxret, int filenamesize, char** filenam,
long* extno, char** online, int* nret,
int* nfound, int* status)
# Perl
use HEACORE::HEAUTILS;
HDgtcalf($tele, $instr, $detnam, $filt, $codenam,
$strtdate, $strtime, $stpdate, $stptime,
$expr, $maxret, $filenamesize,
$filnam, $extno, $online, $nret, $nfound, $status);
DESCRIPTION
This routine returns the location of calibration datasets located in
the Calibration Database.
Selection of the appropriate calibration data is based on the values of
the arguments TELE, INSTR, DETNAM, FILT, CODENAM, STRTDATE, STRTTIME,
STPDATE, STPTIME, EXPR. These arguments respectively describe the mission
or telescope, instrument, sub-detector, filter, type of dataset, start
date & time, stop date & time and calibration boundaries for which the
returned datasets should be valid.
In addition to the arguments explicitly listed here, this routine also
uses the values of the environment variables CALDB, and CALDBCONFIG.
See the Caldb user's guide for info on how these system variables should
be set.
The maximum number of datasets to return is given by the MAXRET argument.
Any datasets which meet the selection criteria are returned through the
FILENAM and EXTNO arrays. Each element of the FILENAM array contains
the complete system dependent path (including the filename) to the file
where the calibration data resides. The corresponding element of the
EXTNO array contains the FITS extension number of the calibration data
within the file.
Note that the calling sequence subroutine differs only slightly
from the FORTRAN gtcalf (in the FTOOLS package) in that the current
implementation does NOT include a "chatter" argument but does require
that a "filenamesize" argument be used to specify the desired length
of the returned string array elements. A wrapper exists for the current
routine so that it may be called from a FORTRAN program as "hdgtcalf".
There is an equivalent HDgtcalf interface using Perl. The function
arguments are identical to the C version. Upon return, the variables
$filenam, $extno and $online are Perl references to string arrays.
Therefore, there is no need for the caller to pre-allocate arrays
of the desired maximum size.
Access to the nth element of the $filenam array would be obtained
with "$filenam->[$n]".
ARGUMENTS
- tele (in)
- The name of the mission or telescope for which the
returned datasets should be valid. Corresponds to the
TELESCOP keyword value found in the requested calibration
file(s).
- instr (in)
- The name of the instrument for which the returned datasets
should be valid. Corresponds to the INSTRUME keyword
value found in the requested calibration file(s).
- detnam (in)
- The name of the detector for which the returned datasets
should be valid. Corresponds to the DETNAM keyword value
found in the requested calibration file(s). If a '-' is
passed, no selection will be made on detector names.
- filt (in)
- The name of the filter for which the returned datasets
should be valid. Corresponds to the FILTER keyword value
should be valid. Corresponds to the FILTER keyword value
found in the requested calibration file(s). If a '-' is
passed, no selection will be made on filter values.
- codenam (in)
- The OGIP codename for the requested dataset. Corresponds
to the CCNMxxxx keyword value found in the requested
calibration file(s).
- strtdate (in)
- The start-date when the datasets should be valid. This value
should be in dd/mm/yy format. If 'now' is passed, the
current system date is substituted.
- strtime (in)
- The time of the day (strtdate) when the dataset should be
valid. This value should be in hh:mm:ss.s format. If 'now' is
passed, the current system time is substituted.
- stpdate (in)
- The end-date when the datasets should be valid. This value
should be in dd/mm/yy format. If 'now' is passed, the
current system date is substituted.
- stptime (in)
- The time of the day (stpdate) when the dataset should be
valid. This value should be in hh:mm:ss.s format. If 'now' is
passed, the current system time is substituted.
- expr (in)
- A boolean expression used to select on calibration
boundary parameters. Calibration boundary parameters are
part of the CBDnxxxx keyword values found in the
requested calibration file(s). (e.g. In the string
'ENERGY(2-12)keV', ENERGY is the boundary parameter.)
Currently, the expression syntax supports the
arithmetic operator ".lt., .le., eq., .ge., .gt." and the logical operator
".and., .or.". To request a dataset which is valid for an
off-axis angle of 10 arcmins and an energy of 5.0 keV,
one would pass an expr value of: theta.eq.10.and.energy.eq.5
If no expr selection is required, a '-' value should be
passed.
NOTE: The expr parser cannot distinguish between certain
valid and invalid expressions. For example, expressions
such as:
cor.eq.7.and.and.energy.eq.5
will be incorrectly interpreted as "cor=7" and
"and.energy=5". A lex and yacc parser is planned for
this routine which will work much better.
- maxret (in)
- An integer defining the number of elements in the filenam
and extno arguments and the number of datasets to return.
- filenamesize (in)
- An integer defining the maximum length of filenam expected to
return.
- filenam (out)
- A character array containing the complete system dependent
path(s) to the file(s) in which the requested
calibration data is stored. In C, the array should be preallocated.
Dimensioned using the maxret argument. In Perl, $filenam returns
a reference to a Perl array, and no preallocation is required.
- extno (out)
- An integer array containing the FITS extension numbers of
requested datasets. Each extension number is valid for
the filename found in the corresonding element of the
filenam array. Dimensioned using the maxret argument.
In Perl, $extno returns
a reference to a Perl array, and no preallocation is required.
- online (out)
- A character array which specifys the on-line/off-line
status of the corresponding file in the filenam argument.
Each element contains either 'ONLINE' or a string
describing the off-line status of the file. If the
string 'ONLINE' is not encountered for a particular
filenam element, then this file has been moved to an
off-line media (e.g. magnetic tape) and the main program
will not be able to access the data.
In Perl, $online returns
a reference to a Perl array, and no preallocation is required.
- nret (out)
- The number of entries returned to the filenam extno
and online arguments.
- nfound (out)
- The nfound argument reports the total number of datasets
found during the search which match the selection
criteria. May be larger than maxret.
- status (out)
- The (integer) return status of the subroutine. The same as the
return value of the subroutine itself.
ALSO SEE
quzcif
The design of this routine is based on Fortran routine gtcalf in
FTOOLS callib package.
LAST MODIFIED
Oct 2011