cdds_scant - retrieve definition from dictionary
SYNOPSIS
#include "cdds.h"
int cdds_scant(alias, str);
-
const char *alias
const char **str
[ Description
| Examples
]
DESCRIPTION
cdds_scant retrieves a definition from dictionaries. The
scan dictionaries must have been previously selected by
cdds_dict, or related function. The name of
the definition is specified by alias (multiple names, delimited
by white space, may be specified). If a null alias is specified
(i.e. NULL, zero length string, or a string that only contains
white space) the value is processed, starting from the current position
of the current scan definition.
Dictionaries are scanned from bottom-to-top and right-to-left.
The newest definition that matches any alias is selected.
cdds_scant assigns a string pointer to *str.
The string uses a temporary buffer; the contents may be changed by
the next DDS API call. The string contains the next token parsed
from the value. White space is skipped, starting at the current
position in the value. If the next character is a double quote,
a matching quote terminates the token. If not quoted, the token
is terminated by the next white space. The current position is
advanced to EOT (end of token). The function returns the number
of characters in the string. If a token is not found, it returns EOF
and *str is not changed.
If the token is delimited by double quotes, the value may contain
special characters. Any single character may be escaped by prefixing
it with "\". Escapes are required to preserve special
characters ('\', '=', '"'). White space within
the token does not need to be escaped. Escape characters "\"
are removed during retrieval.
Dictionaries may contain alias definitions. They define
alternate names for older definitions. Alias
definitions are denoted by a special prefix,
"alias:defn_name" or "$defn_name".
The value of an alias definition is a list of alternate names.
For example:
out_data= /very/long/path/name/file
name= value...
alias:data= out_data
foo= hidden definition...
name= value...
$foo=
Alias definitions are processed, when scan functions search for
a name. If a definition name matches an alias, the search list
is modified and processing continues. The defined values (definition
names delimited by white space) replace the one name matched in the
original alias list.
EXAMPLES
const char *bar, *bar2;
int j;
bar = "default for first bar token";
j = cdds_scant("bar", &bar);
bar2 = "default for second bar token";
j = cdds_scant("", &bar2);
SEE ALSO
cdds_dict Select DDS dictionary and mode
cdds_scanf Retrieve a definition
cdds_scank Retrieve a definition
cdds_scantn Retrieve a definition
cdds_scanv Retrieve a definition
AUTHOR
R. L. Selzler, EPTG (Oct 1995)