OGIP Calibration Memo CAL/SW/93-005

Summary of CALLIB routines

Rehana Yusaf Ian M George, and Ron S Zellar

Codes 664 & 668,
NASA/GSFC,
Greenbelt,
MD 20771

Last Update: 1994 Feb 22
(by IMG)






SUMMARY

The document summarizes all available and currently planned modules of the CALLIB Subroutine Library.

This document is up-to-date for the FTOOLS version 3.2 Public release, and the NASA/GSFC development area as of 1995 Feb 01

Contents

1  INTRODUCTION
    1.1  Using CALLIB routines
2  SUMMARY TABLES
3  REFERENCES

LOG OF SIGNIFICANT CHANGES

Release Sections Changed Brief Notes
Date
1994 Feb 10 All FTOOLS Version 2.8 Public Release
1994 Mar 30 All FTOOLS Version 2.9 Public Release
1994 Jun 01 All FTOOLS Version 3.0 Public Release
1994 Oct 21 All FTOOLS Version 3.1 Internal Release
1995 Jan 10 All Made compatible with LaTeX2HTML software
1995 Jan 13 All FTOOLS Version 3.2 Public Release
2004 Apr 01 All Made compatible with tth

ABOUT THIS DOCUMENT

This document was constructed from a single LATEXavailable via anonymous ftp from the HEASARC (legacy.gsfc.nasa.gov) as:
caldb/docs/memos/cal_sw_93_005.tex

However, due to its size, two pdf versions are available:

(It should be noted that the Table of Contents of cal_sw_93_005_small.pdf includes the full Table of Contents of cal_sw_93_005.pdf).

Typically this document is up-dated once a month, but at least once per FTOOLS release. The last update and corresponding FTOOLS release are given on the front page.

1  INTRODUCTION

CALLIB is a subroutine library which contains useful utilities that have been used by several calibration related FTOOLS. The /callib library is a subdirectory of the FTOOLS package (see Users.v3.0.ps). The CALLIB library has three sub-directories, src/gen which contains system independant routines, src/unx which contains UNIX/ULTRIX specific code and src/vms which contains the VMS specific routines.

One of the primary features of the CALLIB library is that it contains OGIP standard format FITS readers and writers, for example wtpha1.f (see section 2.1.8) writes a FITS PHA extension that conforms to the OGIP standard format, that software expects.

1.1  Using CALLIB routines

For a complete guide to installing FTOOLS see the Ftools installation guide (Install.v3.0.ps). In addition the Developer's Guide to FTOOLS is a useful referance (Develop.v3.0.ps). FTOOLS developers should note that the CALLIB library is not available with the CORE FTOOLS distribution, therefore it should not be used for a core package task. Currently the core packages are FUTILS,FIMAGE, and TIME. Assuming FTOOLS is installed, any user can access the CALLIB or any other FTOOLS library using the following path,

for UNIX/ULTRIX :

LIBF = -L/path/host -lcaltools -lftools -lhost -lxanlib -lfitsio

where path should contain your path to the FTOOLS host directory. For HEASARC users this is ftools/SUN/release for Suns, SUN should be replaced by DEC for DECstations.

for VMS :

ftools:[host]caltools/lib,ftools:[host]ftools/lib

The caltools link enables users to access the CALLIB library.

2  SUMMARY TABLES

Table 1: Available General Routines for writing Datasets
Subroutine Primary Versions Description
Name Author Pub DevWrites ...
wt_ear1992a IMG 0.9.0 0.9.0 a EARVERSN=1992a extension
wt_eef1992a IMG 1.0.2 1.0.2 a EEFVERSN = 1992a extension
wt_flt1992a IMG 1.0.0 1.0.0 a FLTVERSN = 1992a extension
wt_spec RY 1.0.8 1.0.8 a PHAVERSN = 1992a extension
wtarf1 IMG 1.0.1 1.0.1 an ARFVERSN = 1992a dataset
wtebd1 IMG 2.0.1 2.0.1 an EBOUNDS ext of an RMFVERSN = 1992a dataset
wtexm1 RY 1.0.1 1.0.1 a Exposure map in the Primary array
wtpha1 IMG 3.0.3 3.0.3 a PHAVERSN = 1992a extension
wtrmf1 IMG 3.2.0 3.2.0 a RMFVERSN = 1992a extension
wtrpf1 RY 1.0.1 1.0.1 a RPSFVERS = 1992a dataset

Table 2: Planned General Routines for writing Datasets
Subroutine Author Priority Status Description
Name Writes ...
wtcol1.fIMG 1 99% a COLVERSN = 1992a dataset
wtear1 IMG 1 99% a EARVERSN = 1992a dataset
wteef1 IMG 1 95% a EEFVERSN = 1992a dataset
wteff1.fIMG 1 99% a EFFVERSN = 1992a dataset
wtegd1.fIMG 1 99% a EGRDVERS = 1992a dataset
wtobf1 IMG 1 99% a OBSVERSN = 1992a dataset
wtspr1.fIMG 1 99% a SPRVERSN = 1992a dataset
wttrs1.fIMG 1 99% a TRANSVER = 1992a dataset
wtvig1.fIMG 1 99% a VIGVERSN = 1992a dataset

Table 3: Available General Routines for accessing Datasets
Subroutine Primary Versions Description
Name Author Pub DevReads ...
rdarf1 IMG 1.0.0 1.0.0 an ARFVERSN = 1992a dataset
rdatrd RY 1.0.0 1.0.0 a RDF Attitude dataset
rdebd1 RY 1.1.2 1.1.2 an EBOUNDS ext of an RMFVERSN = 1992a dataset
rdetm1 RY 1.0.0 1.0.0 a detector map from a FITS Primary Array
rdgti1 RY 2.0.0 2.0.0 a GTI dataset
rdmvrd RY 1.0.0 1.0.0 a RDF Event Rate dataset
rdoht1 RY 1.1.0 1.1.0 a SPECTRUM DETECTOR dataset
rdpha1 RY 1.0.3 1.0.3 a PHAVERSN = 1992a dataset
rdrmf1 RY 1.1.1 1.1.1 a RMFVERSN = 1992a dataset
rdrpf1 RY 1.1.1 1.1.1 a RPSFVERS = 1992a dataset

Table 4: Planned General Routines for accessing Datasets
Subroutine Author Priority Status Description
Name Reads ...
rdeprd RY 1 75% a RDF EPHEM dataset
rdhkrd RY 1 75% a RDF HKP dataset
rdstrd RY 1 75% a RDF HKSTA dataset

Table 5: Available General Routines for writing Keywords
Subroutine Primary Versions Description
Name Author Pub DevWrites ...
wt_addcom IMG 1.0.0 1.0.0 COMMENTS to CDU from ASCII i/p file
wt_cifkys IMG 1.1.0 1.1.0 keywords mandatory for CIF purposes
wt_objradec IMG 1.0.1 1.0.1 RA & dec keywords for an object/target
wt_obsinfo IMG 1.1.1 1.1.1 keywords containing observational details
wt_pntradec IMG 1.0.1 1.0.1 RA, dec & roll keywords for pointing direction
wt_regdesc IMG 1.3.0 1.3.0 keywords describing region descriptors
wt_scradec IMG 1.0.1 1.0.1 RA, dec & roll keywords for spacecraft orientation
wtftim IMG 1.0.2 1.0.2 keywords describing (observing) time (in detail)
wttobs IMG 1.0.1 1.0.1 keywords describing (observing) time (crudely)

Table 6: Planned General Routines for writing Keywords
Subroutine Author Priority Status Description
Name

Table 7: Available General Routines for accessing Keywords
Subroutine Author Latest Description
Name Version
rd_cifkys IMG 1993 Feb 17 Reads Mandatory keywords from current header unit
rd_obsinfo IMG 1.0.0 Reads Observation details of CHDU
rdtobs IMG 1.0.0 Reads details of time of observation from CHDU

Table 8: Planned General Routines for accessing Keywords
Subroutine Author Priority Status Description
Name

Table 9: Other General FITS/caldb-related CALLIB Routines Available
Subroutine Primary Versions Description
Name Author Pub Dev
cfappend RY spawns FTOOL fappend
cgetlun IMG sys-dep sys-dep Gets a free logical unit
ck_file RY 1.0.3 1.0.3 Checks for illegal (output) filenames etc
ck_man RY 1.0.1 1.0.1 Checks whether record is mandatory keyword
copyphd RY 1.0.2 1.0.2 Copys the primary header from one file to another
do_addcom IMG 1.0.1 1.0.1 Opens FITS file & adds COMMENTS from ASCII file
fndext IMG 1.1.0 1.1.0 Finds extension(s) with given EXTNAME
fndhdu IMG 1.1.0 1.1.0 Finds extension(s) with given HDUCLASn values
getkeys RY 1.0.0 1.0.0 Returns list of keywords
gt_csysnms IMG 1.1.0 1.1.0 Returns standard colnames for given spatial coord sys
mver RY 1.0.0 1.0.0 moves to desired extension
mvext RY 1.1.0 1.1.0 opens file and moves to desired extension
mvfile RZ 1.0 1.0 renames a given file
op_npa IMG 1.0.3 1.0.3 Gets free unit & opens a null P.array FITS file
par_dim RY 1.0.0 1.0.0 Parse TDIMnnn keyword
pg_fcecho RY 1.0.0 1.0.0 pages screen output
wt_com RY 1.0.3 1.0.3 Copy i/p file to o/p file excl PHA extension
wt_copy RY 1.0.1 1.0.1 Copy i/p extn to o/p file excl PHA extension
wt_ferrmsg RY 1.0 1.0 writes FITSIO error message in standard format

Table 10: Other General CALLIB Routines Available related to string manipulation
Subroutine Primary Versions Description
Name Author Pub Dev
apndfl RZ 1.0 1.0 Concatinates path & filename
cconc RZ (no #) (no #) Converts string to system default
clenact RY ?? ?? Returns length of string (excluding trailing blanks)
clnstr IMG 1.0.0 1.0.0 Replaces ïllegal" ASCII characters within a string
clocase RY 1.0 1.0 Converts to lower case
cptend RZ 1.0 1.0 Concats logical,director & filename
crmvblk IMG 1.0.0 1.0.0 Removes all blanks from a string
crmvlbk RZ ?? ?? ?? Removes LEADING blanks from a string
crmvxbk ?? ?? ?? Removes extra blanks from strings
rmvexsp RY 1.0.0 1.0.0 Replaces multiple blanks with single blank

Table 11: Other General CALLIB Routines Available
Subroutine Primary Versions Description
Name Author Pub Dev
cbftoch IMG (no #) (no #) Converts a (SF) byte buffer to char string
ccaldj RZ (no #) (no #) Converts Gregorian Calendar to MJD
ccldj RZ (no #) (no #) Converts Gregorian Calendar to MJD
cmp_fact RY 1.0.2 1.0.2 Determines compression factor for rebinning
cnxpksf IMG 1.0.1 1.0.1 Gets and decodes SF package header
copnrsf IMG 1.0.4 1.0.4 Opens an SF format file for reading
crstrsf IMG 1.0.0 1.0.0 Write strings as aux records to SF file
crsubsf IMG 1.0.2 1.0.2 Reads subsidiary SF record
cspawn IMG 1.1.0 1.1.0 Spawns to operating system
ctrlog RZ 1.0 1.0 Translates logical name
delfil RZ 1.0 1.0 Deletes a file
grp_rmf IMG 1.1.2 1.1.2 Calculates channel subsets for an RSP_MATRIX dataset
gtdate RZ 1.0 1.0 Returns system date as integer day, month, year
gtdir RZ 1.0 1.0 Gets current working directory
gttime RZ 1.0 1.0 Returns system time as integer hr,min,sec
ppthnm RZ 1.0 1.0 Parse string into disk,directory,filename strings
rd_rsp IMG 1.1.4 1.1.4 Reads an SF-style RSP file
remap IMG - 1.0.0 Remaps 1-d array onto another grid

Table 12: Planned General CALLIB Routines (Other)
Subroutine Author Priority Status Description
Name
gt_instalias RY 1 0% Returns any aliases for INSTRUME keyword value
gt_telealias RY 1 0% Returns any aliases for TELESCOPE keyword value
parse_cdb RY 1 0% Parses a CBD expression

Table 13: Available Einstein-specific CALLIB Routines
Subroutine Primary Versions Description
Name Author Pub Dev
wtehr1 IMG - 1.1.0 writes DETECTOR extension for the HRI
wtipc1 IMG - 1.2.0 writes DETECTOR extension for the IPC

Table 14: Available EXOSAT-specific CALLIB Routines
Subroutine Primary Versions Description
Name Author Pub Dev
cma_detnam IMG - 1.0.0 returns DETNAM & FILTER strings for the CMA
cshfdmy IMG - ? converts SHF key to calendar dd/mm/yy
cshftime IMG - ? converts SHF key to integer yr,day,hr,min,sec
me_detnam IMG - 1.0.0 returns DETNAM string for the ME
wtxgs1 IMG - 1.0.0 writes DETECTOR extension for the GSPC
wtxme1 IMG - 2.0.0 writes DETECTOR extension for the ME

Table 15: Available ROSAT-specific CALLIB Routines
Subroutine Primary Versions Description
Name Author Pub Dev
livtim ??? ??? ??? calc PSPC livetime ????
rdatu0 RY - 1.0.1 reads US REV0 format Attitude extension
rdmvu0 RY - 1.0.0 reads US REV0 format (Qualified) EVRAT extension
wtrhr1 IMG - 1.1.0 writes DETECTOR extension for the HRI
wtrps1 IMG - 2.1.0 writes DETECTOR extension for the PSPC

3  REFERENCES

Develop.v3.0.ps, Blackburn, J.K,
available via anonymous FTP, /FTP/software/ftools/release/Develop.v3.0.ps

Install.v3.0.ps, Blackburn, J.K, Greene, E.A,
available via anonymous FTP, /FTP/software/ftools/release/Install.v3.0.ps

Users.v3.0.ps, Blackburn, J.K, Greene, E.A,
available via anonymous FTP, /FTP/software/ftools/release/Users.v3.0.ps

USEFUL LINKS TO OTHER HTML PAGES

The following useful links are available (in the HTML version of this document only):



File translated from TEX by TTH, version 3.13.
On 21 Apr 2004, 07:23.