Common Pipeline Library Reference 7.3.2
|
Typedefs | |
typedef enum _cpl_fits_mode_ | cpl_fits_mode |
The CPL fits mode. It is a bit field. | |
Enumerations | |
enum | _cpl_fits_mode_ { CPL_FITS_STOP_CACHING , CPL_FITS_START_CACHING , CPL_FITS_RESTART_CACHING , CPL_FITS_ONE } |
The values of the CPL fits mode. The values can be combined with bitwise or. More... | |
Functions | |
cpl_size | cpl_fits_count_extensions (const char *filename) |
Get the number of extensions contained in a FITS file. | |
cpl_size | cpl_fits_find_extension (const char *filename, const char *extname) |
Get the place of a given extension in a FITS file. | |
int | cpl_fits_get_extension_nb (const char *filename, const char *extname) |
Get the place of a given extension in a FITS file. | |
cpl_fits_mode | cpl_fits_get_mode (void) |
Get the FITS I/O mode. | |
int | cpl_fits_get_nb_extensions (const char *filename) |
Get the number of extensions contained in a FITS file. | |
cpl_error_code | cpl_fits_set_mode (cpl_fits_mode mode) |
Set the FITS I/O mode. | |
This module provides functions to get basic information on FITS files
typedef enum _cpl_fits_mode_ cpl_fits_mode |
The CPL fits mode. It is a bit field.
enum _cpl_fits_mode_ |
The values of the CPL fits mode. The values can be combined with bitwise or.
cpl_size cpl_fits_count_extensions | ( | const char * | filename | ) |
Get the number of extensions contained in a FITS file.
filename | The file name |
Possible _cpl_error_code_ set in this function:
References cpl_ensure, CPL_ERROR_BAD_FILE_FORMAT, CPL_ERROR_FILE_IO, and CPL_ERROR_NULL_INPUT.
Referenced by cpl_fits_get_nb_extensions(), and cpl_frame_get_nextensions().
cpl_size cpl_fits_find_extension | ( | const char * | filename, |
const char * | extname | ||
) |
Get the place of a given extension in a FITS file.
filename | The file name |
extname | The extension name |
Possible _cpl_error_code_ set in this function:
References cpl_ensure, CPL_ERROR_FILE_IO, and CPL_ERROR_NULL_INPUT.
Referenced by cpl_fits_get_extension_nb(), and cpl_multiframe_append_datagroup().
int cpl_fits_get_extension_nb | ( | const char * | filename, |
const char * | extname | ||
) |
Get the place of a given extension in a FITS file.
filename | The file name |
extname | The extension name |
References cpl_fits_find_extension().
cpl_fits_mode cpl_fits_get_mode | ( | void | ) |
Get the FITS I/O mode.
References CPL_FITS_START_CACHING, and CPL_FITS_STOP_CACHING.
int cpl_fits_get_nb_extensions | ( | const char * | filename | ) |
Get the number of extensions contained in a FITS file.
filename | The file name |
References cpl_fits_count_extensions().
cpl_error_code cpl_fits_set_mode | ( | cpl_fits_mode | mode | ) |
Set the FITS I/O mode.
mode | The FITS I/O mode: CPL_FITS_STOP_CACHING, CPL_FITS_START_CACHING, CPL_FITS_RESTART_CACHING |
Normally when a FITS file is processed with a CPL call the file is openened and closed during that call. However repeated calls on FITS data with many extensions causes the FITS headers to be parsed many times which can lead to a significant performance penalty. If instead this function is called with CPL_FITS_START_CACHING, CPL will use internal storage to keep the FITS files open between calls and only close them when the FITS I/O mode is changed (or cpl_end() is called).
If a CPL function that creates a FITS file is called any previously opened handles to that file are closed. If a CPL function that appends to a FITS file is called any previously opened read-only handles to that file are closed. If a CPL function that reads from a FITS file is called any previously opened read/write-handle to that file is used for the read. Any additional concurrent reads causes the file to also be opened for reading. This means that there is also a performance gain when alternating between appending to and reading from the same file. This optimized I/O mode cannot be used if the CPL application accesses a FITS file without using CPL. An incomplete list of such access is: Calls to rename(), remove(), unlink(), fopen() and access via another process started with for example system() or popen().
The caching of opened FITS files may be used in a multi-threaded environment to the extent that the underlying FITS library (CFITSIO) supports it. One implication of this is that multiple threads may only call CPL FITS saving functions on the same file using proper synchronization such as the OpenMP 'ordered' construct. CPL makes no attempt to verify that a CPL based application performs thread parallel FITS I/O correctly.
The mode CPL_FITS_STOP_CACHING causes all cached filed to be closed. Beware that this can cause an I/O error for a file that has otherwise not been accessed for some time.
Since CPL_FITS_STOP_CACHING closes all cached FITS files, the caller must ensure that this does not interfere with the concurrent use of those same files in another thread.
The mode CPL_FITS_RESTART_CACHING has the same effect as a call with CPL_FITS_STOP_CACHING followed by a call with CPL_FITS_START_CACHING.
The modes CPL_FITS_RESTART_CACHING and CPL_FITS_ONE may be combined. This causes all files cached by the calling thread to be closed. The caching remains active (for all threads), so subsequently opened files will be cached.
CPL_FITS_RESTART_CACHING can be used after an external modification of a FITS file also cached by CPL, thus allowing the caching to work together with the above mentioned external access to the same FITS files.
Possible _cpl_error_code_ set in this function:
References CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NONE, CPL_ERROR_UNSUPPORTED_MODE, CPL_FITS_ONE, CPL_FITS_RESTART_CACHING, CPL_FITS_START_CACHING, and CPL_FITS_STOP_CACHING.
Referenced by cpl_end(), and cpl_init().