gphistprms, gphistadd, gphistxfer - dataset history processing

SYNOPSIS

#include <gp.h>
#include <hist.h>
#include <terrno.h>

int gphistprms(set)
SETP set;

int gphistadd(set, text, len)
SETP set;
char *text;
int len;

int gphistxfer(fromset, destset, frompath)
SETP fromset, toset;
char *frompath;

DESCRIPTION

The processing history of a dataset consists of

The list of commands, with their parameters and input datasets, used to create or modify the dataset

The processing history of each of the input datasets

By convention, the processing history of a dataset is stored in a TDF history attribute, C_HISTORY, defined in include/hist.h.

gphistprms appends the description of the current command, with its parameters, to an output dataset's history.

output_history = output_history command parameter-list HIST_REC

gphistadd appends arbitrary text to the history of an output dataset.

output_history = output_history text HIST_REC

gphistxfer appends the history of an input dataset to the history of an output dataset.

output_history = output_history HIST_DOWN input_path HIST_NAME input_history HIST_UP HIST_REC

HIST_DOWN, HIST_UP, HIST_NAME and HIST_REC are special characters defined in include/hist.h, and are used when parsing a dataset's history.

All three functions create a history attribute in the output dataset if one does not already exist.

RETURN VALUES

All three functions return 0 if successful. Otherwise they return -1 and set terrno to the appropriate error code.

ERRORS

Errors encountered by these functions are typically TDF related and are defined in include/gp.h. Also, errors related to parameter processing are possible; status codes for these errors are defined in include/uif.h.

EXAMPLES

The following examples illustrate how application routines are expected to initialize and propagate processing history.

Creation

:
nfiles = cmdform(argc, argv, ...
:
outset = gpcreate(outpath, ...
:
if (gphistprms(outset) < 0) ...;
:
/* for each input dataset */
:
if (gphistxfer(inset[i], inset, inpath) < 0) ...;
:
if (gpclose(outset) < 0) ...;

Edit In Place

:
nfiles = cmdform(argc, argv, ...
:
outset = gpopen(outpath, ...
:
if (gphistprms(outset) < 0) ...
:
if (gpclose(outset) < 0) ...;
:

FILES

include/gp.h, include/hist.h, include/terrno.h, lib/libcdf.a, lib/libuif.a

SEE ALSO

audit, datasets, gperr

NOTES

None.

Last Update: $Date: 1999/05/10 20:56:49 $