NAME

       gd_mplex_lookback — set the GetData lookback length for MPLEX fields.

SYNOPSIS

       #include <getdata.h>

       void gd_mplex_lookback(DIRFILE *dirfile, int lookback);

DESCRIPTION

       The  gd_mplex_lookback()  function controls how far GetData searches backwards for the initial value of a
       field when reading a MPLEX field from the dirfile(5) database specified by dirfile.

       If the first sample returned of a MPLEX field does not contain the value of the field, because the  index
       field  does  not  take on the specified multiplex index value, GetData must search the field backwards to
       find the last time the field was updated, in order to propagate that value into the  initial  portion  of
       the returned data.  (See gd_getdata(3) for further discussion on the data returned for a MPLEX field).

       This  function  sets  the  amount  of  data  GetData  searches before giving up according to the value of
       lookback.  If lookback is zero, this search is disabled completely, and the start of  the  returned  data
       will  be  padded (with zero or IEEE-754-conformant not-a-number) unless the first sample returned happens
       to contain the value of the field.  If lookback is  the  special  symbol  GD_LOOKBACK_ALL,  GetData  will
       exhaustively search all available data before the returned portion for an initial value.

       If  not  one  of the special values, lookback should be a positive integer specifying the number of MPLEX
       periods to search.  Each MPLEX field has its own period, measured in samples of the index field, which is
       defined as follows:

       •      if  the  MPLEX  field  in  question specifies an optional period positive parameter (see the MPLEX
              definition in dirfile-format(5)), its period is that many samples;

       •      otherwise, if the MPLEX field's count_val is at least five, its period is  one  more  sample  than
              twice that value;

       •      otherwise, the period is ten samples.

       So, given the following MPLEX definitions:

              field1 MPLEX data_field index_field 7 12
              field2 MPLEX data_field index_field 2 6
              field3 MPLEX data_field index_field 7
              field4 MPLEX data_field index_field 2

       field1  has  a  period  of  12  samples  and field2 a period of 6 samples (both the value of their period
       parameters); field3 has a period of 15 samples (one more than twice it's count_val),  and  field4  has  a
       period of 10 samples (the default value, since its count_val is less than five).

       The  initial  value  of  the  MPLEX  lookback  is  ten  periods.   This value is provided in getdata.h as
       GD_DEFAULT_LOOKBACK.

       This function always succeeds and returns no value.

HISTORY

       The gd_mplex_lookback() function appeared in GetData-0.8.0.

SEE ALSO

       gd_getdata(3), gd_open(3), dirfile(5), dirfile-format(5)