next up previous contents
Next: 3. Opening, Locking, Closing Up: CFHT FITS Handling Library Previous: 1. Using `idx' Sorting   Contents

Subsections

2. Summary of All Functions

NOTE: In this table, hu is a type HeaderUnit that was returned from a previous call to fh_create() or fh_ehu(), fd is an open file descriptor (type int) returned by a previous call to open(), and idx is a double floating point sorting number used internally by the library. Finally, where-ever name and comment are found, these are ASCII character strings (type char*). The must contain only those characters by the FITS standard.


Table 1: Functions to Open, Lock, Close, or create new FITS files
Return Function Parameters Description
HeaderUnit fh_file (const* filespec, fh_mode) Open and read header from a file or extension.
int fh_file_desc (HeaderUnit hu) Get the file descriptor used by fh_file
HeaderUnit fh_create No parameters Allocate a table to store FITS cards.
fh_result fh_destroy (HeaderUnit hu) Free memory associated with HeaderUnit. Check return!
fh_result fh_read (hu, int fd, double idx) Read header from an open file descriptor.
fh_result(**) fh_reserve (hu, int n) Reserve at least n cards slots for downstream use.
fh_result fh_validate (hu) Test if HeaderUnit is complete and valid.
fh_result fh_write (hu, fd) Write header, padding, and END to an open file.
fh_result fh_write_padding (hu, fd) Write padding to go after the IMAGE.
fh_result fh_write_padded_image (hu, fd, void* data, size) Write image from `data' plus padding.
fh_result fh_read_padded_image (hu, fd, void* data, size) Read image in user allocated `data'.
fh_result fh_copy_padded_image (hu, fd_out, fd_in) Copy image and padding from another open file.
fh_result fh_rewrite (hu) Write the header back to the original file, if possible.

(**)-Note: We might change the return of fh_reserve() to be the old number of reserved cards.


Table 2: Functions for looking at Extensions and Image data
Return Function Parameters Description
HeaderUnit fh_ehu (hu, int number) Seek to extension by its offset in the file (caution!)
HeaderUnit fh_ehu_by_imageid (hu, int imageid) Seek to extension with matching IMAGEID keyword.
HeaderUnit fh_ehu_by_extname (hu, char* extname) Seek by EXTNAME (e.g. ``im07'' or ``chip03b'')
int fh_extensions (hu) Reads NEXTEND to determine number of extensions.
int fh_image_bytes (hu) Reads BITPIX and NAXIS* to find (unpadded) image size.
int fh_image_blocks (hu) Converts fh_image_bytes to size in 2880-byte blocks.
int fh_header_blocks (hu) Returns size required for header, in 2880-byte blocks.


Table 3: Functions for Getting Keyword Values
Return Function Parameters Description
fh_result fh_get_bool (hu, char* name, int* value) *value gets 0 if F(alse) or 1 if T(rue)
fh_result fh_get_int (hu, char* name, int* value) *value gets integer value of `name'
fh_result fh_get_flt (hu, char* name, double* value) *value gets double-float value of `name'
fh_result fh_get_str (hu, char* name, char* value, maxlen) *value gets string value of `name'
double fh_idx_after (hu, char* name) Returns an `idx' that would cause a new header to be inserted after `name'
double fh_idx_before (hu, char* name) Returns an `idx' that would cause a new header to be inserted before `name'
fh_result fh_search (hu, char* name, double* idx) If FH_SUCCESS if found; if `idx' not NULL, it will return the card's `idx' value
fh_result fh_show (target_hu) Display a list on stdout (for debugging).


Table 4: Functions for Setting Keyword Values
Return Function Parameters Description
fh_result fh_remove (hu, char* name) Removes a card from the header unit in memory. It will disappear from the file on the next fh_rewrite()
fh_result fh_this_unit_only (hu) Overrides default behavior of fh_set*() functions, which normally change extensions too (if any).
void fh_set_com (hu, idx, char* name, char* comment) Creates new command card containing up to 72 ASCII characters. ``name'' should be ``HISTORY'' or ``COMMENT''.
void fh_set_bool (hu, idx,name, int value, comment) Changes or creates the card ``name'' and with new value of 'T' if value is non-zero, and sets comment field if comment is not empty.
void fh_set_int (hu, idx, name, int value, comment) Changes or creates the card ``name'' and with new integer value and comment fields.
void fh_set_flt (hu, idx, name, double value, comment) Changes or creates the card ``name'' and with new floating-point value and comment fields.
void fh_set_str (hu, idx, name, char* value, comment) Changes or creates the card ``name'' and with new string value and comment fields.
void fh_set_val (hu, idx, name, char* value, comment) Changes or creates the card ``name'' and with new pre-formatted value and comment fields. (Use typed functions above instead.)
fh_result fh_merge (target_hu, source_hu) Merges all cards from one list in another. Final order will depend on the sorting numbers contained in both.

2.1 Auto-assigned `idx' Numbers

It is also possible to use FH_AUTO for everything, in which case the order of the FITS header depends only on the order in which cards were added (except for the specific ones listed above, which will always be first.)

The original `idx' numbers are lost once a header has been re-read from a FITS file. In this case they are assigned numbers 10.001, 10.002, 10.003, ... You can change the base starting number (10.0) by passing a different value to fh_read().


next up previous contents
Next: 3. Opening, Locking, Closing Up: CFHT FITS Handling Library Previous: 1. Using `idx' Sorting   Contents
Sidik Isani
2001-04-22