6.4.5 Read Keyword Subroutines

These routines return the value of the specified keyword(s). Wild card characters (*, ?, or #) may be used when specifying the name of the keyword to be read: a '?' will match any single character at that position in the keyword name and a '*' will match any length (including zero) string of characters. The '#' character will match any consecutive string of decimal digits (0 - 9). Note that when a wild card is used in the input keyword name, the routine will only search for a match from the current header position to the end of the header. It will not resume the search from the top of the header back to the original header position as is done when no wildcards are included in the keyword name. If the desired keyword string is 8-characters long (the maximum length of a keyword name) then a '*' may be appended as the ninth character of the input name to force the keyword search to stop at the end of the header (e.g., 'COMMENT *' will search for the next COMMENT keyword). The ffgrec routine may be used to set the starting position when doing wild card searches.

1

Get the nth 80-character header record from the CHU. The first keyword in the header is at key_no = 1; if key_no = 0 then this subroutine simple moves the internal pointer to the beginning of the header so that subsequent keyword operations will start at the top of the header; it also returns a blank card value in this case.

        FTGREC(unit,key_no, > card,status)

2

Get the name, value (as a string), and comment of the nth keyword in CHU. This routine also checks that the returned keyword name (KEYWORD) contains only legal ASCII characters. Call FTGREC and FTPSVC to bypass this error check.

        FTGKYN(unit,key_no, > keyword,value,comment,status)

3

Get the 80-character header record for the named keyword

        FTGCRD(unit,keyword, > card,status)

4

Get the next keyword whose name matches one of the strings in 'inclist' but does not match any of the strings in 'exclist'. The strings in inclist and exclist may contain wild card characters (*, ?, and #) as described at the beginning of this section. This routine searches from the current header position to the end of the header, only, and does not continue the search from the top of the header back to the original position. The current header position may be reset with the ftgrec routine. Note that nexc may be set = 0 if there are no keywords to be excluded. This routine returns status = 202 if a matching keyword is not found.

        FTGNXK(unit,inclist,ninc,exclist,nexc, > card,status)

5

Get the literal keyword value as a character string. Regardless of the datatype of the keyword, this routine simply returns the string of characters in the value field of the keyword along with the comment field.

        FTGKEY(unit,keyword, > value,comment,status)

6

Get a keyword value (with the appropriate datatype) and comment from the CHU

        FTGKY[EDJKLS](unit,keyword, > keyval,comment,status)

7

Read a string-valued keyword and return the string length, the value string, and/or the comment field. The first routine, FTGKSL, simply returns the length of the character string value of the specified keyword. The second routine, FTGSKY, also returns up to maxchar characters of the keyword value string, starting with the firstchar character, and the keyword comment string. The length argument returns the total length of the keyword value string regardless of how much of the string is actually returned (which depends on the value of the firstchar and maxchar arguments). These routines support string keywords that use the CONTINUE convention to continue long string values over multiple FITS header records. Normally, string-valued keywords have a maximum length of 68 characters, however, CONTINUE'd string keywords may be arbitrarily long.

       FTGKSL(unit,keyword, > length,status)
       FTGSKY(unit,keyword,firstchar,maxchar,> keyval,length,comment,status)

8

Get a sequence of numbered keyword values. These routines do not support wild card characters in the root name.

        FTGKN[EDJKLS](unit,keyroot,startno,max_keys, > keyvals,nfound,status)

9

Get the value of a floating point keyword, returning the integer and fractional parts of the value in separate subroutine arguments. This subroutine may be used to read any keyword but is especially useful for reading the 'triple precision' keywords written by FTPKYT.

        FTGKYT(unit,keyword, > intval,dblval,comment,status)

10

Get the physical units string in an existing keyword. This routine uses a local convention, shown in the following example, in which the keyword units are enclosed in square brackets in the beginning of the keyword comment field. A blank string is returned if no units are defined for the keyword.

    VELOCITY=                 12.3 / [km/s] orbital speed

        FTGUNT(unit,keyword, > units,status)