cdds_out - initialize output DDS dictionary for binary data.

SYNOPSIS

#include "cdds.h"

const char * cdds_out(alias, value, history);

const char *alias
const char *value
const char *history

[ Description | Input | Output | Examples ]

DESCRIPTION

cdds_out initializes a dictionary for output binary data. If an output dictionary name is specified, any existing contents are discarded. Initialization includes a copy of the dictionary named by history. One dictionary name is returned as the function value. The output dictionary is selected for print mode, before cdds_out returns. The history dictionary, if specified, is selected for scan 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_out accepts a dictionary name either indirectly via alias or by default via value.

Multiple 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_out ignores the default, if value is "stdout:", and "par:" defines "alias_data".

The history argument should name a dictionary that contains the processing history. The history is copied when a new dictionary is created. If there is no previous history, then create a basic one using "cdds_in("","",title);".

OUTPUT

A constant character pointer is returned containing the opened dictionary name and the dictionary is setup for printing definitions.

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

EXAMPLES

            
const char *out_dict;
                        
/* derive output dictionary from input */
out_dict = cdds_out("out", "stdout:", in_dict);
Some applications create output, but do not require input. The processing history can be initialized by calling cdds_in with null arguments. Once initialized, it can be passed to cdds_out like a normal input history. For example: 
const char *in_dict, *out_dict;
            
/* begin a new processing history */
in_dict = cdds_in("", "", "Program: processing from scratch");
out_dict = cdds_out("out", "stdout:", in_dict);
Some applications require intermediate dictionaries. They may be used to describe internal buffer formats or temporary data files. Intermediate dictionaries can be initialized by calling cdds_out. All processing should be reflected in the accumulated history. For example: 
            
const char *in_dict, *buf_dict, *out_dict, *vel_dict;
           
/* open input dictionary */
in_dict = cdds_in("in", "stdin:", title);
...            
/* create intermediate "buf" dictionary */            
buf_dict = cdds_out("", "", in_dict);            
...            
/* open output dictionary */            
out_dict = cdds_out("out", "stdout:", buf_dict);            
...
Some applications produce auxiliary data, in addition to the primary output. cdds_out is used to initialize these dictionaries. The "out" alias and "stdout:"" default value should be reserved for the primary output data. Typical alias names for auxiliary output are "vel", "geom", "zmap", etc. Auxiliary output may not have a reasonable default value. For example: 
            
const char *in_dict, *model_dict;            
            
/* auxiliary output velocity model dictionary */            
model_dict = cdds_out("vel", "", in_dict);

SEE ALSO

cdds_dict Select DDS dictionary and mode

AUTHOR

R. L. Selzler, EPTG (Oct 1995)