PROVSHOW

Displays provenance information for an NDF

Description:

This application displays details of the NDFs that were used in the creation of the supplied NDF. This information is read from the PROVENANCE extension within the NDF, and includes both immediate parent NDFs and older ancestor NDFs (i.e. the parents of the parents, etc.).

Each displayed NDF (see Parameter SHOW) is described in a block of lines. The first line holds an integer index for the NDF followed by the path to that NDF. Note, this path is where the NDF was when the provenance information was recorded. It is of course possible that the NDF may subsequently have been moved or deleted.

The remaining lines in the NDF description are as follows.

In addition, a text file can be created containing the paths for the direct parents of the supplied NDF. See Parameter PARENTS.

Usage:

provshow ndf [show]

Parameters:

DOTFILE = FILENAME (Read)
Name of a new text file in which to store a description of the provenance tree using the “dot” format. This file can be visualised using third-party tools such as Graphviz, ZGRViewer, OmniGraffle, etc.
HIDE = _LOGICAL (Read)
If TRUE, then any ancestors which are flagged as ‘hidden’ (for example, using PROVREM) are excluded from the display. If FALSE, then all requested ancestors, whether hidden or not, are included in the display (but hidden ancestors will be highlighted as such). Note, choosing to exclude hidden ancestors may change the index displayed for each ancestor. The default is to display hidden ancestors if and only if history is being displayed (see Parameter HISTORY). []
HISTORY = _LOGICAL (Read)
If TRUE, any history records stored with each ancestor are included in the displayed information. Since the amount of history information displayed can be large, and thus swamp other information, the default is not to display history information.

When an existing NDF is used in the creation of a new NDF, the provenance system will copy selected records from the HISTORY component of the existing NDF and store them with the provenance information in the new NDF. The history records copied are those that describe operations performed on the existing NDF itself. Inherited history records that describe operations performed on ancestors of the existing NDF are not copied. [FALSE]

INEXT = LITERAL (Read)
Determines which ancestor to display next. Only used if Parameter SHOW is set to "Tree". The user is re-prompted for a new value for this parameter after each NDF is displayed. The new value should be the integer identifier for one of the parents of the currently displayed NDF. Alternatively, the string "up" can be supplied, causing the previously displayed NDF to be displayed again.
NDF = NDF (Read)
The NDF data structure.
PARENTS = FILENAME (Read)
Name of a new text file in which to put the paths to the direct parents of the supplied NDF. These are written one per line with no extra text. If null, no file is created. [!]
SHOW = LITERAL (Read)
Determines which ancestors are displayed on the screen. It can take any of the following case-insensitive values (or any abbreviation).
  • "All" –- Display all ancestors, including the supplied NDF itself.

  • "Roots" –- Display only the root ancestors (i.e. ancestors that do not themselves have any recorded parents). The supplied NDF itself is not displayed.

  • "Parents" –- Display only the direct parents of the supplied NDF. The supplied NDF itself is not displayed.

  • "Tree" –- Display the top level NDF and then asks the user which parent to display next (see Parameter INEXT). The whole family tree can be navigated in this way.

["All"]

Examples:

provshow m51
This displays information about the NDF m51, and all its recorded ancestors.
provshow m51 roots
This displays information about the root ancestors of the NDF m51.
provshow m51 parents
This displays information about the direct parents of the NDF m51.

Notes:

Related Applications

KAPPA: PROVADD, HISLIST.