fdds_member - fetch a field tag within a DDS structure

SYNOPSIS

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

integer fdds_member(bin_tag, field_tag, field_name)

integer bin_tag
integer field_tag
character(DEFNNAME_MAX) field_name

DESCRIPTION

fdds_member returns the tag associated with the given field_name that is a member of the structure associated with the tag, field_tag. If field_tag is zero, it defaults to the SEQUENCE (trace type) associated with bin_tag. If field_name is blank, the returned value will be the tag associated with the first member of the structure. field_name can include structure names relative to the field_tag (eg. "Spare.Hdr.RecNum") or can specify the first member of a substructure (eg. "TmMsS1_union."). The functions, fdds_next, fdds_prev and fdds_parent allows traversing through the structure's members. The returned tag should be the tag used in fdds_index and fdds_get.

NOTE: for the fdds_member, if the field_name is "Horz..." and the member cannot be found, the "Horz" will be replaced with "TVPT" and tried again so that "Horz01" thru "Horz20" can be overloaded and used in the fdds_getff and fdds_putff calls.

INPUT

bin_tag is the tag associated with an open binary, previously obtained from fdds_open. It specifies a particular binary stream.

field_tag is the tag associated with a particular field known by bin_tag. A value of "0" always refers to the entire trace field.

field_name is a string that names a member or object field within field_tag. If field_name is zero length or blank, the returned tag defaults to the first member or object in the structure, field_tag.

OUTPUT

The return value is the field tag associate with the desired object or -1 if none found.

NOTE: for cases where "Horz..." was used in fdds_member, then the return value is the negative ( < -1) of the associated field so that fdds_getr will divert the call to fdds_getff with the absolute value of the tag.

EXAMPLE

      integer bin
      integer tag,ptag
      integer ndx,rec,ibuf(*)
      ...
      ! find index of header RecNum
      tag=fdds_member(bin, 0, 'RecNum')
      ndx=1+fdds_index(bin, tag, DDS_INTEGER)
      rec=ibuf(ndx)
      ...
      ! find all trace header tags  
      tag=fdds_member(bin, 0, ' ')
      do while (tag.ge.0)
          ptag=fdds_prime(bin, tag)
          ...
          tag=fdds_next(bin, tag)
      enddo

SEE ALSO

fdds_object  Fetch object tag
fdds_next Fetch next field tag
fdds_prev Fetch previous field tag
fdds_parent Fetch parent field tag
fdds_prime  Fetch field prime tag

AUTHOR

Jerry Ehlers, BP America (May 2003)