integer function fdds_dict(names, mode)
[ Description | Input | 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 fdds_in, fdds_out, fdds_mod and fdds_open.
fdds_scan... reads definitions from the input dictionaries. Input dictionaries are selected by the most recent call to fdds_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.
fdds_print... appends definitions to the output dictionary. The output dictionary is selected by the most recent call to fdds_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.
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 fdds_scan... routines.
If mode is "print", the named dictionary is opened for appending new definitions into the dictionary by the fdds_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
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.
! open "line207.aH" dictionary for output
j = fdds_dict('line207.aH', 'print')
! open four dictionaries for input
j = fdds_dict('cmd: file1 file2 stdin:', 'scan')
fdds_in Initialize dictionary for input data
fdds_out Initialize dictionary for output data
fdds_mod Initialize dictionary for modify data