cdds_scank - retrieve definition information from dictionary

SYNOPSIS

#include "cdds.h"

int cdds_scank(alias, keys);

const char *alias
const char *keys

[ Description | Examples ]

DESCRIPTION

cdds_scank retrieves a definition information 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_scank is used to count tokens and search for keywords. The value is parsed into tokens, similar to cdds_scant. The remaining tokens are simply counted, if a null keys is specified. The function returns -1 if the alias is not found, 0 if the alias is found but there are no tokens, or the total number of tokens found. When tokens are counted, the current position in the value is not changed. A search is requested by specifying a non-null keys. The keys argument is parsed into tokens, similar to the value. The search stops at the first value token that matches any keys token. If a match is found, its count is returned and the current position in the value is advanced to the token. If a match is not found, the function returns zero and the current position is not changed.

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

int i, j, dimensions, ier;
float size[3];

j = cdds_scank("flag", "true TRUE True t T");

dimensions = cdds_scank("size3d", "");
if (dimensions > -1) {
    if (dimensions == 3) {
        ier = cdds_scanf("size3d", "");
        for (i = 0; i < bounds; ++i) {
            ier = cdds_scanf("", "%f", &size[i]);
        }
    }
    else {
        ier = cdds_prterr("You did not specify the correct size3d dimensions.\n");
    }
}
else {
    size[0] = 0;
    size[1] = 0;
    size[2] = 0;
}

SEE ALSO

cdds_dict Select DDS dictionary and mode
cdds_scanf Retrieve a definition
cdds_scant Retrieve a definition
cdds_scantn Retrieve a definition
cdds_scanv Retrieve a definition

AUTHOR

R. L. Selzler, EPTG (Oct 1995)