FTS1_EDKEY

Edits keywords in a FITS card array

Description:

This subroutine inserts, updates, moves, deletes, reports, and tests the existence of a number of keyword cards in a FITS-header array. 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. The routine returns the modified FITS-header array.

Invocation

CALL FTS1_EDKEY( NOCARD, NKEY, MXCARD, EDITS, NAMES, PSTNS, KOCCUR, POCCUR, VALUES, COMNTS, TYPES, FTSCAR, ACTNUM, IARY1, IARY2, CARY, EXISTS, STATUS )

Arguments

NOCARD = INTEGER (Given)
Number of cards in the original FITS array.
NKEY = INTEGER (Given)
The number of keyword cards to be inserted into the FITS-header array.
MXCARD = INTEGER (Given)
Maximum number of cards in the resultant FITS array. This must be not less than NOCARD + NKEY + 1.
EDITS( MAXMOD ) = CHARACTER ( ) (Returned)
The editing commands. Allowed values are Amend , Delete , Exist , Move , Rename , Print , Update , and Write . Each element 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 twenty. Each keyword must be no longer than eight characters, and be a valid FITS keyword comprising alphanumeric characters, hyphen, and underscore. 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 Amend, 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. edited.

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 Amend, 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 eight characters.
FTSCAR( MXCARD ) = CHARACTER ( ) (Given and Returned)
On entry its first NOCARD elements hold the original FITS cards. On exit, its first ACTNUM elements hold the FITS cards after the insersion.
ACTNUM = INTEGER (Returned)
The actual number of cards in the FITS array after inserting.
IARY1( MXCARD ) = INTEGER (Returned)
The first temporary working space.
IARY2( MXCARD ) = INTEGER (Returned)
The second temporary working space.
CARY( MXCARD ) = CHARACTER ( ) (Returned)
A temporary working space.
EXISTS = LOGICAL (Returned)
The result of the last " Exist" operation.
STATUS = INTEGER (Given and Returned)
The global status.

Notes: