FTS1_RFMOD

Reads a text file containing instructions for editing an NDF s FITS extension

Description:

This routines opens a text file and parses it to determine how to modify an NDF s FITS extension. Details of the format and its interpretation is given in the item called " File Format" . The routine returns the editing command, keyword, position, values, comment, and data type in arrays.

Invocation

CALL FTS1_RFMOD( FD, MAXMOD, NWRITE, EDITS, KEYWDS, KEYPOS, KOCCUR, POCCUR, VALUES, COMNTS, TYPES, STATUS )

Arguments

FD = INTEGER (Given)
The FIO identifier of the text file containing the editing instructions.
MAXMOD = INTEGER (Given)
The maximum number of modifications.
NWRITE = INTEGER (Returned)
The number of modifications actually made.
EDITS( MAXMOD ) = CHARACTER ( ) (Returned)
The editing commands. Thus need only be one character per element.
KEYWDS( MAXMOD ) = CHARACTER ( ) (Returned)
The FITS keywords to be modified into FITS card array. The length should be at least 48 characters to allow for hierarchical keywords.
KEYPOS( MAXMOD ) = CHARACTER ( ) (Returned)
The position keyword names. The new keywords are inserted immediately before each corresponding position keyword. The length should be at least 48 characters to allow for hierarchical keywords.
KOCCUR( MAXMOD ) = INTEGER (Returned)
The occurrences of the KEYWDS keywords to use.
POCCUR( MAXMOD ) = INTEGER (Returned)
The occurrences of the KEYPOS keywords to use.
VALUES( MAXMOD ) = CHARACTER ( ) (Returned)
The values to be given to the KEYWDS keywords. The length should be at least 68 characters to allow for the maximum length of a value.
COMNTS( MAXMOD ) = CHARACTER ( ) (Returned)
The comments of the NAME keywords to use. The length should be at least 68 characters to allow for the maximum length of a comment, but normally 50 should be adequate.
TYPES( MAXMOD ) = CHARACTER ( ) (Returned)
The data types of the values to write. These will be one of the following: _CHAR , _DOUBLE , _INTEGER , _LOGICAL , _REAL . In addition there are two special values: COMMENT to indicate that the card is a comment (so strictly it has no type), and to indicate that the data type is unknown, as occurs for a value defined by a reference keyword. The length should be at least 8 characters.
STATUS = INTEGER (Given and Returned)
The global status.

File Format

The file consists of a series of lines, one per editing instruction, although blank lines and lines beginning with a ! or # are treated as comments. Note that the order does matter, as the edits are performed in the order given.

The format is summarised below:

command keyword{[occur]}{(keyword{[occur]})} {value {comment}}

where braces indicate optional values, and occur is the occurrence of the keyword. In effect there are four fields delineated by spaces that define the edit operation, keyword, value and comment.

Field 1: This specifies the editing operation. Allowed values are Amend, Delete, Exist, Move, Null, Read, Write, and Update, and can be abbreviated to the initial letter. Delete removes a named keyword. Read causes the value of a named keyword to be displayed to standard output. Exist reports TRUE to standard output if the named keyword exists in the header, and FALSE if the keyword is not present. Move relocates a named keyword to be immediately before a second keyword. When this positional keyword is not supplied, it defaults to the END card, and if the END card is absent, the new location is at the end of the headers. Write creates a new card given a value and an optional comment. Its location uses the same rules as for the Move command. Update revises the value and/or the comment. If a secondary keyword is defined explicitly, the card may be relocated at the same time. Update requires that the keyword exists. Amend behaves as Write if the keyword in Field 2 is not already present, or as Update if the keyword exists. Null replaces the value of a named keyword with blanks.

Field 2: This specifies the keyword to edit, and optionally the position of that keyword in the header after the edit (for Move, Write, Update, and Amend edits). The new position in the header is immediately before a positional keyword, whose name is given in parentheses concatenated to the edit keyword. See " Field 1" for defaulting when the position parameter is not defined or is null.

Both the editing keyword and position keyword may be compound to handle hierarchical keywords. In this case the form is keyword1.keyword2.keyword3 etc. All keywords must be valid FITS keywords. This means they must be no more than 8 characters long, and the only permitted characters are uppercase alphabetic, numbers, hyphen, and underscore. Invalid keywords will be rejected.

Both the edit and position keyword may have an occurrence specified in brackets []. This enables editing of a keyword that is not the first occurrence of that keyword, or locate a edited keyword not at the first occurrence of the positional keyword. Note that it is not normal to have multiple occurrences of a keyword in a FITS header, unless it is blank, COMMENT or HISTORY. Any text other than a positive integer is interpreted as the first occurrence.

Use a null value ( or "" ) if you want the card to be a comment with keyword other than COMMENT or HISTORY. As blank keywords are used for hierarchical keywords, to write a comment in a blank keyword you must give a null edit keyword. These have no keyword appears before the left parenthesis or bracket, such as (), [], [2], or (EPOCH).

Field 3: This specifies the value to assign to the edited keyword in the the Amend, Write, and Update operations, or the name of the new keyword in the Rename modification. If the keyword exists, the existing value or keyword is replaced, as appropriate. The data type used to store the value is inferred from the value itself. See topic " Value Data Types" .

For the Update and Write modifications there is a special value, $V, which means use the current value of the edited keyword, provided that keyword exists. This makes it possible to modify a comment, leaving the value unaltered. In addition $V(keyword) requests that the value of the keyword given between the parentheses be assigned to the keyword being edited.

The value field is ignored when the keyword is COMMENT, HISTORY or blank and the modification is an Update or Write.

Field 4: This specifies the comment to assign to the edited keyword for the Amend, Write, and Update operations. A leading / should not be supplied.

There is a special value, $C, which means use the current comment of the edited keyword, provided that keyword exists. This makes it possible to modify a value, leaving the comment unaltered. In addition $C(keyword) requests that the comment of the keyword given between the parentheses be assigned to the edited keyword.

To obtain leading spaces before some commentary, use a quote ( ) or double quote (" ) as the first character of the comment. There is no need to terminate the comment with a trailing and matching quotation character. Also do not double quotes should one form part of the comment.

Value Data Types

The data type of the value is determined as follows:

Examples of the File Format

The best way to illustrate the options is by listing some example lines.

P AIRMASS This reports the value of keyword AIRMASS to standard output.

E FILTER This determines whether keyword FILTER exists and reports TRUE or FALSE to standard output.

D OFFSET This deletes the keyword OFFSET.

Delete OFFSET[2] This deletes any second occurrence of keyword OFFSET.

Rename OFFSET1[2] OFFSET2 This renames the second occurrence of keyword OFFSET1 to have keyword OFFSET2.

W AIRMASS 1.379 This writes a real value to new keyword AIRMASS, which will be located at the end of the FITS extension.

A AIRMASS 1.379 This writes a real value to keyword AIRMASS if it exists, otherwise it writes a real value to new keyword AIRMASS located at the end of the FITS extension.

N AIRMASS This blanks the value of the AIRMASS keyword, if it exists.

W FILTER(AIRMASS) Y This writes a logical true value to new keyword FILTER, which will be located just before the AIRMASS keyword, if it exists.

Write FILTER(AIRMASS) Y As the preceding example except that this writes a character value " Y" .

W COMMENT(AIRMASS) . Following values apply to mid-observation This writes a COMMENT card immediately before the AIRMASS card, the comment being " Following values apply to mid-observation" .

W DROCOM(AIRMASS) Following values apply to mid-observation As the preceding example but this writes to a non-standard comment keyword called DROCOM. Note the need to supply a null value.

W (AIRMASS) Following values apply to mid-observation As the preceding example but this writes to a blank-keyword comment.

U OBSERVER " Dr. Peter O Leary" Name of principal observer This updates the OBSERVER keyword with the string value " Dr. Peter O Leary" , and comment " Name of principal observer" . Note that had the value been enclosed in single quotes ( ), the apostrophe would need to be doubled.

M OFFSET This moves the keyword OFFSET to just before the END card.

Move OFFSET(SCALE) This moves the keyword OFFSET to just before the SCALE card.

Move OFFSET[2](COMMENT[3]) This moves the second occurrence of keyword OFFSET to just before the third COMMENT card.