fdds_map - convert fields between DDS type buffers

SYNOPSIS

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

integer function fdds_map(out_bin, out_tag, out_buf, in_bin, in_tag, in_buf)

integer out_bin
integer out_tag
integer out_buf(*)
integer in_bin
integer in_tag
integer in_buf(*)

[ Description | Input | Output | Examples ]

DESCRIPTION

This function maps fields from one type buffer to another. The conversions are specified by map definitions. These may be defined by the user, program or default files. These definitions are retrieved, when fdds_open is executed. Normally the "Samples" are mapped along with any headers (except when used in conjunction with either fddx_out or fddx_outhdr the "Samples" are NOT mapped). If the output "Samples" (or any other vectors) have different lengths between the input and output, then the shorter length is used.

Map definitions have the following syntax.

map:in_format:out_format.out_field= expression

or

map:in_alias:out_alias.out_field= expression 

map:usp:segy.OrigRecNum= RecNum
map:in:out.OrigRecNum= RecNum
map:*:out.OrigRecNum= RecNum

map:disco:usp.ToTmAU= 4 * TTIMAU

comment= subscripts are zero based
map:usp:abc.time= _TVPair.TVPair[0]
map:usp:abc.velocity= _TVPair.TVPair[1]

comment= don't map (change) gamma from disco
map:disco:abc.gamma= void

comment= macro required for ambiguous names
         or default support.
map:disco:usp.SrRcMX= field("MID-X", 0.0)

comment= support for defined constants
map:usp:abc.xyz= dict("xyz_default", 0.0)

comment= error, if disco "BETA" field doesn't exist
map:disco:abc.beta= field("BETA", error)

comment= select input field name via definition
map:usp:abc.Sample= field( dict("component", "Sample"), void)

The value of the map definition is an algebraic expression. Map definitions are ignored, unless they match the format and field name. If a map definition is not specified for an output field, an input field by the same name is used by default. The field type (integer, float, ...) and style (ieee, ibm, ...) are converted as needed.

The following operators may be used in numeric expressions. The operands are field names, or the results from functions and macros. Operator precedence and associativity are consistent with Fortran. 

Operator   grouping        Description (precedence)
()  []     left to right   grouping, subscript (highest).
+  -       right to left   unary signs
*  /       left to right   multiply, divide
+  -       left to right   binary add, subtract (lowest).
The following functions are supported, for numeric data types. The argument type may be integer or float. The result is either scalar or vector valued, depending upon the argument. 
Function   Description
abs(x)     absolute value.
ceil(x)    smallest integer not less than x.
floor(x)   largest integer not greater than x.
int(x)     convert to integer (round toward zero).
near(x)    convert to nearest integer.
float(x)   convert to float.
sqrt(x)    square root.
sign(x)    returns -1 or +1 based on the sign of x.
sin(x)     sine(x) (x in radians)
cos(x)     cosine(x) (x in radians)
tan(x)     tangent(x) (x in radians)
asin(x)    arcsine(x) in radians
acos(x)    arccosine(x) in radians
atan(x)    arctangent(x) in radians
atan2(x,y) arctangent of x/y in radians
log(x)     natural log of x
log10(x)   base-10 log of x
exp(x)     e**x
pow(x,y)   x**y
Two special macros are recognized. The first argument is a string that names an input field or an output definition. The second argument is a default value. It is evaluated if the field or definition, referenced by the first argument, doesn't exist. If a macro subscript is specified, it only applies to the first argument. 
Macro                          Description
field("field_name", default)   input field.
dict("defn_name", default)     output definition.
If an input field has a "nice" name, it can be directly referenced in an expression. Otherwise, the field macro must be used. Nice names begin with an alpha character (a-z, A-Z, "_"), and only contain alpha and numeric characters. "BIN-X" is not a nice name; it would parse as "BIN" minus "X".

Three special values are recognized. The output field is not mapped (not changed), if the final expression yields any of these values. They may optionally generate warning or error messages. 

Value   Description
error   generate error message
warn    generate warning message
void    no mapping, no message

INPUT

The first three arguments describe an output type and buffer.

Out_bin is a binary tag, previously obtained from fdds_open.

Out_tag is a field tag, previously obtained eg. from fdds_member. It specifies a tag associated with out_bin. If out_type is zero (nominal), it defaults to the SEQUENCE (trace type) associated with out_bin.

out_buf is the destination buffer. The size and field structure is implied by out_tag.

The last three arguments describe an input type and buffer. They are similar to the out arguments.

OUTPUT

The contents of out_buf are updated, as specified by the map definitions. The return value is zero. If an error is detected, a negative value is returned.

EXAMPLES

      integer out_bin, in_bin
      integer out_buf(*)
      integer in_buf(*)
      ...
      fdds_map(out_bin, 0, out_buf, in_bin, 0, in_buf)

SEE ALSO

fdds_readm
fdds_writem

AUTHOR

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