Reads a text file containing instructions for editing an NDF FTS1_RFMOD
’
s FITS extension
’
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. ’
_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. 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.
Values enclosed in quotes (’
) or doubled quotes ("
) are strings. Note that numeric or logical string
values must be quoted to prevent them being converted to a numeric or logical value in the FITS
extension.
Otherwise type conversions of the first word after the keywords are made to integer, double precision, and logical types in turn. If a conversion is successful, that becomes the data type. In the case of double precision, the type is set to real when the number of significant digits only warrants single precision. If all the conversions failed the value is deemed to be a string.
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.