fdds_scanf - retrieve definition from DDS dictionary

SYNOPSIS

#include <fdds.h> (fixed-format sources)
#include <f90dds.h> (free-format sources)

integer function fdds_scanf(alias, fmt,...)

character*(*) alias
character*(*) fmt

DESCRIPTION

fdds_scanf retrieves a definition from a dictionary. The "scan" dictionary(s) must have been previously selected by fdds_dict, fddx_dict, or fddx_out.

ARGUMENTS

"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 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 immediately after the "=" of the definition. When alias is blank, the "position" is unchanged. values are 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.

Format strings MUST be terminated with a null character ("\0").

Optional arguments, "...", are program variables that are set by fdds_scanf if they are present in the "scan" dictionaries.

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. fdds_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.

The following table summarizes conversion specifiers recognized within fmt. 

fmt        -------- Sun -------- 
char      Fortran       modifier 
                      h    l    L
d         integer     *2   *4   *4 
i         integer     *2   *4   *4
o         integer     *2   *4   *4
u         integer     *2   *4   *4
x         integer     *2   *4   *4
c         character   NA   NA   NA
s         character   NA   NA   NA
f         real        NA   dp   NA
e, f, g   real        NA   dp   NA
p         not char    NA   NA   NA
n         integer     *2   *4   *4
[...]     character   NA   NA   NA
[^...]    character   NA   NA   NA
%         NA          NA   NA   NA
fdds_scanf pads trailing blanks or truncates strings as needed during '%c', '%s' and '%[...]' conversion. Unlike "C", the maximum field width is not required to prevent string overflow.

OUTPUT

fdds_scanf returns the number of arguments converted and assigned.

fdds_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

c  default "alpha" to 3.14, override if defined
      alpha = 3.14
      ier = fdds_scanf('alpha', '%f\0', alpha)
 
c  retrieve beta, using defn alias
      ier = fdds_scanf('beta BETA Beta', '%s\0', beta)
 
c  retrieve mixed data types (string, integer, float)
      ier = fdds_scanf('gamma', '%s %d %f\0', s, i, r)
 
c  retrieve 1st & 2nd axis sizes
      ier  = fdds_scanf('size.axis(1)', '%d\0', nsmp)
      ier  = fdds_scanf('size.axis(2)', '%d\0', ntrc)
 
c  retrieve arbitrary number of float values
      ier = fdds_scanf('omega', '%f\0',omega(1))
      n = 0
      dowhile(ier.eq.1)
         n = n + 1
         ier = fdds_scanf(' ', '%f\0', omega(n+1))
      enddo

c  retrieve alias definition itself
      ier = fdds_scanf('$name', ' %s\0', alias)

SEE ALSO

fdds_dict  Select DDS dictionary and set mode
fddx_dict  Select DDS dictionary and set mode
fdds_scank Retrieve a definition

AUTHOR

R. L. Selzler, EPTG (May, 1994)