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

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

The design of this routine is based on Fortran routine gtcalf in FTOOLS callib package.

LAST MODIFIED