cdds_dict - select DDS dictionary and mode.

---

SYNOPSIS

int cdds_dict(names, mode);

const char * names
const char * mode

[ Description | Input | Output | Examples ]

DESCRIPTION

NOTE: Other DDS API functions may implicitly call cdds_dict. If they change dictionary selection, their documentation should clearly say so. In particular see cdds_in, cdds_out, cdds_mod and cdds_open.

cdds_scan... reads definitions from the input dictionaries. Input dictionaries are selected by the most recent call to cdds_dict with "scan" mode. Any dictionaries previously selected for scanning are supsended and replaced by names. Multiple dictionaries may be specified by names. Their precedence is left-to-right; the first dictionary has precedence over subsequent ones. If a name is not specified, subsequent cdds_scan... calls will return EOF.

cdds_print... appends definitions to the output dictionary. The output dictionary is selected by the most recent call to cdds_dict with "print" mode. Any dictionary previously selected for printing is supsended and replaced by names. If multiple names are specified, only the first is selected. If a name is not specified, subsequent cdds_print... calls will return EOF.

If the same dictionary is selected for both scan and print modes, the most recent request is honored. This prevents a dictionary from being open for both input and output simultaneously. Dictionaries don't need to be explicitly suspended when switching between scan and print modes.

INPUT

dictionary   nominal initialization.
filename     Definitions read from filename.
stdin:       Definitions read from standard input.
stdout:      Definitions read from standard output.
cmd:         Command line definitions.
par:         Command line and "par= file ..." definitions.
env:         All environment variables.
fdn:         File descriptor n.
tmpxxx:      Empty, temporary dictionary xxx.
    

mode determines the subsequent mode of the named dictionary(s). It also controls initialization, when a dictionary is first selected. If mode is "scan", "suspend" or "reset", then existing (nominal) contents are preserved; if mode is "print", then existing (nominal) contents are discarded (empty). Initialization is only performed when changing a dictionary from reset (closed) to another mode. Dictionaries may also be closed, when no longer needed. This implies initialization if accessed again.

If mode is "scan", the named dictionaries are opened for scanning by the cdds_scan... routines.

If mode is "print", the named dictionary is opened for appending new definitions into the dictionary by the cdds_print... routines.

If mode is "suspend", the named dictionaries are explicitly suspended from their current mode. Their contents are preserved for subsequent selection. This is done automatically if the dictionary has not been referenced by the most recent "scan" or "print" mode.

If mode is "reset", the named dictionaries are explicitly reset. If they are subsequently selected, their contents are re-initialized. All dictionaries are implicitly reset, when a process terminates normally. The "close" keyword for mode is deprecated because its less intuitive than "reset".

If mode is "freeze", the named dictionaries are frozen from any further modification. This is done internally by DDS to prevent redefining the binary after the dataset is opened.

 mode       access    initialization
"scan"      input     preserve contents
"print"     output    discard contents
"suspend"   none      temporary suspend
"reset"     none      close dictionary
"close"     none      same as "reset"
"freeze"    none      freeze contents
    

OUTPUT

Dictionary resources are not released, until a dictionary is explicitly closed. This includes file descriptors and about two words of memory for each definition. Some dictionaries may have binary data attached to them. Once opened, they should not be closed, until the binary stream is opened.

EXAMPLES

int j;

/* select "foo_dict" dictionary for printing */
j = cdds_dict("foo_dict", "print");

/* select two dictionaries for scanning */
j = cdds_dict("par:   bar_dict", "scan");
    

SEE ALSO

cdds_in Initialize dictionary for input data
cdds_out Initialize dictionary for output data
cdds_mod Initialize dictionary for modify data
    

AUTHOR