[fitsbits] New routines for reading string keywords in CFITSIO

[William Pence]

During the recent discussion about the CONTINUE long string keyword 
proposal, it was mentioned that the CFITSIO library  support for reading 
string keyword values is currently split into 2 separate routines that 
have significantly different user interfaces. One routine is used for 
reading normal string keywords (where the string length is limited to at 
most 68 characters), and a separate routine is provided for reading long 
string keywords that span multiple header records (when using the 
CONTINUE keyword convention).   In this note, I describe a new set of 
routines that will be available in the next release of the CFITSIO 
library that will provide a more unified and transparent method for 
reading FITS string keywords of any length. (An equivalent set of 
Fortran callable wrapper routines will also be provided). If you are not 
interested in the implementation details of how CFITSIO reads FITS 
string keywords, then there is no need to read any further.

Current set of routines
-----------------------

CFITSIO currently provides 2 routines for reading string valued keywords:

1. fits_read_key_str(fitsfile *ptr, char* keyname, char* value,
                      char* comment, int *status)

This is the basic routine which reads a single FITS keyword where the 
returned string value is limited to at most 68 characters in length. 
Note that the calling program must ensure that the allocated size of the 
'value' argument is large enough to contain the returned string to avoid 
a buffer overflow error.

2. fits_read_key_longstr(fitsfile *ptr, char* keyname, char** value,
                          char* comment, int *status)

This routine supports the CONTINUE convention and can return an 
arbitrarily long string value (that is continued over multiple FITS 
header records).  The key difference with the first routine is that this 
routine internally allocates memory for the whole string value and 
returns a pointer to that memory location.  The calling routine must 
'free' that memory when it is no longer needed.

In practice it could sometimes be difficult for applications programmers 
to decide which of these routines to call because it may not be obvious 
whether the keyword uses the CONTINUE convention or not.  To remedy 
this, the following set of routines will be added to the next release of 
CFITSIO.

New routines
------------

These 2 new routines will transparently read both single and CONTINUE'd 
string keywords:

1.  fits_get_str_len(fitsfile *ptr, char* keyname, int* length,
                     int* status)

This routine simply returns the total length of the specified keyword 
value.  This can be used to determine how much space needs to be 
allocated to hold the string value before calling the next routine.

2. fits_read_key_str(fitsfile *ptr, char* keyname, int firstchar,
                  int maxchar, char* value, int* length,
                  char* comment, int *status).

This routine reads the specified keyword and returns up to 'maxchar' 
characters in the value string, starting with the 'firstchar' character. 
  This routine also returns the actual length of the returned string in 
the event that it is shorter than 'maxchar'.

Usage Notes
-----------

These 2 new routines provide a more consistent and uniform interface for 
reading FITS string keywords of any length.  Since the CONTINUE 
convention is so rarely used in practice, in the great majority of cases 
applications programs can safely assume that the keyword value will fit 
on a single header keyword and can simply call fits_read_str_key with 
firstchar = 1 and maxchar = 68 (which is exactly equivalent to calling 
the old fits_read_key_str routine).  However, if there is any doubt 
about the length of the string value, then the application program can 
first call fits_get_str_len, and then allocate an appropriately sized 
character string array that can be used in the subsequent call to 
fits_read_str_key.

In the unlikely event that the string length returned by 
fits_get_str_len is so large that it would be unwieldy to read the 
entire string at one time, then the application program has the option 
to read the string in smaller pieces, by calling fits_read_str_key 
multiple times and incrementing the value of firstchar between calls.

-Bill
-- 
____________________________________________________________________
Dr. William Pence    Astrophysicist     William.Pence at nasa.gov
NASA/GSFC Code 662     [Emeritus]       +1-301-286-4599 (voice)
Greenbelt MD 20771                      +1-301-286-1684 (fax)