cdds_get - get one field from a DDS type buffer

SYNOPSIS

#include "cdds.h"

int cdds_getxx(bin, tag, in_buf, out_array, count);

BIN_TAG bin
FIELD_TAG tag
const void *in_buf
HostType *out_array
int count

DESCRIPTION

These functions get data from a data field and into an array variable. The data is converted to the host array type, from the type defined for the field. The array type is implied by the function name suffix.

INPUT

The first two arguments describe an input field within a type buffer. bin is a binary tag, previously obtained from cdds_open.

tag identifies a specific field associated with bin obtained from cdds_member. Note that there is a distinct difference between tags generated from different bin values. This means that you should not be using a tag from the in_bin for anything related to the out_bin. If tag is zero, the default target (trace) is used.

in_buf is the buffer of data read for the entire target (or trace).

The last two arguments describe an output array. The type of out_array is implied by the function name suffix. The number of elements is specified by count.

OUTPUT

The get functions copy (or convert) data from one type field into the output array. Vectors are truncated or padded, depending upon the source and destination count.

The function return value is the count, or zero if an error occurred.

A simple byte copy is performed, if the binary formats are the same. The getxx functions convert between most numeric representations. The allowed combinations are implementation dependent. The functions also convert between ascii and ebcdic character formats. Byte fields can be copied, without conversion, into any array. The cdds_get function copies any field type into array, without conversion. Conversion is not allowed between numeric and character types. If conversion is not possible, an error is reported and the output array is not changed. 

Function   HostType       out_array Pad
cdds_get     byte              --
cdds_getcs   char             null terminated
cdds_getcb   char             blank
cdds_geti    int              zero
cdds_gets    short            zero
cdds_getl    long             zero
cdds_getu    unsigned         zero
cdds_getus   short unsigned   zero
cdds_getul   long unsigned    zero
cdds_getf    float            zero
cdds_getff   float            zero (USP fake float)
cdds_getc    complex          zero
cdds_getd    double           zero
C assignment rules are used to convert float fields to integer and unsigned values. Character fields are assumed to be padded with blanks. Trailing pad characters are ignored during get processing; they effectively shorten input character fields. cdds_getcs appends a trailing null character to the value. In this case out_array should be dimensioned greater than count. cdds_getcb pads the value with blanks to the full count. cdds_getff pulls a float value stuffed from consecutive 4-byte.

NOTE: When cdds_getf is given a negative tag, then the absolute value of the tag is instead passed to cdds_getff. This is indicative of a request from cdds_member for one of the Horzxx trace headers.

EXAMPLES

      BIN_TAG bin;
      FIELD_TAG tag;
      const char *in_buf;
      int *out_array;
      ...
      tag = cdds_member(bin,0,"TagName");
      ...
      // Read in a single trace to in_buf
      cddx_read(bin, in_buf, 1);
      // Store 100 values from "TagName" header into out_array (cast to int if necessary)
      cdds_geti(bin, tag, in_buf, out_array, 100);

SEE ALSO

cdds_put Put one field to a buffer

AUTHOR

R. L. Selzler, EPTG (Oct 1995)