cdds_map - convert fields between DDS type buffers

SYNOPSIS

#include "cdds.h"

int cdds_map(out_bin, out_tag, out_buf, in_bin, in_tag, in_buf);

BIN_TAG out_bin
FIELD_TAG out_tag
void *out_buf
BIN_TAG in_bin
FIELD_TAG in_tag
const void *in_buf

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 cdds_open is executed. Normally the "Samples" are mapped along with any headers (except when used in conjunction with either cddx_out or cddx_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.)

            comment= support for defined constants
            map:usp:abc.xyz= dict("xyz_default", 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 "C". 

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).
%          left to right   Modulo (Remainder).
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 cdds_open.

Out_tag is a field tag, previously obtained eg. from cdds_member. It specifies a field tag associated with out_bin. If out_tag 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

          
            BIN_TAG out_bin, in_bin;
            char *out_buf;
            const char *in_buf;
            ...
            cdds_map(out_bin, 0, out_buf, in_bin, 0, in_buf)

SEE ALSO

      cdds_readm  Read binary stream and map buffer
      cdds_writem Write binary stream and map buffer

AUTHOR

R. L. Selzler, EPTG (Oct 1995)