cdds_scanf - retrieve definition from dictionary

SYNOPSIS

#include "cdds.h"

int cdds_scanf(alias, fmt, ...);

const char *alias
const char *fmt

[ Description | Arguments | Details | Output | Examples ]

DESCRIPTION

cdds_scanf retrieves a definition from a dictionary. The "scan" dictionary(s) must have been previously selected by cdds_dict, cddx_dict, or cddx_out.

ARGUMENT

"alias" is used to set the "position" from which value retrieval starts. It specifies the definition to retrieve. alias may contain multiple names, delimited by white space, or it may be null. When names are given, the "scan" dictionaries are searched from bottom-to-top, right-to-left. The newest definition that matches any name is selected and the "position" is set immediately after the "=" of the definition. If a null alias is given (i.e. NULL, zero length string, or a string that only contains white space) the value is processed starting at "position".

"fmt" is an ANSI C standard format string for the stdio scanf function. It converts optional arguments "..." following the rules of the ANSI C standard for scanf.

Optional arguments, "...", are program variables that are set by cdds_scanf if they are present in the "scan" dictionaries. These variables should be passed by address.

DETAILS

Processing begins at the current "position" in the definition value. Characters are matched and converted, according to fmt, as specified by the ANSI C standard for the stdio scanf function. The "position" is advanced as the format is processed. cdds_scanf returns the number of arguments converted and assigned.

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=
When cdds_scanf finds an alias: definition for alias the search list is modified and processing continues. The values of the alias: definition replace the one name matched in the original alias list.

OUTPUT

cdds_scanf returns the number of arguments converted and assigned.

cdds_scanf returns EOF, if no match is found, if a "scan" definition is not already selected, or if conversion fails prior to the first assignment.

EXAMPLES

   int i, j, n;
   float alpha, gamma[100], f;
   const char s[100];

   alpha = 3.14;
   j = cdds_scanf("alpha", "%f", &alpha);

   j = cdds_scanf("beta", "%s %i %f", s, &i, &f);

   /* retrieve list of float values */
   j = cdds_scanf("gamma", "");
   for(n = 0; 1 == cdds_scanf("", "%f", gamma + n); n++);

SEE ALSO

cdds_dict  Select DDS dictionary and mode
cddx_dict  Select DDS dictionary and mode
cdds_scank Retrieve a definition

AUTHOR

R. L. Selzler, EPTG (Oct 1995)