Header C Routines
"Pure C" Layer Routines for Headers
Headers can be associated with regions, masks, Binary Tables, etc. They
describe those entities characteristics.
The headers are similar to FITS headers, but should not be thought of such.
A header vector can contain up to three fields: a keyword field (required), a
value field (required) and a comment field (optional). The following collection
of routines manipulate the header in various ways. A description of each
routine follows.
shHdrNew
shHdrDel
shHdrGetAscii
shHdrGetDbl
shHdrGetInt
shHdrGetLogical
shHdrGetLine
shHdrGetLineCont
shHdrGetLineno
shHdrDelByLine
shHdrDelByKeyword
shHdrInsertLine
shHdrReplaceLine
shHdrInsertLogical
shHdrInsertDbl
shHdrInsertInt
shHdrInsertInt
shHdrInsertAscii
shHdrMakeLineWithDbl
shHdrMakeLineWithAscii
shHdrMakeLineWithInt
shHdrMakeLineWithLogical
shHdrCopy
This routine will return a pointer to a new header structure. The header
vector is also malloced, but the header lines are not.
C SYNTAX:
HDR *shHdrNew()
RETURNS:
Pointer to a new header - on success
NULL - otherwise
This routine will free the header passed to it. The header lines themselves,
the header vector and the header structure are all freed.
C SYNTAX:
void shHdrDel
(
HDR *a_hdr /* IN: pointer to header to free */
)
RETURNS:
NONE
This routine retrieves an alphanumeric keyword string from a header.
The calling program provides it a header pointer and a keyword to search
on. The resulting value is placed in a buffer allocated by the user that must
be large enough to hold it. It is the calling routine's responsibility to
ensure that the result buffer is indeed large enough.
C SYNTAX:
RET_CODE shHdrGetAscii
(
const HDR *a_hdr, /* IN: Header pointer */
const char *a_keyword, /* IN: Keyword to search for in header vector */
char *a_dest /* OUT: pointer to result buffer */
)
RETURNS:
SH_SUCCESS - on success
SH_HEADER_IS_NULL - if the header is null
SH_GENERIC_ERROR - otherwise
This routine retrieves a double value from a header. The calling
program provides it a header pointer and the keyword to search on.
C SYNTAX:
RET_CODE shHdrGetDbl
(
const HDR *a_hdr, /* IN: Header pointer */
const char *a_keyword, /* IN: Keyword to search for in header vector */
double *a_dest /* OUT: pointer to result buffer */
)
RETURNS:
SH_SUCCESS - on success
SH_HEADER_IS_NULL - if the header is null
SH_GENERIC_ERROR - otherwise
This routine retrieves an integer value from a header. The calling
program provides it a header pointer and the keyword to search on.
C SYNTAX:
RET_CODE shHdrGetInt
(
const HDR *a_hdr, /* IN: Header pointer */
const char *a_keyword, /* IN: Keyword to search for in header vector */
int *a_dest /* OUT: pointer to result buffer */
)
RETURNS:
SH_SUCCESS - on success
SH_HEADER_IS_NULL - if the header is null
SH_GENERIC_ERROR - otherwise
This routine retrieves a logical (1 or 0) value from a header. The
calling program provides it a header pointer and the keyword to search on.
C SYNTAX:
RET_CODE shHdrGetLogical
(
const HDR *a_hdr, /* IN: Header pointer */
const char *a_keyword, /* IN: Keyword to search for in header vector */
int *a_dest /* OUT: pointer to result buffer */
)
RETURNS:
SH_SUCCESS - on success
SH_HEADER_IS_NULL - if the header is null
SH_GENERIC_ERROR - otherwise
This routine retrieves a line from the header identified by the given
keyword. The calling program provides it a header pointer and the keyword to
search on.The resulting line is placed in a buffer that must be large enough
to hold it. It is the calling routine's responsibility to ensure that the
result buffer is indeed large enough.
C SYNTAX:
RET_CODE shHdrGetLine
(
const HDR *a_hdr, /* IN: Header pointer */
const char *a_keyword, /* IN: Keyword to search for in header vector */
char *a_dest /* OUT: pointer to result buffer */
)
RETURNS:
SH_SUCCESS - on success
SH_HEADER_IS_NULL - if the header is null
SH_GENERIC_ERROR - otherwise
This routine retrieves a line from the header identified by the given
line number. The calling program provides it a header pointer and the line
number to search on. The resulting line is placed in a buffer that must be
large enough to hold it. It is the calling routine's responsibility to ensure
that the result buffer is indeed large enough.
C SYNTAX:
RET_CODE shHdrGetLineCont
(
const HDR *a_hdr, /* IN: Header pointer */
int *a_line, /* IN: Line num to search for in header vector */
char *a_dest /* OUT: pointer to result buffer */
)
RETURNS:
SH_SUCCESS - on success
SH_HEADER_IS_NULL - if the header is null
SH_GENERIC_ERROR - otherwise
This routine retrieves the line number in the header where the specified
keyword was found. The calling program provides it a header pointer and the
keyword to search on.
C SYNTAX:
RET_CODE shHdrGetLineno
(
const HDR *a_hdr, /* IN: Header pointer */
const char *a_keyword, /* IN: Keyword to search for in header vector */
int *a_dest /* OUT: pointer to result buffer */
)
RETURNS:
SH_SUCCESS - on success
SH_HEADER_IS_NULL - if the header is null
SH_GENERIC_ERROR - otherwise
This routine deletes the requested line number from the header.
C SYNTAX:
RET_CODE shHdrDelByLine
(
HDR *a_hdr, /* MOD: Header pointer */
const int a_lineNo /* IN: line number to be deleted */
)
RETURNS:
SH_SUCCESS - on success
SH_HEADER_IS_NULL - if the header is null
SH_GENERIC_ERROR - otherwise
This routine deletes a header vector identified by keyword a_keyword.
C SYNTAX:
RET_CODE shHdrDelByKeyword
(
HDR *a_hdr, /* MOD: Header pointer */
const char *a_keyword /* IN: line to be deleted is identified by this */
) /* keyword */
RETURNS:
SH_SUCCESS - on success
SH_HEADER_IS_NULL - if header is null
SH_GENERIC_ERROR - otherwise
Insert a header vector in a header. If the header vector is null,
memory will be allocated for it.
C SYNTAX:
RET_CODE shHdrInsertLine
(
HDR *a_hdr, /* MOD: Header pointer */
const int a_lineNo, /* IN: Line number after which to insert */
const char *a_line /* IN: Vector to be inserted */
)
RETURNS:
SH_SUCCESS - on success
SH_HEADER_INSERTION_ERROR - otherwise
Insert a logical (0 or 1) value in a header vector. A valid header
vector will be created using the parameters a_key, a_value, and
a_comment and subsequently inserted in the header vector.
If the header does not have a header vector, one will be created
using shHdrInit().
C SYNTAX:
RET_CODE shHdrInsertLogical
(
HDR *a_hdr, /* MOD: Header pointer */
const char *a_key, /* IN: Header vector's keyword */
const int a_value, /* IN: Header vector's logical value */
const char *a_comment /* IN: Header vector's comment. Can be blank */
) /* or NULL */
RETURNS:
SH_SUCCESS - on success
SH_HEADER_INSERTION_ERROR - otherwise
Insert a double value in a header vector. A valid header
vector will be created using the parameters a_key, a_value, and
a_comment and subsequently inserted in the header vector.
If the header does not have a header vector, one will be created
using shHdrInit().
C SYNTAX:
RET_CODE shHdrInsertDbl
(
HDR *a_hdr, /* MOD: Header pointer */
const char *a_key, /* IN: Header vector's keyword */
const double a_value, /* IN: Header vector's double value */
const char *a_comment /* IN: Header vector's comment. Can be blank */
) /* or NULL */
RETURNS:
SH_SUCCESS - on success
SH_HEADER_INSERTION_ERROR - otherwise
Insert an integer value in a header vector. A valid header
vector will be created using the parameters a_key, a_value, and
a_comment and subsequently inserted in the header vector.
If the header does not have a header vector, one will be created
using shHdrInit().
C SYNTAX:
RET_CODE shHdrInsertInt
(
HDR *a_hdr, /* MOD: Header pointer */
const char *a_key, /* IN: Header vector's keyword */
const int a_value, /* IN: Header vector's integer value */
const char *a_comment /* IN: Header vector's comment. Can be blank */
) /* or NULL */
RETURNS:
SH_SUCCESS - on success
SH_HEADER_INSERTION_ERROR - otherwise
Insert a line in a header vector. A valid header vector will be
created using the parameters a_key, a_value, and a_comment
and subsequently inserted in the header vector. If the header does
not have a header vector, one will be created using
shHdrInit().
C SYNTAX:
RET_CODE shHdrInsertAscii
(
HDR *a_hdr, /* MOD: Header pointer */
const char *a_key, /* IN: Header vector's keyword */
const char *a_value, /* IN: Header vector's ASCII value */
const char *a_comment /* IN: Header vector's comment. Can be blank */
) /* or NULL */
RETURNS:
SH_SUCCESS - on success
SH_HEADER_INSERTION_ERROR - otherwise
Constructs a line suitable for inclusion into a header. Uses
a_keyword, a_value, and a_comment to construct a valid
line containing double data. Stores the constructed line in a_dest.
It is the calling function's responsibility to ensure that a_dest
is big enough to hold the constructed line.
C SYNTAX:
void shHdrMakeLineWithDbl
(
const char *a_keyword, /* IN: Pointer to the keyword */
const double a_value, /* IN: Data to be inserted in the header */
const char *a_comment, /* IN: Header vector's comment. Can be blank */
/* or NULL */
char *a_dest /* OUT: Pointer to buffer where the */
) /* constructed line is stored */
RETURNS:
Nothing
Constructs a line suitable for inclusion into a header. Uses
a_keyword, a_value, and a_comment to construct a valid
line containing Ascii (alphanumeric) data. Stores the constructed line in
a_dest. It is the calling function's responsibility to ensure
that a_dest is big enough to hold the constructed line.
C SYNTAX:
void shHdrMakeLineWithAscii
(
const char *a_keyword, /* IN: Pointer to the keyword */
const char *a_value, /* IN: Data to be inserted in the header */
const char *a_comment, /* IN: Header vector's comment. Can be blank */
/* or NULL */
char *a_dest /* OUT: Pointer to buffer where the */
) /* constructed line is stored */
RETURNS:
Nothing
Constructs a line suitable for inclusion into a header. Uses
a_keyword, a_value, and a_comment to construct a valid
line containing integer data. Stores the constructed line in a_dest.
It is the calling function's responsibility to ensure that a_dest
is big enough to hold the constructed line.
C SYNTAX:
void shHdrMakeLineWithInt
(
const char *a_keyword, /* IN: Pointer to the keyword */
const int a_value, /* IN: Data to be inserted in the header */
const char *a_comment, /* IN: Header vector's comment. Can be blank */
/* or NULL */
char *a_dest /* OUT: Pointer to buffer where the */
) /* constructed line is stored */
RETURNS:
Nothing
Constructs a line suitable for inclusion into a header. Uses
a_keyword, a_value, and a_comment to construct a valid
line containing logical (0 or 1) data. Stores the constructed line in
a_dest. It is the calling function's responsibility to ensure
that a_dest is big enough to hold the constructed line.
C SYNTAX:
void shHdrMakeLineWithLogical
(
const char *a_keyword, /* IN: Pointer to the keyword */
const int a_value, /* IN: Data to be inserted in the header */
const char *a_comment, /* IN: Header vector's comment. Can be blank */
/* or NULL */
char *a_dest /* OUT: Pointer to buffer where the */
) /* constructed line is stored */
RETURNS:
Nothing
Replace, in the header, line a_lineNo by the contents of
a_line.
C SYNTAX:
RET_CODE shHdrReplaceLine
(
HDR *a_hdr, /* MOD: Header pointer */
const int a_lineNo, /* IN: line number on which to insert */
const char *a_line /* IN: pointer to the line to be inserted */
)
RETURNS:
SH_SUCCESS - on success
SH_HEADER_IS_NULL - if the header is null
SH_GENERIC_ERROR - otherwise
This routine copies a header from a_inReg to a_outReg. It
runs standard checks that include ensuring that a_inReg's header is
non null, creating a header for a_outReg if one does not already
exist (using shHdrMallocForVec()).
If a header for a_outReg exists, this routine will deallocate
it.
C SYNTAX:
RET_CODE shHdrCopy
(
const HDR *a_inHdr, /* IN: Input (source) header pointer */
HDR *a_outHdr /* MOD: Output (destination) header pointer */
)
RETURNS:
SH_SUCCESS - on success
SH_HEADER_IS_NULL - if source header pointer is null