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, field_tag, in_buf, offset, out_array[, count])

integer bin_tag
integer field_tag
HostBufType in_buf(*)
integer offset
HostArrayType out_array(*)
integer count

DESCRIPTION

These functions get data from a field of an input buffer and place it into an array variable. The data are converted from the type of the field known to bin_tag to the host-dependent type defined for the trailing characters in the function name (see below).

ARGUMENTS

"bin_tag" is a binary tag previously obtained from fddx_in.

"field_tag" identifies a specific field within a structure of bin_tag. It is obtained with function fdds_member. If field_tag is zero, the default target (a trace) is used.

"in_buf" is a buffer of data containing the target (a trace).

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

"out_array" is a buffer where converted information is placed. The host-dependent type of out_array is implied by trailing chacters in the function name (see below).

"count" specifies the number of elements to convert. (except for type character where the maximum count is implicit).

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         zero
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 1-, 2- or 4-byte integers.

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

EXAMPLES

c  get (convert) type field into integer out_array
      integer bin_tag, field_tag
      integer in_buf(*)
      integer out_array
      ...
      ier = fddx_read(bin, in_buf, 1)
      j = fdds_geti(bin_tag, field_tag, in_buf, 0, out_array, 100)

c retrieve the dead trace flag for tests during processing
      character Title*(80)
      integer bin_tag, field_tag
      integer itrc, ntrc
      integer ier, dt_flag
      real    in_buf(*)
      ...
      bin_tag = fddx_in('in','stdin:',Title)
      ntrc = fdds_axis_prod(1)
      field_tag = fdds_member(bin_tag,0,'StaCor')
      do itrc = 1,ntrc
         ier = fddx_read(bin_tag,in_buf,1)
         ier = fdds_geti(bin_tag,field_tag,in_buf,0,dt_flag,1)
         if (dt_flag .ne. 30000) then
            ...
         endif
      enddo

SEE ALSO

fddx_in
fdds_member
fdds_axis_prod
fddx_read
fdds_put

AUTHOR

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