integer function fdds_dict(names, mode)
[ Description | Arguments | Output | Examples ]
NOTE: Other DDS API functions may implicitly call fdds_dict. If they change dictionary selection, their documentation should clearly say so. In particular see fddx_dict, fddx_in, fddx_out,
fdds_scan functions read definitions from dictionaries in "scan" mode. A dictionary is selected for scanning either by invoking fdds_dict with "scan" mode or by invoking fddx_in. Dictionaries previously selected for scanning are suspended when these 2 functions are used. Multiple dictionaries may be specified by names. Their precedence is left-to-right; the first dictionary has precedence over subsequent ones. If name is not specified, subsequent use of fdds_scan functions will return EOF.
fdds_print functions append definitions to the dictionary in "print" mode. A dictionary is selected for printing either by invoking fdds_dict with "print" mode or by invoking fddx_out. The dictionary previously selected for printing is suspended when these 2 functions are used. If multiple names are specified, only the first is selected. If a name is not specified, subsequent use of fdds_print functions 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.
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 mode of the named dictionary(s). It controls initialization, when a dictionary is first selected. If mode is "scan", "suspend" or "print", the existing contents are preserved. If mode is "reset", then existing contents are discarded. Initialization is only performed when changing a dictionary from "reset" to another mode.
If mode is "scan", the named dictionaries are opened for scanning by the fdds_scan functions.
If mode is "print", the named dictionary is opened for appending new definitions into the dictionary by the fdds_print functions.
If mode is "suspend", the named dictionaries are suspended. Their contents are preserved for future use. 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 reset. If they are selected again later, their contents are re-initialized. All dictionaries are implicitly reset, when a process terminates normally.
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 preserve contents
"suspend" none temporary suspend
"reset" none reset dictionary
"freeze" none freeze contents
Dictionary resources are not released, until a dictionary is explicitly reset. This includes file descriptors and about two words of memory for each definition. Some dictionaries may have binary data attached to them. Once these dictionaries are opened, they should not be closed, until the binary stream is opened.
c open command line and par file dictionaries for input
j = fdds_dict('par:', 'scan')
fddx_in Open input
fddx_dict set dictionary mode convenience routine open