Functions in the low-level module are usually needed when it is necessary to perform some task that is not readily achievable using the high-level interface. This module may be loaded using
require ("cfitsio");
When mixing functions from both interfaces, it is not necessary to
explicitly load the cfitsio
module in this manner since it
is loaded automatically by the high-level interface.
For the most part, for those functions that have been wrapped, the
cfitsio
module represents a 1-1 mapping between the
functions of the cfitsio library and those of the module. For this
reason a detailed description of the functions in the
cfitsio
module will not be given here; the reader is
referred to the documentation for the CFITSIO library itself for the
details. Here only the semantic differences between the functions in
the module and those of the library, and how the functions are
documented.
Most CFITSIO functions adhere to a so-called ``inherited status''
convention via a ``status'' argument as the last parameter. In
addition functions also return the error status as a return value.
For simplicity the wrapping by the module does not respect this
convention. That is, none of the module's functions take a status
argument. For example, the CFITSIO documentation for the
fits_get_num_hdus
specifies that it is to be called from C
via:
status = fits_get_num_hdus (fptr, &hdunum, &status);
This function has been wrapped such that it is to be called from
S-lang via
status = _fits_get_num_hdus (fptr, &hdunum);
Retrieve a text string corresponding to an error code
String_Type _fits_get_errstatus (Int_Type status)
This function is a wrapper around the cfitsio library function fits_get_errstatus
. See
its documentation for additional information.
Retrieve an error message from the cfitsio error message stack
String_Type _fits_read_errmsg ()
This function is a wrapper around the cfitsio library function fits_read_errmsg
. See
its documentation for additional information.
This function returns NULL
if there are no error messages available.
Open a fits file
status = _fits_open_file (Ref_Type fptr, String_Type file, String_Type mode)
This function is a wrapper around the cfitsio library function fits_open_file
. See
its documentation for additional information.
The main difference between this function and its cfitsio
counterpart is that the mode
argument is a string whose value
must be one of the following:
"r" Open the file in read-only mode
"w" Open the file in read-write mode
"c" Create a new file.
Note that if the mode argument is "c"
, then the
cfitsio fits_create_file
function will be called. An
important difference between this intrinsic function and the
fits_create_file
library function is that if the file already
exists, the library function will return an error, whereas
_fits_open_file
will simply delete the file before creating a
new one.
Delete the file associated with a Fits_File_Type object
status = _fits_delete_file (Fits_File_Type fptr)
This function is a wrapper around the cfitsio library function fits_delete_file
. See
its documentation for additional information.
Close a fits file
status = _fits_close_file (Fits_File_Type fptr)
This function is a wrapper around the cfitsio library function fits_close_file
. See
its documentation for additional information.
Move to an absolute HDU number
status = _fits_movabs_hdu (Fits_File_Type fptr, Int_Type hdunum)
This function is a wrapper around the cfitsio library function fits_movabs_hdu
. See
its documentation for additional information.
The cfitsio counterpart also returns the HDU type of the resulting HDU.
Move a relative number of HDUs
status = _fits_movrel_hdu (Fits_File_Type fptr, Int_Type nmove)
This function is a wrapper around the cfitsio library function fits_movrel_hdu
. See
its documentation for additional information.
The cfitsio counterpart also returns the HDU type of the resulting HDU.
Move to a named HDU
status = _fits_movnam_hdu (fptr, hdutype, extname, extvers)
Fits_File_Type fptr;
Int_Type hdutype, extvers;
String_Type extname;
This function is a wrapper around the cfitsio library function fits_movnam_hdu
. See
its documentation for additional information.
Return the number of HDUs in a FITS file
status = _fits_get_num_hdus (Fits_File_Type fptr, Ref_Type hdunum)
This function is a wrapper around the cfitsio library function fits_get_num_hdus
. See
its documentation for additional information.
Return the current HDU number
hdunum = _fits_get_hdu_num (Fits_File_Type fptr)
This function is a wrapper around the cfitsio library function fits_get_hdu_num
. See
its documentation for additional information.
Get the current HDU type
status = _fits_get_hdu_type (Fits_File_Type fptr, Ref_Type hdutype)
This function is a wrapper around the cfitsio library function fits_get_hdu_type
. See
its documentation for additional information.
Upon a sucessful return, the value of the variable associated with
the hdutype
reference will be set to one of the following
constants:
_FITS_IMAGE_HDU
_FITS_ASCII_TBL
_FITS_BINARY_TBL
Copy a fits file
status = _fits_copy_file (infptr, outfptr, previous, current, following)
Fits_File_Type infptr, outfptr;
Int_Type previous, current, following;
This function is a wrapper around the cfitsio library function fits_copy_file
. See
its documentation for additional information.
Copy an HDU
status = _fits_copy_hdu (infptr, outfptr, morekeys)
Fits_File_Type infptr, outfptr;
Int_Type morekeys;
This function is a wrapper around the cfitsio library function fits_copy_hdu
. See
its documentation for additional information.
Copy a fits header from one HDU to another
status = _fits_copy_header (Fits_File_Type infptr, Fits_File_Type outfptr)
This function is a wrapper around the cfitsio library function fits_copy_header
. See
its documentation for additional information.
Delete the current HDU
status = _fits_delete_hdu (Fits_File_Type fptr)
This function is a wrapper around the cfitsio library function fits_delete_hdu
. See
its documentation for additional information.
The corresponding cfitsio function also returns the HDU type of the
new HDU. If that information is necessary, make a separate call to
_fits_get_hdu_type
.
Create a new image extension
status = _fits_create_img (fptr, bitpix, dims)
Fits_File_Type fptr;
Int_Type bitpix;
Array_Type dims;
This function is a wrapper around the cfitsio library function fits_create_img
. See
its documentation for additional information.
This function differs from the corresponding cfitsio function in
that the dims
array is assumed to be a 1-d integer array
whose elements specify the number of axes and the size of each axis.
In particular, the value of the NAXIS keyword will be given by
length(dims)
, the value of NAXIS1 will be given by
dims[0]
, and so forth.
Write an image
status = _fits_write_img (Fits_File_Type fptr, Array_Type img
This function is a wrapper around the cfitsio library function fits_write_img
. See
its documentation for additional information.
This function differs from its cfitsio counterpart in that the whole
image represented by the array img
will be written out.
Read an image
status = _fits_read_img (Fits_File_Type fptr, Ref_Type img)
This function is a wrapper around the cfitsio library function fits_read_img
. See
its documentation for additional information.
This function differs from the corresponding cfitsio routine in that
the type of the image returned is automatically determined by the
routine via a call to fits_get_img_type
. The dimensionality
of the returned image is given by [...,NAXIS2,NAXIS1]
such
that NAXIS1
corresponds to the fastest varying dimension,
NAXIS2
the next fastest varying, etc.
Create a binary table extension
status = _fits_create_binary_tbl (fptr, naxis2, ttype, tform, tunit, extname)
Fits_File_Type fptr;
Array_Type tunit, tform, ttype;
Int_Type naxis2;
String_Type extname;
The _fits_create_binary_tbl
function is a wrapper around the
fits_create_tbl function explicitly creating a binary table.
The input arrays ttype
, tform
, and tunit
must
be the same length, which determines the number of columns in the
table. The tunit
and extname
parameters may be set to
NULL
.
Update a keyword or append a new one
status = _fits_update_key (fptr, keyname, value, comment)
Fits_File_Type fptr;
String_Type keyname, comment;
Any_Type value;
This function is a wrapper around the cfitsio library function fits_update_key
. See
its documentation for additional information.
The data-type for the value
argument must be an approriate type for
FITS keywords. If value
is a string, then the string will be
written as a cfitsio long-string using the
fits_update_key_longstr function. If value
is NULL
,
then the
fits_update_key_null function will be called to
update the keyword.
The comment
parameter may be set to NULL
to if the comment
field associated with the keyword is not to be modified.
To update the value of a boolean (logical) keyword, use the
_fits_update_logical
function.
Update the value of a boolean keyword
status = _fits_update_logical (fptr, keyname, value, comment)
Fits_File_Type fptr;
String_Type keyname, comment;
Int_Type value;
The _fits_update_logical
function is a wrapper around the
cfitsio
fits_update_key function with TLOGICAL specified as
the datatype argument. If the value
parameter is non-zero,
then a value T
(TRUE) will be given to the specified
keyword. Otherwise, the value of the keyword will be set to
F
(FALSE).
If the comment
parameter is NULL, then the keyword's comment
field will not be modified.
Write a COMMENT header
status = _fits_write_comment (Fits_File_Type fptr, String_Type comment)
This function is a wrapper around the cfitsio library function fits_write_comment
. See
its documentation for additional information.
Write a HISTORY header
status = _fits_write_history (Fits_File_Type fptr, String_Type history)
This function is a wrapper around the cfitsio library function fits_write_history
. See
its documentation for additional information.
Write a DATE keyword
status = _fits_write_date (Fits_File_Type fptr)
This function is a wrapper around the cfitsio library function fits_write_date
. See
its documentation for additional information.
Write a keyword record
status = _fits_write_record (Fits_File_Type fptr, String_Type card)
This function is a wrapper around the cfitsio library function fits_write_record
. See
its documentation for additional information.
Rename a keyword
status = _fits_modify_name (fptr, oldname, newname)
Fits_File_Type fptr;
String_Type oldname, newname;
This function is a wrapper around the cfitsio library function fits_modify_name
. See
its documentation for additional information.
Get the number of keywords in the current HDU
status _fits_get_num_keys (Fits_File_Type fptr, Ref_Type numkeys)
This function is a wrapper around the cfitsio
fits_get_hdrspace function. It obtains the number of
existing keywords in the current HDU (excluding the END keyword) and
assigns that value to variable associated with the numkeys
parameter.
Read the value of a keyword as an integer
status = _fits_read_key_integer (fptr, keyname, value, comment)
Fits_File_Type fptr;
String_Type keyname;
Ref_Type value, comment;
This function uses the cfitsio
fits_read_key function to read
the value of the specifed keyword as an integer. Its value is
assigned to the variable referenced by the value
parameter.
If the comment parameter is non-NULL, then the value of the comment
field will be assigned to it.
_fits_read_key,
_fits_read_key_string,
_fits_read_key_double
Read the value of a keyword as a string
status = _fits_read_key_string (fptr, keyname, value, comment)
Fits_File_Type fptr;
String_Type keyname;
Ref_Type value, comment;
This function uses the cfitsio
fits_read_key_longstr function
to read the value of the specifed keyword as a cfitsio long-string.
The string is assigned to the variable referenced by the
value
parameter. If the comment parameter is non-NULL, then
the value of the comment field will be assigned to it.
_fits_read_key,
_fits_read_key_integer,
_fits_read_key_double
Read the value of a keyword as a double
status = _fits_read_key_double (fptr, keyname, value, comment)
Fits_File_Type fptr;
String_Type keyname;
Ref_Type value, comment;
This function uses the cfitsio
fits_read_key function
to read the value of the specifed keyword as a double.
The keyword's value is assigned to the variable referenced by the
value
parameter. If the comment parameter is non-NULL, then
the value of the comment field will be assigned to it.
_fits_read_key,
_fits_read_key_integer,
_fits_read_key_string
Read the value of a keyword
status = _fits_read_key (fptr, keyname, value, comment)
Fits_File_Type fptr;
String_Type keyname;
Ref_Type value, comment;
This function uses the cfitsio
fits_read_key function
to read the value of the specifed keyword. It first uses the cfitsio
fits_get_keytype function to determine the data-type for the
keyword and then calls
fits_read_key using that data-type.
The resulting value is assigned to the variable referenced by the
value
parameter. If the comment parameter is non-NULL, then
the value of the comment field will be assigned to it.
_fits_read_key_integer,
_fits_read_key_string,
_fits_read_key_double
Read a specified record from the current HDU
status = _fits_read_record (fptr, keynum, card)
Fits_File_Type fptr;
Int_Type keynum;
Ref_Type card;
This function is a wrapper around the cfitsio library function fits_read_record
. See
its documentation for additional information.
Delete a keyword from the header
status = _fits_delete_key (Fits_File_Type fptr, String_Type keyname)
This function is a wrapper around the cfitsio library function fits_delete_key
. See
its documentation for additional information.
Get the column number of a specfied table column
status = _fits_get_colnum (fptr, colname, colnum)
Fits_File_Type fptr;
String_Type colname;
Ref_Type colnum;
This function is a wrapper around the cfitsio library function fits_get_colnum
. See
its documentation for additional information.
The corresponding cfitsio function permits a wildcard match to the
colname
parameter. The current wrapping of this function
does not support such matching.
The colname
parameter is treating in a case-insensitive manner.
Insert rows into a table
status = _fits_insert_rows (fptr, firstrow, nrows)
Fits_File_Type fptr;
Int_Type firstrow, nrows;
This function is a wrapper around the cfitsio library function fits_insert_rows
. See
its documentation for additional information.
Delete rows from a table
status = _fits_delete_rows (fptr, firstrow, nrows)
Fits_File_Type fptr;
Int_Type firstrow, nrows;
This function is a wrapper around the cfitsio library function fits_delete_rows
. See
its documentation for additional information.
Insert columns into a table
status = _fits_insert_cols (fptr, colnum, ttype, tform)
Fits_File_Type fptr;
Int_Type colnum;
Array_Type ttype, tform;
This function is a wrapper around the cfitsio library function fits_insert_cols
. See
its documentation for additional information.
The number of columns to be inserted is given by the length of
the ttype
and tform
arrays, which must be of the same
length.
Delete a column from a table
status = _fits_delete_col (Fits_File_Type fptr, Int_Type colnum)
This function is a wrapper around the cfitsio library function fits_delete_col
. See
its documentation for additional information.
Get the number of table columns
status = _fits_get_num_cols (Fits_File_Type fptr, Ref_Type ncols)
This function is a wrapper around the cfitsio library function fits_get_num_cols
. See
its documentation for additional information.
Get the number of rows to read or write for maximum efficiency
status = _fits_get_rowsize (Fits_File_Type fptr, Ref_Type nrows)
This function is a wrapper around the cfitsio library function fits_get_rowsize
. See
its documentation for additional information.
Get the number of table rows
status = _fits_get_num_cols (Fits_File_Type fptr, Ref_Type nrows)
This function is a wrapper around the cfitsio library function fits_get_num_rows
. See
its documentation for additional information.
Write data to a table column
status = _fits_write_col (fptr, colnum, firstrow, firstelem, array)
Fits_File_Type fptr;
Int_Type colnum;
Int_Type firstrow, firstelem;
Array_Type array;
This function is a wrapper around the cfitsio library function fits_write_col
. See
its documentation for additional information.
The number of elements written out to the column by this function will be equal to the number of elements in the array.
Read elements from a column
status = _fits_read_col (fptr, colnum, firstrow, numrows, array
Fits_File_Type fptr;
Int_Type colnum, firstrow, numrows;
Ref_Type array;
This function is a complicated wrapper around a number of cfitsio
functions to enable it to read any type of column, including vector
and variable length columns. The data read by the function is
assigned as the appropriately typed array to the variable referenced
by the array
argument.
For ordinary scalar columns, a 1-d array of size numrows
will
be produced. For a vector column, a 2d array of size
[numrows,repeat]
will be generated. Here repeat
is
given by the repeat value associated with the column. For a
variable length column, where data are stored in the heap of the
HDU, the data will be read as a 1-d array of numrows
arrays.
If the column is a bit-valued column, then data will be returned as an array of integers of the appropriate size. Currently only 8X, 16X, and 32X bit columns are supported.
Get a keyword's data type
status = _fits_get_keytype (fptr, keyname, type)
Fits_File_Type fptr;
String_Type keyname;
Ref_Type type;
This function is a wrapper around the cfitsio library function fits_get_keytype
. See
its documentation for additional information.
This function differs from its cfitsio counterpart in that instead
of explicitly specifying the keyword's value string, this function
uses the value of the specified keyword. It also returns the type
as a S-lang DataType_Type
object, e.g., Int_Type
,
Complex_Type
, etc.
Get the class of an input header record
Int_Type _fits_get_keyclass (String_Type card)
This function is a wrapper around the cfitsio library function fits_get_keyclass
. See
its documentation for additional information.
Read one or more table columns
status = _fits_read_cols (fptr, colnums, firstrow, nrows, arrays)
Fits_File_Type fptr;
Array_Type colnums;
Int_Type firstrow, numrows;
Ref_Type arrays;
This function performs a similar task as the _fits_read_col
.
The main difference is that instead of reading a single column, it
is capable of reading multiple columns specified by the colnums
parameter. It assigns the data as an array of arrays to the
variable referenced by the arrays
parameter. See the
documentation for the _fits_read_col
function for more
information.
This function takes advantage of the cfitsio buffering mechanism to optimize the reads.
Compute and write DATASUM and CHECKSUM keywords
status = _fits_write_chksum (Fits_File_Type fptr)
This function is a wrapper around the cfitsio library function fits_write_chksum
. See
its documentation for additional information.
Update the CHECKSUM keyword
status = _fits_update_chksum (Fits_File_Type fptr)
This function is a wrapper around the cfitsio library function fits_update_chksum
. See
its documentation for additional information.
Verify the checksums for the current HDU
status = _fits_verify_chksum (fptr, dataok, hduok)
Fits_File_Type fptr;
Ref_Type dataok, hduok;
This function is a wrapper around the cfitsio library function fits_verify_chksum
. See
its documentation for additional information.
Get the checksums for the current HDU
status = _fits_get_chksum (fptr, datasum, hdusum)
Fits_File_Type fptr;
Ref_Type datasum, hdusum;
This function is a wrapper around the cfitsio library function fits_get_chksum
. See
its documentation for additional information.
Get the cfitsio library version number
Float_Type _fits_get_version ()
This function is a wrapper around the cfitsio library function fits_get_version
. See
its documentation for additional information.