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)