.\" header.tmac.  GetData manual macros.
.\"
.\" Copyright (C) 2016 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.

.\" Format a function name with optional trailer: func_name()trailer
.de FN \" func_name [trailer]
.nh
.BR \\$1 ()\\$2
.hy
..

.\" Format a reference to section 3 of the manual: name(3)trailer
.de F3 \" func_name [trailer]
.nh
.BR \\$1 (3)\\$2
.hy
..

.\" Format the header of a list of definitons
.de DD \" name alt...
.ie "\\$2"" \{ \
.TP 8
.PD
.B \\$1 \}
.el \{ \
.PP
.B \\$1
.PD 0
.DD \\$2 \\$3 \}
..

.\" Start a code block: Note: groff defines an undocumented .SC for
.\" Bell Labs man legacy reasons.
.de SC
.fam C
.na
.nh
..

.\" End a code block
.de EC
.hy
.ad
.fam
..

.\" Format a structure pointer member: struct->member\fRtrailer
.de SPM \" struct member trailer
.nh
.ie "\\$3"" .IB \\$1 ->\: \\$2
.el .IB \\$1 ->\: \\$2\fR\\$3
.hy
..

.\" Format a function argument
.de ARG \" name trailer
.nh
.ie "\\$2"" .I \\$1
.el .IR \\$1 \\$2
.hy
..

.\" Hyphenation exceptions
.hw sarray carray lincom linterp
.\" gd_mplex_lookback.3.  The gd_mplex_lookback man page.
.\"
.\" Copyright (C) 2012, 2013, 2016 D.V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
.TH gd_mplex_lookback 3 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_mplex_lookback \(em set the GetData lookback length for MPLEX fields.

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "void gd_mplex_lookback(DIRFILE *" dirfile ", int " lookback );
.EC

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

If the first sample returned of a
.B 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
.F3 gd_getdata
for further discussion on the data returned for a
.B MPLEX
field).

This function sets the amount of data GetData searches before giving up
according to the value of
.IR lookback .
If
.I 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
.I lookback
is the special symbol
.BR 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,
.I lookback
should be a positive integer specifying the number of
.B MPLEX
periods to search.  Each
.B MPLEX
field has its own period, measured in samples of the index field, which is
defined as follows:
.IP \(bu
if the
.B MPLEX
field in question specifies an optional
.I period
positive parameter (see the
.B MPLEX
definition in
dirfile-format(5)),
its period is that many samples;
.IP \(bu
otherwise, if the
.B MPLEX
field's
.I count_val
is at least five, its period is one more sample than twice that value;
.IP \(bu
otherwise, the period is ten samples.
.PP
So, given the following
.B MPLEX
definitions:
.IP
field1 \fBMPLEX\fR data_field index_field 7 12
.br
field2 \fBMPLEX\fR data_field index_field 2 6
.br
field3 \fBMPLEX\fR data_field index_field 7
.br
field4 \fBMPLEX\fR data_field index_field 2
.PP
.I field1
has a period of 12 samples and
.I field2
a period of 6 samples (both the value of their
.I period
parameters);
.I field3
has a period of 15 samples (one more than twice it's
.IR count_val ),
and
.I field4
has a period of 10 samples (the default value, since its
.I count_val
is less than five).
.PP
The initial value of the
.B MPLEX
lookback is ten periods.  This value is provided in getdata.h as
.BR GD_DEFAULT_LOOKBACK .

This function always succeeds and returns no value.

.SH HISTORY
The
.FN gd_mplex_lookback
function appeared in GetData-0.8.0.

.SH SEE ALSO
.F3 gd_getdata ,
.F3 gd_open ,
dirfile(5), dirfile-format(5)