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
  • 
    
    

    shHdrNew

    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
    
    
    

    shHdrDel

    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
    
    
    

    shHdrGetAscii

    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
    
    
    

    shHdrGetDbl

    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
    
    
    

    shHdrGetInt

    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
    
    
    
    

    shHdrGetLogical

    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
    
    
    

    shHdrGetLine

    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
    
    
    

    shHdrGetLineCont

    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
    
    
    

    shHdrGetLineno

    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
    
    
    

    shHdrDelByLine

    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
    
       
    

    shHdrDelByKeyword

    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
    
    
    

    shHdrInsertLine

    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
    
    
    

    shHdrInsertLogical

    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
    
    
    

    shHdrInsertDbl

    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
    
    
    

    shHdrInsertInt

    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
    
    
    

    shHdrInsertAscii

    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
    
    
    

    shHdrMakeLineWithDbl

    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
    
    
    

    shHdrMakeLineWithAscii

    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
    
    
    

    shHdrMakeLineWithInt

    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
    
    
    

    shHdrMakeLineWithLogical

    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
    
    
    

    shHdrReplaceLine

    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
    
    
    

    shHdrCopy

    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