[fitsbits] New routines for reading string keywords in CFITSIO

[Peter Weilbacher]

Dear Bill,

you say that the new set of routines will be /added/ to CFITSIO. But
since function (2) of the new routines has the same name as function (1)
of the existing routines (and this is not C++), this means that in fact
you are /replacing/ the current routines, right?
Or was this just a typo and the new function will actually get a
different name?

Anyway, I cannot think of a case which would not work with your new API.

Cheers,
   Peter.

On Wed, 23 Mar 2016, William Pence wrote:

> 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. Peter M. Weilbacher             http://www.aip.de/People/PWeilbacher
Phone +49 331 74 99-667                       encryption key ID 7D6B4AA0
------------------------------------------------------------------------
Leibniz-Institut für Astrophysik Potsdam (AIP)
An der Sternwarte 16, D-14482 Potsdam

Vorstand: Prof. Dr. Matthias Steinmetz, Matthias Winker
Stiftung bürgerlichen Rechts, Stiftungsverz. Brandenburg: 26 742-00/7026