cdds_in - initialize input DDS dictionary for binary data.

SYNOPSIS

#include "cdds.h"

const char * cdds_in(alias, value, title);

const char *alias
const char *value
const char *title

[ Description | Input | Output | Examples ]

DESCRIPTION

cdds_in initializes a dictionary for input binary data. A temporary dictionary is used so that input files are not changed. It contains the title definitions and a copy of the "par:" dictionary. The function returns a string naming the input dictionaries (temporary and input history, if any). These dictionaries are selected for scan mode, before cdds_in returns. No dictionary is selected for print mode.

Applications may update the temporary dictionary contents by appending (print) definitions. The cdds_open function may also update the dictionary.

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_in accepts a dictionary name either indirectly via alias or by a 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. 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= DoeJohn 
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:

OUTPUT

A constant character pointer is returned containing a temporary dictionary name and the opened input dictionary name. The dictionaries are setup for scaning definitions but it changed to print mode, any new definitions will be added to the temporary dictionary. This is done so that any new definitions will not modify the input dataset.

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 *in_dict;

/* initialize input dictionary */
in_dict = cdds_in("in", "stdin:", "filt processing");
Some applications consume auxiliary data, in addition to the primary input. cdds_in is used to initialize these dictionaries. The "in" alias and "stdin:"" default value should be reserved for the primary input data. Typical alias names for auxiliary input are "vel", "zmap", "geom", etc. Auxiliary input may not have a reasonable default value. For example: 
const char *model_dict;
            
/* auxiliary input model dictionary */
vel_dict = cdds_in("vel", "", "migvz: migrate data via model");
Some applications create output, but do not require input. The processing history can be initialized by calling cdds_in. Once initialized, it can be passed to cdds_out like a normal input history. For example: 
const char *in_dict;
            
/* begin a new processing history */
in_dict = cdds_in("", "", "program: processing from scratch");

SEE ALSO

cdds_dict Select DDS dictionary and mode

AUTHOR

R. L. Selzler, EPTG (Oct 1995)