ndgFormatProv - Format the information in a provenance structure

Description:

This function returns an AST KeyMap holding a set of text strings containing information taken from the supplied provenance structure.

The returned KeyMap has an entry with key "0" that describes the NDF from which the provenance was read. It also has an entry describing each ancestor NDF. These entries have keys "1", "2", "3", etc, up to the number of ancestors in the NDF.

Each of these entries contains a pointer to another AST KeyMap which may contain any subset of the following entries (all of which are strings):

"ID" - the integer index within the ancestors array (zero for the main NDF).

"PATH" - The full path or base name for the NDF (see "base").

"DATE" - The date of creation of the NDF.

"CREATOR" - The software item that created the NDF.

"PARENTS" - A comma-separated list of indices into the ancestors array that identifies the direct parents of the NDF.

"MORE" - A summary of the contents of the MORE structure associated with the NDF.

"HISTORY" - A vector entry holding one or more KeyMaps. Each KeyMap contains items that describe an action performed on the ancestor. The actions are stored in chronological order within the vector entry. The last KeyMap in the vector describes the action that created the ancestor NDF. Any earlier KeyMaps in the vector describe any subsequent actions performed on the ancestor NDF prior to it being used in the creation of its parent. Each KeyMap contains the following scalar character entries (all taken from the corresponding record in the NDF HISTORY component):

• "DATE": The date and time of the action (e.g. "2009-JUN-24 14:00:53.752" ).

• "COMMAND": An indication of the command that performed the action (e.g. "WCSATTRIB (KAPPA 1.10-6)" ).

• "USER": The user name that performed the action (e.g. "dsb").

• "TEXT": The full text of the NDF history record. This is arbitrary, but for NDFs created by Starlink software it will usually include environment parameter values, and the full path of the command that performed the action.

Finally, the returned KeyMap has an entry with key "MXLEN" that is again a pointer to another KeyMap with the same entries listed above (except that it has no "HISTORY" entry). However, this time the entries are integers, not strings, and holds the maximum field width used to format the strings.

Invocation:

void ndgFormatProv( NdgProvenance $*$prov, int base, AstKeyMap $*$$*$keymap, int $*$status )

Arguments:

prov

An identifier for a structure holding the provenance information read from an NDF, as returned by ndgReadProv

base

If non-zero, then the PATH field in the returned KeyMap holds the base name of each NDF rather than the full path.

keymap

A location at which to returned a pointer to the returned AST KeyMap.

status

The global status.