5.8.3 General Utility Routines

The following utility routines may be useful for certain applications.

1

Return the revision number of the CFITSIO library. The revision number will be incremented with each new release of CFITSIO.  

  float fits_get_version / ffvers ( > float *version)

2

Write an 80-character message to the CFITSIO error stack. Application programs should not normally write to the stack, but there may be some situations where this is desirable.  

  void fits_write_errmsg / ffpmsg (char *err_msg)

3

Convert a character string to uppercase (operates in place).  

  void fits_uppercase / ffupch (char *string)

4

Compare the input template string against the reference string to see if they match. The template string may contain wildcard characters: '*' will match any sequence of characters (including zero characters) and '%' will match any single character in the reference string. If casesen = CASESEN = TRUE then the match will be case sensitive, otherwise the case of the letters will be ignored if casesen = CASEINSEN = FALSE. The returned MATCH parameter will be TRUE if the 2 strings match, and EXACT will be TRUE if the match is exact (i.e., if no wildcard characters were used in the match). Both strings must be 68 characters or less in length.  

  void fits_compare_str / ffcmps
       (char *templt, char *string, int casesen, > int *match, int *exact)

5

Test that the keyword name contains only legal characters (A-Z,0-9, hyphen, and underscore) or that the keyword record contains only legal printable ASCII characters    

  int fits_test_keyword / fftkey (char *keyname, > int *status)

  int fits_test_record / fftrec (char *card, > int *status)

6

Test whether the current header contains any NULL (ASCII 0) characters. These characters are illegal in the header, but they will go undetected by most of the CFITSIO keyword header routines, because the null is interpreted as the normal end-of-string terminator. This routine returns the position of the first null character in the header, or zero if there are no nulls. For example a returned value of 110 would indicate that the first NULL is located in the 30th character of the second keyword in the header (recall that each header record is 80 characters long). Note that this is one of the few CFITSIO routines in which the returned value is not necessarily equal to the status value).  

  int fits_null_check / ffnchk (char *card, > int *status)

7

Parse a header keyword record and return the name of the keyword, and the length of the name. The keyword name normally occupies the first 8 characters of the record, except under the HIERARCH convention where the name can be up to 70 characters in length.  

  int fits_get_keyname / ffgknm
      (char *card, > char *keyname, int *keylength, int *status)

8

Parse a header keyword record, returning the value (as a literal character string) and comment strings. If the keyword has no value (columns 9-10 not equal to '= '), then a null value string is returned and the comment string is set equal to column 9 - 80 of the input string.  

  int fits_parse_value / ffpsvc
      (char *card, > char *value, char *comment, int *status)

9

Construct an array indexed keyword name (ROOT + nnn). This routine appends the sequence number to the root string to create a keyword name (e.g., 'NAXIS' + 2 = 'NAXIS2')  

  int fits_make_keyn / ffkeyn
      (char *keyroot, int value, > char *keyname, int *status)

10

Construct a sequence keyword name (n + ROOT). This routine concatenates the sequence number to the front of the root string to create a keyword name (e.g., 1 + 'CTYP' = '1CTYP')  

  int fits_make_nkey / ffnkey
      (int value, char *keyroot, > char *keyname, int *status)

11

Determine the datatype of a keyword value string. This routine parses the keyword value string to determine its datatype. Returns 'C', 'L', 'I', 'F' or 'X', for character string, logical, integer, floating point, or complex, respectively.  

  int fits_get_keytype / ffdtyp
      (char *value, > char *dtype, int *status)

12

Return the class of an input header record. The record is classified into one of the following categories (the class values are defined in fitsio.h). Note that this is one of the few CFITSIO routines that does not return a status value.  

       Class  Value             Keywords
  TYP_STRUC_KEY  10  SIMPLE, BITPIX, NAXIS, NAXISn, EXTEND, BLOCKED,
                     GROUPS, PCOUNT, GCOUNT, END
                     XTENSION, TFIELDS, TTYPEn, TBCOLn, TFORMn, THEAP,
                     and the first 4 COMMENT keywords in the primary array
                     that define the FITS format.
  TYP_CMPRS_KEY  20  The experimental keywords used in the compressed
                     image format ZIMAGE, ZCMPTYPE, ZNAMEn, ZVALn,
                     ZTILEn, ZBITPIX, ZNAXISn, ZSCALE, ZZERO, ZBLANK
  TYP_SCAL_KEY   30  BSCALE, BZERO, TSCALn, TZEROn
  TYP_NULL_KEY   40  BLANK, TNULLn
  TYP_DIM_KEY    50  TDIMn
  TYP_RANG_KEY   60  TLMINn, TLMAXn, TDMINn, TDMAXn, DATAMIN, DATAMAX
  TYP_UNIT_KEY   70  BUNIT, TUNITn
  TYP_DISP_KEY   80  TDISPn
  TYP_HDUID_KEY  90  EXTNAME, EXTVER, EXTLEVEL, HDUNAME, HDUVER, HDULEVEL
  TYP_CKSUM_KEY 100  CHECKSUM, DATASUM
  TYP_WCS_KEY   110  CTYPEn, CUNITn, CRVALn, CRPIXn, CROTAn, CDELTn
                     CDj_is, PVj_ms, LONPOLEs, LATPOLEs
                     TCTYPn, TCTYns, TCUNIn, TCUNns, TCRVLn, TCRVns, TCRPXn,
                     TCRPks, TCDn_k, TCn_ks, TPVn_m, TPn_ms, TCDLTn, TCROTn
                     jCTYPn, jCTYns, jCUNIn, jCUNns, jCRVLn, jCRVns, iCRPXn,
                     iCRPns, jiCDn,  jiCDns, jPVn_m, jPn_ms, jCDLTn, jCROTn
                     (i,j,m,n are integers, s is any letter)
  TYP_REFSYS_KEY 120 EQUINOXs, EPOCH, MJD-OBSs, RADECSYS, RADESYSs
  TYP_COMM_KEY   130 COMMENT, HISTORY, (blank keyword)
  TYP_CONT_KEY   140 CONTINUE
  TYP_USER_KEY   150 all other keywords

  int fits_get_keyclass / ffgkcl (char *card)

13

Parse the 'TFORM' binary table column format string. This routine parses the input TFORM character string and returns the integer datatype code, the repeat count of the field, and, in the case of character string fields, the length of the unit string. See Appendix B for the allowed values for the returned typecode parameter. A null pointer may be given for any output parameters that are not needed.  

   int fits_binary_tform / ffbnfm
       (char *tform, > int *typecode, long *repeat, long *width,
        int *status)

14

Parse the 'TFORM' keyword value that defines the column format in an ASCII table. This routine parses the input TFORM character string and returns the datatype code, the width of the column, and (if it is a floating point column) the number of decimal places to the right of the decimal point. The returned datatype codes are the same as for the binary table, with the following additional rules: integer columns that are between 1 and 4 characters wide are defined to be short integers (code = TSHORT). Wider integer columns are defined to be regular integers (code = TLONG). Similarly, Fixed decimal point columns (with TFORM = 'Fw.d') are defined to be single precision reals (code = TFLOAT) if w is between 1 and 7 characters wide, inclusive. Wider 'F' columns will return a double precision data code (= TDOUBLE). 'Ew.d' format columns will have datacode = TFLOAT, and 'Dw.d' format columns will have datacode = TDOUBLE. A null pointer may be given for any output parameters that are not needed.  

  int fits_ascii_tform / ffasfm
      (char *tform, > int *typecode, long *width, int *decimals,
       int *status)

15

Calculate the starting column positions and total ASCII table width based on the input array of ASCII table TFORM values. The SPACE input parameter defines how many blank spaces to leave between each column (it is recommended to have one space between columns for better human readability).  

  int fits_get_tbcol / ffgabc
      (int tfields, char **tform, int space, > long *rowlen,
       long *tbcol, int *status)

16

Parse a template header record and return a formatted 80-character string suitable for appending to (or deleting from) a FITS header file. This routine is useful for parsing lines from an ASCII template file and reformatting them into legal FITS header records. The formatted string may then be passed to the fits_write_record, ffmcrd, or fits_delete_key routines to append or modify a FITS header record.  

  int fits_parse_template / ffgthd
      (char *templt, > char *card, int *keytype, int *status)

The input templt character string generally should contain 3 tokens: (1) the KEYNAME, (2) the VALUE, and (3) the COMMENT string. The TEMPLATE string must adhere to the following format:

-

The KEYNAME token must begin in columns 1-8 and be a maximum of 8 characters long. A legal FITS keyword name may only contain the characters A-Z, 0-9, and '-' (minus sign) and underscore. This routine will automatically convert any lowercase characters to uppercase in the output string. If the first 8 characters of the template line are blank then the remainder of the line is considered to be a FITS comment (with a blank keyword name).

-

The VALUE token must be separated from the KEYNAME token by one or more spaces and/or an '=' character. The datatype of the VALUE token (numeric, logical, or character string) is automatically determined and the output CARD string is formatted accordingly. The value token may be forced to be interpreted as a string (e.g. if it is a string of numeric digits) by enclosing it in single quotes.

-

The COMMENT token is optional, but if present must be separated from the VALUE token by at least one blank space and a '/' character.

-

One exception to the above rules is that if the first non-blank character in the first 8 characters of the template string is a minus sign ('-') followed by a single token, or a single token followed by an equal sign, then it is interpreted as the name of a keyword which is to be deleted from the FITS header.

-

The second exception is that if the template string starts with a minus sign and is followed by 2 tokens (without an equals sign between them) then the second token is interpreted as the new name for the keyword specified by first token. In this case the old keyword name (first token) is returned in characters 1-8 of the returned CARD string, and the new keyword name (the second token) is returned in characters 41-48 of the returned CARD string. These old and new names may then be passed to the ffmnam routine which will change the keyword name.

The keytype output parameter indicates how the returned CARD string should be interpreted:

        keytype                  interpretation
        -------          -------------------------------------------------
           -2            Rename the keyword with name = the first 8 characters of CARD
                         to the new name given in characters 41 - 48 of CARD.

           -1            delete the keyword with this name from the FITS header.

            0            append the CARD string to the FITS header if the
                         keyword does not already exist, otherwise update
                         the keyword value and/or comment field if is already exists.

            1            This is a HISTORY or COMMENT keyword; append it to the header

            2            END record; do not explicitly write it to the FITS file.

EXAMPLES: The following lines illustrate valid input template strings:

      INTVAL 7 / This is an integer keyword
      RVAL           34.6   /     This is a floating point keyword
      EVAL=-12.45E-03  / This is a floating point keyword in exponential notation
      lval F / This is a boolean keyword
                  This is a comment keyword with a blank keyword name
      SVAL1 = 'Hello world'   /  this is a string keyword
      SVAL2  '123.5'  this is also a string keyword
      sval3  123+  /  this is also a string keyword with the value '123+    '
      # the following template line deletes the DATE keyword
      - DATE
      # the following template line modifies the NAME keyword to OBJECT
      - NAME OBJECT

17

Parse the input string containing a list of rows or row ranges, and return integer arrays containing the first and last row in each range. For example, if rowlist = "3-5, 6, 8-9" then it will return numranges = 3, rangemin = 3, 6, 8 and rangemax = 5, 6, 9. At most, 'maxranges' number of ranges will be returned. 'maxrows' is the maximum number of rows in the table; any rows or ranges larger than this will be ignored. The rows must be specified in increasing order, and the ranges must not overlap. A minus sign may be use to specify all the rows to the upper or lower bound, so "50-" means all the rows from 50 to the end of the table, and "-" means all the rows in the table, from 1 - maxrows.  

    int fits_parse_range / ffrwrg(char *rowlist, long maxrows, int maxranges, >
       int *numranges, long *rangemin, long *rangemax, int *status)

18

Check that the Header fill bytes (if any) are all blank. These are the bytes that may follow END keyword and before the beginning of data unit, or the end of the HDU if there is no data unit.  

    int ffchfl(fitsfile *fptr, > int *status)

19

Check that the Data fill bytes (if any) are all zero (for IMAGE or BINARY Table HDU) or all blanks (for ASCII table HDU). These file bytes may be located after the last valid data byte in the HDU and before the physical end of the HDU.  

    int ffcdfl(fitsfile *fptr, > int *status)