fdds_get - get one field from a DDS type buffer

SYNOPSIS

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

integer function fdds_getxx(bin, tag, in_buf, offset, out_array[, count])

integer bin
integer tag
array in_buf(*)
integer offset
HostType out_array(*)
integer count

DESCRIPTION

These functions get data from a type 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 buffer. bin is a binary tag, previously obtained from fdds_open.

tag identifies a specific field associated with bin obtained from fdds_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).

offset is a byte offset into buffer from where the tag is referenced (typically 0).

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 (except for character type where the maximum count is inherent).

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 functions return value is 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. 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
fdds_get     byte          --
fdds_getcb   character    blank
fdds_geti    integer      zero
fdds_geti2   integer*2    zero
fdds_getr    real         zero
fdds_getff   real         zero (USP fake float)
fdds_getd    real*8       zero
fdds_getc    complex      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. fdds_getff retrieve fake floats from consecutive 4-bytes.

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

EXAMPLE

      integer :: in_bin, tag, ier
      integer :: in_buf(*)
      integer :: out_array(*)
      ...
      tag = fdds_member(in_bin,0,'TagName')
      ...
      ! Read in a single trace to in_buf
      ier = fddx_read(in_bin, in_buf, 1)
      ! Store 100 values from 'TagName' header into out_array (cast to integer if necessary)
      ier = fdds_geti(in_bin, tag, in_buf, 0, out_array, 100)

SEE ALSO

fdds_put

AUTHOR

R. L. Selzler, EPTG (May, 1994) Jerry Ehlers, BP America (May 2003)