cdds_scank - retrieve definition information from dictionary

SYNOPSIS

#include "cdds.h"

int cdds_scank(alias, keys);

const char *alias
const char *keys

[ Description | Arguments | Output | Examples ]

DESCRIPTION

cdds_scank retrieves information about a definition in a dictionary. It is used to count definition tokens and search for keywords. The "scan" dictionary(s) must have been previously selected by cdds_dict, cddx_dict, or cddx_in.

ARGUMENTS

"alias" is used to set the "position" within the "scan" dictionaries from which value interrogation starts. It specifies the definition of interest. alias may contain multiple names, delimited by white space, or be blank. 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 imediately after the "=" of the definition. When alias is blank, the "position" is unchanged. values are interrogated starting at "position".

"keys" is a list of keywords to match against "tokens" available in value. It may be blank, it may be one of the DDS utility strings defined in cdds.h (e.g., DDS_TRUE_KEY), or it may be any other string useful to the application.

OUTPUT

When keys is blank, cdds_scank counts "tokens" between "position" and the end of the definition. If none are found, zero is returned. When "tokens" are counted, "position" does not change.

Keyword matching is requested with non-blank keys. Each "token" in value is compared to all of the keywords in keys. When a match is found, comparison stops and cdds_scank returns the "token" number within value that matched a keyword. ("token" numbering starts at 1.) The "position" is advanced to the "token". When a match is not found, the function returns zero and the "position" is not changed.

The function returns EOF when no definition is found for non-blank alias and when alias is blank and a definition is not yet selected.

EXAMPLES

   /* retrieve # axes from dictionary associated with bin_tag */
   BIN_TAG bin_tag;
   int ier, rank;
   ier = cddx_dict(bin_tag,"scan");
   rank = cdds_scank("axis","\0");

   /* retrieve verbose flag from par: dictionary */
   int ier, verbose;
   ier = cdds_dict("par:","scan");
   verbose = ( cdds_scank("verbose",DDS_TRUE_KEY) > 0 );

SEE ALSO

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

AUTHOR

R. L. Selzler, EPTG (Oct 1995)