ndgGetProv - Create a KeyMap holding information about an ancestor

Description:

This function returns information about a specified ancestor in the supplied provenance structure.

Invocation:

result = ndgGetProv( NdgProvenance $*$prov, int ianc, HDSLoc $*$$*$more, int $*$status )

Arguments:

prov

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

ianc

The index of the ancestor NDF for which information should be returned. A value of zero will result in information being returned that describes the NDF from which the provenance information was read. Otherwise, the "ianc" value is used as an index into the ANCESTORS array. No error is reported if "ianc" is too large, but a NULL pointer will be returned as the function value.

more

The location at which to return a pointer to a locator for a temporary HDS object containing a full deep copy of the MORE structure associated with the requested ancestor. The returned locator should be annulled using datAnnul when no longer needed. A NULL pointer may be supplied for this argument if the MORE structure is not needed. A NULL pointer will be returned if the requested ancestor has no MORE component. Note, the returned object will be assigned an arbitrary HDS Name, which will not in general be "MORE".

status

The global status.

Returned Value:

A pointer to an AST KeyMap containing entries with the following

keys and values:

- "PATH": A string holding the path of the ancestor NDF.

- "DATE": A string holding the formatted UTC date and time at

which the provenance information for the ancestor NDF was recorded.

- "CREATOR": A string identifying the software that created the

ancestor NDF.

- "PARENTS": A 1D vector of integers that are the indices of

the immediate parents of the ancestor.

- "MORE": A KeyMap containing any scalar or vector primitive

values stored at the top level of the associated HDS MORE structure. The HDS name of the component is used as the key. The full contents of the MORE structure are returned by the "more" argument (see above).

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

If the specified ancestor does not have any of these items of

information, then the corresponding entry will not be present

in the returned KeyMap. For instance, if the ancestor has no

immediate parent NDFs, then the "PARENTS" entry will not be

present in the KeyMap. A NULL pointer will be returned if the

NDF has no provenance extension, or if "ianc" is outside the

bounds of the ANCESTORS array (and is not zero). The returned

KeyMap pointer should be annulled when it is no longer needed,

either by calling astAnnul explicitly, or by relying on astEnd

to annul it (together with all the other AST Objects created in

the current AST Object context).