getwcstab.h File Reference

#include <fitsio.h>

Go to the source code of this file.

Data Structures
struct	wtbarr
	Extraction of coordinate lookup tables from BINTABLE. More...

Functions
int	fits_read_wcstab (fitsfile *fptr, int nwtb, wtbarr *wtb, int *status)
	FITS 'TAB' table reading routine. More...

Detailed Description

fits_read_wcstab(), an implementation of a FITS table reading routine for 'TAB' coordinates, is provided for CFITSIO programmers. It has been incorporated into CFITSIO as of v3.006 with the definitions in this file, getwcstab.h, moved into fitsio.h.

fits_read_wcstab() is not included in the WCSLIB object library but the source code is presented here as it may be useful for programmers using an older version of CFITSIO than 3.006, or as a programming template for non-CFITSIO programmers.

Function Documentation

int fits_read_wcstab	(	fitsfile *	fptr,
		int	nwtb,
		wtbarr *	wtb,
		int *	status
	)

fits_read_wcstab() extracts arrays from a binary table required in constructing 'TAB' coordinates.

Parameters

[in]	fptr	Pointer to the file handle returned, for example, by the fits_open_file() routine in CFITSIO.
[in]	nwtb	Number of arrays to be read from the binary table(s).
[in,out]	wtb	Address of the first element of an array of wtbarr typedefs. This wtbarr typedef is defined to match the wtbarr struct defined in WCSLIB. An array of such structs returned by the WCSLIB function wcstab() as discussed in the notes below.
[out]	status	CFITSIO status value.

Returns

CFITSIO status value.

Notes:
In order to maintain WCSLIB and CFITSIO as independent libraries it is not permissible for any CFITSIO library code to include WCSLIB header files, or vice versa. However, the CFITSIO function fits_read_wcstab() accepts an array of wtbarr structs defined in wcs.h within WCSLIB.

The problem therefore is to define the wtbarr struct within fitsio.h without including wcs.h, especially noting that wcs.h will often (but not always) be included together with fitsio.h in an applications program that uses fits_read_wcstab().

The solution adopted is for WCSLIB to define "struct wtbarr" while fitsio.h defines "typedef wtbarr" as an untagged struct with identical members. This allows both wcs.h and fitsio.h to define a wtbarr data type without conflict by virtue of the fact that structure tags and typedef names share different name spaces in C; Appendix A, Sect. A11.1 (p227) of the K&R ANSI edition states that:

Identifiers fall into several name spaces that do not interfere with one another; the same identifier may be used for different purposes, even in the same scope, if the uses are in different name spaces. These classes are: objects, functions, typedef names, and enum constants; labels; tags of structures, unions, and enumerations; and members of each structure or union individually.

Therefore, declarations within WCSLIB look like

struct wtbarr *w;

while within CFITSIO they are simply

wtbarr *w;

As suggested by the commonality of the names, these are really the same aggregate data type. However, in passing a (struct wtbarr *) to fits_read_wcstab() a cast to (wtbarr *) is formally required.

When using WCSLIB and CFITSIO together in C++ the situation is complicated by the fact that typedefs and structs share the same namespace; C++ Annotated Reference Manual, Sect. 7.1.3 (p105). In that case the wtbarr struct in wcs.h is renamed by preprocessor macro substitution to wtbarr_s to distinguish it from the typedef defined in fitsio.h. However, the scope of this macro substitution is limited to wcs.h itself and CFITSIO programmer code, whether in C++ or C, should always use the wtbarr typedef.