NDG_GETPROV - Create a KeyMap holding information about an ancestor

Description:

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

Invocation:

CALL NDG_GETPROV( IPROV, IANC, KM, MORE, STATUS )

Arguments:

IPROV = INTEGER (Given)

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

IANC = INTEGER (Given)

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 identifier will be returned as the function value.

KM = INTEGER (Returned)

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

MORE = CHARACTER $*$ (DAT__SZLOC) (Returned)

A locator for a temporary HDS object containing a full deep copy of each component of the MORE structure associated with the requested ancestor. The returned locator should be annulled using DAT_ANNUL when no longer needed. A value of DAT__NOLOC 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 = INTEGER (Given and Returned)

The global status.