Next Previous Contents

3. The low-level interface

3.1 Overview

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);

3.2 Low-level Function Reference

_fits_get_errstatus

Synopsis

Retrieve a text string corresponding to an error code

Usage

String_Type _fits_get_errstatus (Int_Type status)

Description

This function is a wrapper around the cfitsio library function fits_get_errstatus. See its documentation for additional information.

See Also

fits_read_errmsgs, _fits_read_errmsg

_fits_read_errmsg

Synopsis

Retrieve an error message from the cfitsio error message stack

Usage

String_Type _fits_read_errmsg ()

Description

This function is a wrapper around the cfitsio library function fits_read_errmsg. See its documentation for additional information.

Notes

This function returns NULL if there are no error messages available.

See Also

fits_read_errmsgs, fits_set_verbose_errors

_fits_open_file

Synopsis

Open a fits file

Usage

status = _fits_open_file (Ref_Type fptr, String_Type file, String_Type mode)

Description

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.

_fits_delete_file

Synopsis

Delete the file associated with a Fits_File_Type object

Usage

status = _fits_delete_file (Fits_File_Type fptr)

Description

This function is a wrapper around the cfitsio library function fits_delete_file. See its documentation for additional information.

_fits_close_file

Synopsis

Close a fits file

Usage

status = _fits_close_file (Fits_File_Type fptr)

Description

This function is a wrapper around the cfitsio library function fits_close_file. See its documentation for additional information.

_fits_movabs_hdu

Synopsis

Move to an absolute HDU number

Usage

status = _fits_movabs_hdu (Fits_File_Type fptr, Int_Type hdunum)

Description

This function is a wrapper around the cfitsio library function fits_movabs_hdu. See its documentation for additional information.

Notes

The cfitsio counterpart also returns the HDU type of the resulting HDU.

_fits_movrel_hdu

Synopsis

Move a relative number of HDUs

Usage

status = _fits_movrel_hdu (Fits_File_Type fptr, Int_Type nmove)

Description

This function is a wrapper around the cfitsio library function fits_movrel_hdu. See its documentation for additional information.

Notes

The cfitsio counterpart also returns the HDU type of the resulting HDU.

_fits_movnam_hdu

Synopsis

Move to a named HDU

Usage

status = _fits_movnam_hdu (fptr, hdutype, extname, extvers)

   Fits_File_Type fptr;
   Int_Type hdutype, extvers;
   String_Type extname;

Description

This function is a wrapper around the cfitsio library function fits_movnam_hdu. See its documentation for additional information.

_fits_get_num_hdus

Synopsis

Return the number of HDUs in a FITS file

Usage

status = _fits_get_num_hdus (Fits_File_Type fptr, Ref_Type hdunum)

Description

This function is a wrapper around the cfitsio library function fits_get_num_hdus. See its documentation for additional information.

_fits_get_hdu_num

Synopsis

Return the current HDU number

Usage

hdunum = _fits_get_hdu_num (Fits_File_Type fptr)

Description

This function is a wrapper around the cfitsio library function fits_get_hdu_num. See its documentation for additional information.

_fits_get_hdu_type

Synopsis

Get the current HDU type

Usage

status = _fits_get_hdu_type (Fits_File_Type fptr, Ref_Type hdutype)

Description

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

_fits_copy_file

Synopsis

Copy a fits file

Usage

status = _fits_copy_file (infptr, outfptr, previous, current, following)

   Fits_File_Type infptr, outfptr;
   Int_Type previous, current, following;

Description

This function is a wrapper around the cfitsio library function fits_copy_file. See its documentation for additional information.

_fits_copy_hdu

Synopsis

Copy an HDU

Usage

status = _fits_copy_hdu (infptr, outfptr, morekeys)

   Fits_File_Type infptr, outfptr;
   Int_Type morekeys;

Description

This function is a wrapper around the cfitsio library function fits_copy_hdu. See its documentation for additional information.

_fits_copy_header

Synopsis

Copy a fits header from one HDU to another

Usage

status = _fits_copy_header (Fits_File_Type infptr, Fits_File_Type outfptr)

Description

This function is a wrapper around the cfitsio library function fits_copy_header. See its documentation for additional information.

_fits_delete_hdu

Synopsis

Delete the current HDU

Usage

status = _fits_delete_hdu (Fits_File_Type fptr)

Description

This function is a wrapper around the cfitsio library function fits_delete_hdu. See its documentation for additional information.

Notes

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.

_fits_create_img

Synopsis

Create a new image extension

Usage

status = _fits_create_img (fptr, bitpix, dims)

   Fits_File_Type fptr;
   Int_Type bitpix;
   Array_Type dims;

Description

This function is a wrapper around the cfitsio library function fits_create_img. See its documentation for additional information.

Notes

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.

_fits_write_img

Synopsis

Write an image

Usage

status = _fits_write_img (Fits_File_Type fptr, Array_Type img

Description

This function is a wrapper around the cfitsio library function fits_write_img. See its documentation for additional information.

Notes

This function differs from its cfitsio counterpart in that the whole image represented by the array img will be written out.

_fits_read_img

Synopsis

Read an image

Usage

status = _fits_read_img (Fits_File_Type fptr, Ref_Type img)

Description

This function is a wrapper around the cfitsio library function fits_read_img. See its documentation for additional information.

Notes

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.

_fits_create_binary_tbl

Synopsis

Create a binary table extension

Usage

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;

Notes

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.

_fits_update_key

Synopsis

Update a keyword or append a new one

Usage

status = _fits_update_key (fptr, keyname, value, comment)

   Fits_File_Type fptr;
   String_Type keyname, comment;
   Any_Type value;

Description

This function is a wrapper around the cfitsio library function fits_update_key. See its documentation for additional information.

Notes

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.

_fits_update_logical

Synopsis

Update the value of a boolean keyword

Usage

status = _fits_update_logical (fptr, keyname, value, comment)

  Fits_File_Type fptr;
  String_Type keyname, comment;
  Int_Type value;

Description

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.

See Also

_fits_update_key

_fits_write_comment

Synopsis

Write a COMMENT header

Usage

status = _fits_write_comment (Fits_File_Type fptr, String_Type comment)

Description

This function is a wrapper around the cfitsio library function fits_write_comment. See its documentation for additional information.

_fits_write_history

Synopsis

Write a HISTORY header

Usage

status = _fits_write_history (Fits_File_Type fptr, String_Type history)

Description

This function is a wrapper around the cfitsio library function fits_write_history. See its documentation for additional information.

_fits_write_date

Synopsis

Write a DATE keyword

Usage

status = _fits_write_date (Fits_File_Type fptr)

Description

This function is a wrapper around the cfitsio library function fits_write_date. See its documentation for additional information.

_fits_write_record

Synopsis

Write a keyword record

Usage

status = _fits_write_record (Fits_File_Type fptr, String_Type card)

Description

This function is a wrapper around the cfitsio library function fits_write_record. See its documentation for additional information.

_fits_modify_name

Synopsis

Rename a keyword

Usage

status = _fits_modify_name (fptr, oldname, newname)

   Fits_File_Type fptr;
   String_Type oldname, newname;

Description

This function is a wrapper around the cfitsio library function fits_modify_name. See its documentation for additional information.

_fits_get_num_keys

Synopsis

Get the number of keywords in the current HDU

Usage

status _fits_get_num_keys (Fits_File_Type fptr, Ref_Type numkeys)

Description

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.

_fits_read_key_integer

Synopsis

Read the value of a keyword as an integer

Usage

status = _fits_read_key_integer (fptr, keyname, value, comment)

   Fits_File_Type fptr;
   String_Type keyname;
   Ref_Type value, comment;

Description

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.

See Also

_fits_read_key, _fits_read_key_string, _fits_read_key_double

_fits_read_key_string

Synopsis

Read the value of a keyword as a string

Usage

status = _fits_read_key_string (fptr, keyname, value, comment)

   Fits_File_Type fptr;
   String_Type keyname;
   Ref_Type value, comment;

Description

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.

See Also

_fits_read_key, _fits_read_key_integer, _fits_read_key_double

_fits_read_key_double

Synopsis

Read the value of a keyword as a double

Usage

status = _fits_read_key_double (fptr, keyname, value, comment)

   Fits_File_Type fptr;
   String_Type keyname;
   Ref_Type value, comment;

Description

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.

See Also

_fits_read_key, _fits_read_key_integer, _fits_read_key_string

_fits_read_key

Synopsis

Read the value of a keyword

Usage

status = _fits_read_key (fptr, keyname, value, comment)

   Fits_File_Type fptr;
   String_Type keyname;
   Ref_Type value, comment;

Description

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.

See Also

_fits_read_key_integer, _fits_read_key_string, _fits_read_key_double

_fits_read_record

Synopsis

Read a specified record from the current HDU

Usage

status = _fits_read_record (fptr, keynum, card)

   Fits_File_Type fptr;
   Int_Type keynum;
   Ref_Type card;

Description

This function is a wrapper around the cfitsio library function fits_read_record. See its documentation for additional information.

_fits_delete_key

Synopsis

Delete a keyword from the header

Usage

status = _fits_delete_key (Fits_File_Type fptr, String_Type keyname)

Description

This function is a wrapper around the cfitsio library function fits_delete_key. See its documentation for additional information.

_fits_get_colnum

Synopsis

Get the column number of a specfied table column

Usage

status = _fits_get_colnum (fptr, colname, colnum)

   Fits_File_Type fptr;
   String_Type colname;
   Ref_Type colnum;

Description

This function is a wrapper around the cfitsio library function fits_get_colnum. See its documentation for additional information.

Notes

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.

_fits_insert_rows

Synopsis

Insert rows into a table

Usage

status = _fits_insert_rows (fptr, firstrow, nrows)

   Fits_File_Type fptr;
   Int_Type firstrow, nrows;

Description

This function is a wrapper around the cfitsio library function fits_insert_rows. See its documentation for additional information.

_fits_delete_rows

Synopsis

Delete rows from a table

Usage

status = _fits_delete_rows (fptr, firstrow, nrows)

   Fits_File_Type fptr;
   Int_Type firstrow, nrows;

Description

This function is a wrapper around the cfitsio library function fits_delete_rows. See its documentation for additional information.

_fits_insert_cols

Synopsis

Insert columns into a table

Usage

status = _fits_insert_cols (fptr, colnum, ttype, tform)

   Fits_File_Type fptr;
   Int_Type colnum;
   Array_Type ttype, tform;

Description

This function is a wrapper around the cfitsio library function fits_insert_cols. See its documentation for additional information.

Notes

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.

_fits_delete_col

Synopsis

Delete a column from a table

Usage

status = _fits_delete_col (Fits_File_Type fptr, Int_Type colnum)

Description

This function is a wrapper around the cfitsio library function fits_delete_col. See its documentation for additional information.

_fits_get_num_cols

Synopsis

Get the number of table columns

Usage

status = _fits_get_num_cols (Fits_File_Type fptr, Ref_Type ncols)

Description

This function is a wrapper around the cfitsio library function fits_get_num_cols. See its documentation for additional information.

_fits_get_rowsize

Synopsis

Get the number of rows to read or write for maximum efficiency

Usage

status = _fits_get_rowsize (Fits_File_Type fptr, Ref_Type nrows)

Description

This function is a wrapper around the cfitsio library function fits_get_rowsize. See its documentation for additional information.

_fits_get_num_rows

Synopsis

Get the number of table rows

Usage

status = _fits_get_num_cols (Fits_File_Type fptr, Ref_Type nrows)

Description

This function is a wrapper around the cfitsio library function fits_get_num_rows. See its documentation for additional information.

_fits_write_col

Synopsis

Write data to a table column

Usage

status = _fits_write_col (fptr, colnum, firstrow, firstelem, array)

   Fits_File_Type fptr;
   Int_Type colnum;
   Int_Type firstrow, firstelem;
   Array_Type array;

Description

This function is a wrapper around the cfitsio library function fits_write_col. See its documentation for additional information.

Notes

The number of elements written out to the column by this function will be equal to the number of elements in the array.

_fits_read_col

Synopsis

Read elements from a column

Usage

status = _fits_read_col (fptr, colnum, firstrow, numrows, array

   Fits_File_Type fptr;
   Int_Type colnum, firstrow, numrows;
   Ref_Type array;

Description

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.

See Also

_fits_read_cols, _fits_write_col

_fits_get_keytype

Synopsis

Get a keyword's data type

Usage

status = _fits_get_keytype (fptr, keyname, type)

   Fits_File_Type fptr;
   String_Type keyname;
   Ref_Type type;

Description

This function is a wrapper around the cfitsio library function fits_get_keytype. See its documentation for additional information.

Notes

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.

_fits_get_keyclass

Synopsis

Get the class of an input header record

Usage

Int_Type _fits_get_keyclass (String_Type card)

Description

This function is a wrapper around the cfitsio library function fits_get_keyclass. See its documentation for additional information.

_fits_read_cols

Synopsis

Read one or more table columns

Usage

status = _fits_read_cols (fptr, colnums, firstrow, nrows, arrays)

   Fits_File_Type fptr;
   Array_Type colnums;
   Int_Type firstrow, numrows;
   Ref_Type arrays;

Description

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.

Notes

This function takes advantage of the cfitsio buffering mechanism to optimize the reads.

_fits_write_chksum

Synopsis

Compute and write DATASUM and CHECKSUM keywords

Usage

status = _fits_write_chksum (Fits_File_Type fptr)

Description

This function is a wrapper around the cfitsio library function fits_write_chksum. See its documentation for additional information.

_fits_update_chksum

Synopsis

Update the CHECKSUM keyword

Usage

status = _fits_update_chksum (Fits_File_Type fptr)

Description

This function is a wrapper around the cfitsio library function fits_update_chksum. See its documentation for additional information.

_fits_verify_chksum

Synopsis

Verify the checksums for the current HDU

Usage

status = _fits_verify_chksum (fptr, dataok, hduok)

   Fits_File_Type fptr;
   Ref_Type dataok, hduok;

Description

This function is a wrapper around the cfitsio library function fits_verify_chksum. See its documentation for additional information.

_fits_get_chksum

Synopsis

Get the checksums for the current HDU

Usage

status = _fits_get_chksum (fptr, datasum, hdusum)

   Fits_File_Type fptr;
   Ref_Type datasum, hdusum;

Description

This function is a wrapper around the cfitsio library function fits_get_chksum. See its documentation for additional information.

_fits_get_version

Synopsis

Get the cfitsio library version number

Usage

Float_Type _fits_get_version ()

Description

This function is a wrapper around the cfitsio library function fits_get_version. See its documentation for additional information.


Next Previous Contents