fdds_printf - append definition to DDS dictionary

SYNOPSIS

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

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

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

DESCRIPTION

fdds_printf appends a definition to a dictionary. The print dictionary must have been previously selected by fdds_dict, or related function.

One definition name may be specified by alias. If specified, a new definition is appended to the print dictionary. A new definition is not created, if a blank alias is specified; in this case the value is appended to the current print definition.

If the alias definition name is prefixed with "alias:" or "?", a definition alias is appended to the dictionary.

fdds_printf is controlled by a format string and optional arguments. Characters are appended to the existing value, if any. The new value is created, as specified by the ANSI C standard for the stdio sprintf function.

fmt and optional arguments control the processing of definition values. The rules correspond to the printf function in ANSI C standard. Values should not contain '=' (unless escaped) and they are normally terminated with '\n'.

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

The following table summarizes conversion specifiers for fdds_printf by Fortran type. See Ansi standard C printf for more details. 

fmt                     modifiers
char      Data type   h     l      L          *         I/O type
----      ---------   --------------------------------  --------------------
 u        integer     short long   longlong   suppress  unsigned
 d        integer     short long   longlong   suppress  decimal
 o        integer     short long   longlong   suppress  octal
 x        integer     short long   longlong   suppress  hexadecimal
 i        integer     short long   longlong   suppress  dec,oct,hex
 n        integer     short long   longlong   suppress  (returns # characters)
 c        characters  NA    NA     NA         suppress  (reads spaces also)
 s        string      NA    NA     NA         suppress  (skips initial spaces)
 p        pointer     NA    NA     NA         suppress
 e, f, g  real        NA    double longdouble suppress
 [...]    character   NA    NA     NA         suppress
 [^...]   character   NA    NA     NA         suppress
 %        NA          NA    NA     NA         NA        (literal "%")
The printf type modifiers for floating point arguments must be extended by fdds_printf to support Fortran. "C" always promotes real arguments (Fortran real) to double (precision), therefore C doesn't distinguish between them in printf formats. The type modifiers used by scanf are also honored by fdds_printf; the default is real (Fortran real), 'l' implies double (precision), and 'L' long double (for extensions). 
real f
double precision d
long double precision ld
...
j = fdds_printf('foo',  '%f  %lf  %Lf\n\0',  f,  d,  ld)
fdds_printf strips trailing blanks from character arguments during '%s' conversion. Like "C", it also assumes the '%c' conversion argument is an integer.

INPUT

alias identifies a new definition, or continued processing of the value for the current one.

OUTPUT

The contents of the current output dictionary may be changed.

No function is provided to overwrite existing definitions -- history can't be changed. An existing name can be appended again, which effectively redefines its value.

The return value is the number of characters written, or negative (EOF) if an error occurred. Zero is returned, if an output dictionary is not open.

EXAMPLES

!     append "beta" definition to output dictionary
      ier = fdds_printf('beta', ' %f\n\0', 3.14)

!     append mixed data types (string, integer, float)
      ier = fdds_printf('gamma', ' %s %i %f\n\0', 'green', 5, 7.3)

!     append an array of float values
      ier = fdds_printf('omega', ' ')
      do i=1,count
         ier = fdds_printf(' ', ' %f\0', omega(i))
      enddo
      ier = fdds_printf(' ', '\n\0')

!     append an alias definition
      ier = fdds_printf('alias:zeta', ' zeta ZETA Zeta\n\0')

!     append an alias to undefine "gamma"
      ier = fdds_printf('alias:gamma',' \n\0')

SEE ALSO

fdds_printt Append a definition
fdds_printv Append a definition

AUTHOR

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