General Utility Subroutines  

The following utility subroutines may be useful for certain applications:

1

Return the revision number of the fitsio library. This subroutine returns the current revision number of the FITSIO software library. The revision number will be incremented whenever any modifications or enhancements are made to the code.

        FTVERS( > version)

2

Return a code value indicating the word architecture of the computer that the program is running on. The routine compares the internal architecture used to store floating point and integer numbers and returns one of the following codes:

        FTARCH( > compid)

           compid = 1  -  VAX or Alpha VMS system
                    2  -  Decstation or Alpha OSF/1, or IBM PC
                    3  -  SUN workstation
                    4  -  IBM mainframe
                    0  -  unknown type of machine

3

Get the current system date. The day, month and year are returned as integers. The year value ranges from 00 to 99.

        FTGSDT(> day,month,year,status)

4

Return the starting byte address of the CHDU and the next HDU.

        FTGHAD(iunit, > curaddr,nextaddr)

5

Return the descriptive text string corresponding to a FITSIO error status code. The 30-character length string contains a brief description of the cause of the error.

        FTGERR(status, > errtext)

6

Return the top (oldest) 80-character error message from the internal FITSIO stack of error messages and shift any remaining messages on the stack up one level. Any FITSIO error will generate one or more messages on the stack. Call this routine repeatedly to get each message in sequence. The error stack is empty when a blank string is returned.

        FTGMSG( > errmsg)

7

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

        FTPMSG(errmsg)

8

Clear the entire error message stack. This routine is useful to clear any error message that may have been generated by a non-fatal FITSIO error (such as failing to find an optional header keyword). This routine is called without any arguments.

        FTCMSG

9

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

        FTUPCH(string)

10

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 'reference string. If CASESN = .true. then the match will be case sensitive. 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.

        FTCMPS(str_template,string,casesen, > match,exact)

11

Test that the keyword name contains only legal characters: A-Z,0-9, hyphen, and underscore.

        FTTKEY(keyword, > status)

12

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

        FTPSVC(card, > value,comment,status)

13

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

        FTKEYN(keyroot,seq_no, > keyword,status)

14

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

        FTNKEY(seq_no,keyroot, > keyword,status)

15

Determine the datatype of a keyword value string. This subroutine parses the keyword value string (usually columns 11-30 of the header record) to determine its datatype.

        FTDTYP(value, > dtype,status)

16

Parse the 'TFORM' binary table column format string. This subroutine 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. The following datatype codes are returned (the negative of the value is returned if the column contains variable-length arrays):

                Datatype                DATACODE value
                bit, X                   1
                byte, B                 11
                logical, L              14
                ASCII character, A      16
                short integer, I        21
                integer, J              41
                real, E                 42
                double precision, D     82
                complex                 83
                double complex          163

        FTBNFM(tform, > datacode,repeat,width,status)

17

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, listed above, with the following additional rules: integer columns that are between 1 and 4 characters wide are defined to be short integers (code = 21). Wider integer columns are defined to be regular integers (code = 41). Similarly, Fixed decimal point columns (with TFORM = 'Fw.d') are defined to be single precision reals (code = 42) if w is between 1 and 7 characters wide, inclusive. Wider 'F' columns will return a double precision data code (= 82). 'Ew.d' format columns will have datacode = 42, and 'Dw.d' format columns will have datacode = 82.

        FTASFM(tform, > datacode,width,decimals,status)

18

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).

        FTGABC(tfields,tform,space, > rowlen,tbcol,status)

19

Parse a template string and return a formatted 80-character string suitable for appending to (or deleting from) a FITS header file. This subroutine 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 FTPREC, FTMCRD, or FTDKEY subroutines to append or modify a FITS header record.

        FTGTHD(template, > card,hdtype,status)

The input TEMPLATE 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. 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). A legal FITS keyword name may only contain the characters A-Z, 0-9, and '-' (minus sign) and underscore. This subroutine will automatically convert any lowercase characters to uppercase in the output string. If KEYNAME = 'COMMENT' or 'HISTORY' then the remainder of the line is considered to be a FITS COMMENT or HISTORY record, respectively.

-

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. A leading '/' character may be used to mark the beginning of the comment field, otherwise the comment field begins with the first non-blank character following the value token.

-

One exception to the above rules is that if the first non-blank character in 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 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 FTMNAM subroutine which will change the keyword name.

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

        hdtype                  interpretation
        ------           -------------------------------------------------
           -2            Modify the name of the keyword given in CARD(1:8)
                         to the new name given in CARD(41:48)

           -1            CARD(1:8) contains the name of a keyword to be deleted
                         from the FITS header.

            0            append the CARD string to the FITS header if the
                         keyword does not already exist, otherwise update
                         the value/comment if the keyword is already present
                         in the header.

            1            simply append this keyword to the FITS header (CARD
                         is either a HISTORY or COMMENT keyword).

            2            This is a FITS END record; it should not be written
                         to the FITS header because FITSIO automatically
                         appends the END record when the header is closed.

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