FTS1_EDFEX

Edits non-reserved keyword cards in a FITS extension of an NDF

Description:

This subroutine edits a number of non-reserved keyword cards in the FITS extension of an NDF file. This subroutine inserts, updates, moves, deletes, reports, and tests the existence of a number of keyword cards in the FITS extension of an NDF. The occurrence of keywords may be defined, when there are more than one cards of the same name. The location of each insertion or move is immediately before some occurrence of a corresponding keyword.

This routine itself merely deals with accessing and enlarging the FITS extension, obtaining worksapce, and being able to pass the mapped character arrays in the desired order to routine FTS1_EDKEY via a dummy routine. FTS1_EDKEY actually performs the editing; look there for more details of the editing functions and rules.

Invocation

CALL FTS1_EDFEX( NKEY, EDITS, NAMES, PSTNS, KOCCUR, POCCUR, VALUES, COMNTS, TYPES, FTSLOC, THERE, STATUS )

Arguments

NKEY = INTEGER (Given)
The number of keyword cards to be inserted into the FITS extension.
EDITS( NKEY ) = CHARACTER ∗ ( ∗ ) (Given)
The editing commands. These need only be one character per element. Allowed values are ’ Amend’ , ’ Delete’ , ’ Exist’ , ’ Move’ , ’ Null’’ , ’ Rename’ , ’ Print’ , ’ Update’ , and ’ Write’ , which can be abbreviated to the initial letter.

’ Amend’ acts as ’ Update’ if the keyword exists, but as ’ Write’ if the keyword is absent.

’ Delete’ removes a named keyword.

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

’ Null’ nullifies the value of the named keyword. Spaces substitute the keyword’ s value.

’ Print’ causes the value of a named keyword to be displayed to standard output. This will be a blank for a comment card.

’ Rename’ renames a keyword, using the value as the new keyword.

’ Update’ revises the value and/or the comment. If a secondary keyword is defined explicitly, the card may be relocated at the same time. If the secondary keyword does not exist, the card being edited is not moved. Update requires that the keyword being edited exists.

’ Write’ creates a new card given a value and an optional comment. Its location uses the same rules as for the Move command.

NAMES( NKEY ) = CHARACTER ∗ ( ∗ ) (Given)
The names of the keywords to be edited in the FITS card array. A name may be compound to handle hierarchical keywords, and it has the form keyword1.keyword2.keyword3 etc. The maximum number of keywords per FITS card is 20. Each keyword must be no longer than 8 characters, and be a valid FITS keyword comprising alphanumeric characters, hyphen, and unsderscore. Any lowercase letters are converted to uppercase and blanks are removed before inserted or comparison with the existing keywords.

The keywords ’’ , ’ COMMENT’ , and ’ HISTORY’ are comment cards and do not have a value.

The keyword must exist except for the Write and Exist commands.

PSTNS( NKEY ) = CHARACTER ∗ ( ∗ ) (Given)
The position keyword names. A position name may be compound to handle hierarchical keywords, and it has the form keyword1.keyword2.keyword3 etc. The maximum number of keywords per FITS card is twenty. Each keyword must be no longer than eight characters. When locating the position card, comparisons are made in uppercase and with the blanks removed.

The new keywords are inserted immediately before each corresponding position keyword. If any name in it does not exist in FITS array, the consequences will be as follows. In the Write, Amend (new keyword), and Move edits its corresponding keyword will be inserted just before the END card or appended to FITS array when the END card does not exist; however, the card is not relocated for an Update or Amend (with an existing keyword) edit. If two or more new cards have the same position name, they will all be put just before the position name in the same order as they are in NAMES.

A positional keyword is used by the Move, Write, Amend, and Update editing commands.

KOCCUR( NKEY ) = INTEGER (Given)
The occurrences of the NAMES keywords to use. Values less than or equal to 1 will manipulate the first occurrence of the keyword to insert.
POCCUR( NKEY ) = INTEGER (Given)
The occurrences of the PSTNS keywords to use. Values less than or equal to 1 will situate the inserted keyword immediately before the first occurrence of the positional keyword.
VALUES( NKEY ) = CHARACTER ∗ ( ∗ ) (Given)
The new values of the NAMES keywords for the Update and Write editing commands. The special value ’$V’ means use the current value of the NAMES keyword. 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. This positional keyword must exist and have a value for a Write edit; whereas the FITS-header value is unchanged for Update if there are problems with this positional keyword.

For a Rename edit, VALUES has a different meaning; in this case it stores the replacement keyword name.

COMNTS( NKEY ) = CHARACTER ∗ ( ∗ ) (Given)
The comments to be written to the NAMES keywords for the Update and Write editing commands. The special value ’$C’ means use the current comment. In addition $C(keyword) requests that the comment of the keyword given between the parentheses be assigned to the keyword being edited. If this positional keyword does not exist the comment is unchanged for Update, and is blank for a Write edit.
TYPES( NKEY ) = CHARACTER ∗ ( ∗ ) (Given)
The data types of the values to Write or Update. This does allow some numeric or logical values to be written as strings. 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.
FTSLOC = CHARACTER ∗ ( ∗ ) (Given)
The locator to the FITS extension of the NDF.
THERE = LOGICAL (Returned)
Result of final " Exist" operation.
STATUS = INTEGER (Given and Returned)
The global status.

Prior Requirements

Unless all edits are read-only, the The FITS extension is mapped for update access. It therefore must have some values assigned before using the routine.