Data Dictionary System: Developers "C" Api (cdds

cdds_mod - initialize DDS dictionary for modification of binary data.

SYNOPSIS

#include "cdds.h"

const char * cdds_mod(alias, value, title, history);

: const char *alias
const char *value
const char *title
const char *history

[ Description | Input | Output | Examples ]

DESCRIPTION

cdds_mod modifies an existing dictionary, or initializes a new one if it does not exist. If the dictionary already exists, the title definitions and "par:" dictionary are appended to it. If the dictionary does not exist, it is initialized with a copy of the history dictionary. One dictionary name is returned as the function value. The dictionary is selected for scan mode, before cdds_mod returns. No dictionary is selected for print mode.

Applications may update the dictionary contents by appending (print) definitions. The cdds_open function may also update the dictionary. Changes are frozen, after the binary data is opened.

Note: This function changes the scan and print dictionary selection. It implicitly calls cdds_dict to select new names and modes. After a dictionary is initialized, it may be switched between scan and print modes by calling cdds_dict.

INPUT

cdds_mod accepts a dictionary name either indirectly via alias or by default via value.

Mutiple definition names, delimited by white space, may be specified by alias. If specified, the "par:" dictionary is searched. If a definition is found, its value is taken as a dictionary name. This feature is disabled, if a null alias is specified (i.e. NULL, zero length string, or a string that only contains white space).

A default dictionary name may be specified by value. The default is used if the "par:" dictionary does not define alias, or a null alias is specified. If there is no appropriate default, then a null value should be specified. A temporary dictionary is created, if an explicit name is not available.

The value default is ignored in special cases. These exceptions make it convenient to use DDS programs with standard formats and non-DDS applications. cdds_mod ignores the default, if value is "stdin:" or "stdout:".

The title argument should provide a brief (one line) description of the application program. The title is accumulated in the history, along with other definitions (it is not used if a new dictionary is being created). For example:

...previous history
DDS_SENTRY= $Revision: 57 $ $Date: 2009-02-11 17:09:37 -0600 (Wed, 11 Feb 2009) $
********************************************
******************* TITLE ******************
********************************************
cmd_title=  "bridge, convert seismic data"
cmd_name= /dist/Linux/2.6/mbs/prod/i686/bridge
cmd_rev= 1.10
cmd_user= DoeJohnw
cmd_date= Mon Oct 23 10:24:20 2006
cmd_host= machine2
cmd_cwd= /data/line2
cmd_pid= 6753
alias:sep_in= in
$size=
$origin=
$delta=
$units=
dds_history{= par:
...contents of par: dictionary
dds_history}= par:

The history argument should name a dictionary that contains the processing history. The history is copied when a new dictionary is created, otherwise it is not used.

OUTPUT

A constant character pointer is returned containing the opened dictionary name and the dictionary is setup for printing definitions if it is being created; otherwise it is setup for scaning.

The dictionary is closed and the memory is freed when the associated binary file is closed. However, if the memory for the output dictionary names must be freed then use cdds_free instead of any other system 'free' routine.

EXAMPLES

const char *mod_dict;

/* create/update velocity model dictionary */
mod_dict = cdds_mod("vel", "model", "model update", in_dict);

AUTHOR

R. L. Selzler, EPTG (Oct 1995)