6.4.3 Write Keyword Subroutines

1

Put (append) an 80-character record into the CHU.

        FTPREC(unit,card, > status)

2

Put (append) a COMMENT keyword into the CHU. Multiple COMMENT keywords will be written if the input comment string is longer than 72 characters.

        FTPCOM(unit,comment, > status)

3

Put (append) a HISTORY keyword into the CHU. Multiple HISTORY keywords will be written if the input history string is longer than 72 characters.

        FTPHIS(unit,history, > status)

4

Put (append) the DATE keyword into the CHU. The keyword value will contain the current system date as a character string in 'dd/mm/yy' format. If a DATE keyword already exists in the header, then this subroutine will simply update the keyword value in-place with the current date.

        FTPDAT(unit, > status)

5

Put (append) a new keyword of the appropriate datatype into the CHU. Note that FTPKYS will only write string values up to 68 characters in length; longer strings will be truncated. The FTPKLS routine can be used to write longer strings, using a non-standard FITS convention. The E and D versions of this routine have the added feature that if the 'decimals' parameter is negative, then the 'G' display format rather then the 'E' format will be used when constructing the keyword value, taking the absolute value of 'decimals' for the precision. This will suppress trailing zeros, and will use a fixed format rather than an exponential format, depending on the magnitude of the value.

        FTPKY[JKLS](unit,keyword,keyval,comment, > status)
        FTPKY[EDFG](unit,keyword,keyval,decimals,comment, > status)

6

Put (append) a string valued keyword into the CHU which may be longer than 68 characters in length. This uses the Long String Keyword convention that is described in the "Usage Guidelines and Suggestions" section of this document. Since this uses a non-standard FITS convention to encode the long keyword string, programs which use this routine should also call the FTPLSW routine to add some COMMENT keywords to warn users of the FITS file that this convention is being used. FTPLSW also writes a keyword called LONGSTRN to record the version of the longstring convention that has been used, in case a new convention is adopted at some point in the future. If the LONGSTRN keyword is already present in the header, then FTPLSW will simply return and will not write duplicate keywords.

        FTPKLS(unit,keyword,keyval,comment, > status)
        FTPLSW(unit, > status)

7

Put (append) a new keyword with an undefined, or null, value into the CHU. The value string of the keyword is left blank in this case.

        FTPKYU(unit,keyword,comment, > status)

8

Put (append) a numbered sequence of keywords into the CHU. One may append the same comment to every keyword (and eliminate the need to have an array of identical comment strings, one for each keyword) by including the ampersand character as the last non-blank character in the (first) COMMENTS string parameter. This same string will then be used for the comment field in all the keywords. (Note that the SPP version of these routines only supports a single comment string).

        FTPKN[JKLS](unit,keyroot,startno,no_keys,keyvals,comments, > status)
        FTPKN[EDFG](unit,keyroot,startno,no_keys,keyvals,decimals,comments, >
                   status)

9

Copy an indexed keyword from one HDU to another, modifying the index number of the keyword name in the process. For example, this routine could read the TLMIN3 keyword from the input HDU (by giving keyroot = "TLMIN" and innum = 3) and write it to the output HDU with the keyword name TLMIN4 (by setting outnum = 4). If the input keyword does not exist, then this routine simply returns without indicating an error.

        FTCPKY(inunit, outunit, innum, outnum, keyroot, > status)

10

Put (append) a 'triple precision' keyword into the CHU in F28.16 format. The floating point keyword value is constructed by concatenating the input integer value with the input double precision fraction value (which must have a value between 0.0 and 1.0). The FTGKYT routine should be used to read this keyword value, because the other keyword reading subroutines will not preserve the full precision of the value.

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

11

Write keywords to the CHDU that are defined in an ASCII template file. The format of the template file is described under the ftgthd routine below.

        FTPKTP(unit, filename, > status)

12

Append the physical units string to 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.

     VELOCITY=                 12.3 / [km/s] orbital speed

        FTPUNT(unit,keyword,units, > status)