.\" gd_putdata.3.  The gd_putdata man page.
.\"
.\" Copyright (C) 2008-2017 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_putdata 3 "25 January 2017" "Version 0.10.0" "GETDATA"

.SH NAME
gd_putdata \(em write data to a Dirfile database

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "size_t gd_putdata(DIRFILE *" dirfile ", const char *" field_code ", off_t"
.IB first_frame ", off_t " first_sample ", size_t " num_frames ", size_t"
.IB num_samples ", gd_type_t " data_type ", const void *" data_in );
.EC

.SH DESCRIPTION
The
.FN gd_putdata
function writes data to a dirfile(5) database specified by
.ARG dirfile
for the field
.ARG field_code ,
which may not contain a representation suffix.  It writes
.ARG num_frames
frames plus
.ARG num_samples
samples to this field, starting 
.ARG first_sample
samples past frame
.ARG first_frame . 
The data is read from the user-supplied buffer
.ARG data_in,
which is has a data type specified by
.ARG data_type .
This interface cannot write to field representations.

The 
.ARG dirfile
argument must point to a valid DIRFILE object previously created by a call to
.F3 gd_open .

Unless using
.B GD_HERE 
(see below), the first sample written will be
.RS
.IR first_frame " * " samples_per_frame " + " first_sample
.RE
as measured from the start of the dirfile, where
.I samples_per_frame
is the number of samples per frame as returned by
.F3 gd_spf .
The number of samples which
.FN gd_putdata
attempts to write is, similarly,
.RS
.IR num_frames " * " samples_per_frame " + " num_samples .
.RE
Although calling
.FN gd_putdata
using both samples and frames is possible, the function is typically called
with either
.ARG num_samples
and
.ARG first_sample ,
or
.ARG num_frames
and
.ARG first_frames ,
equal to zero.

Instead of explicitly specifying the origin of the write, the caller may pass
the special symbol
.B GD_HERE
as
.ARG first_frame .
This will result in the write occurring at the current position of the I/O
pointer for the field (see
.F3 gd_getdata
for a discussion of I/O pointers).  In this case, the value of
.ARG first_sample
is ignored.

The 
.ARG data_type
argument should be one of the following symbols, which indicates the type of
the input data:
.RS
.TP 11
.B GD_UINT8
unsigned 8-bit integer
.DD GD_INT8
signed (two's complement) 8-bit integer
.DD GD_UINT16
unsigned 16-bit integer
.DD GD_INT16
signed (two's complement) 16-bit integer
.DD GD_UINT32
unsigned 32-bit integer
.DD GD_INT32
signed (two's complement) 32-bit integer
.DD GD_UINT64
unsigned 64-bit integer
.DD GD_INT64
signed (two's complement) 64-bit integer
.DD GD_FLOAT32
IEEE-754 standard 32-bit single precision floating point number
.DD GD_FLOAT64
IEEE-754 standard 64-bit double precision floating point number
.DD GD_COMPLEX64
C99-conformant 64-bit single precision complex number
.DD GD_COMPLEX128
C99-conformant 128-bit double precision complex number
.RE

The type of the input data need not be the same as the type of the data stored
in the database.  Type conversion will be performed as necessary to write the
appropriate type.  The argument
.ARG data_in
must point to a valid memory location of containing all the data to be written.

Upon successful completion, the I/O pointer of the field will be on the sample
immediately following the last sample written, if possible.  On error, the
position of the I/O pointer is not specified.

.SH RETURN VALUE
In all cases,
.FN gd_putdata
returns the number of samples (not bytes) successfully written to the database,
which may be zero if an error has occurred.

On error, this function returns zero and stores a negative-valued error code in
the
.B DIRFILE
object which may be retrieved by a subsequent call to
.F3 gd_error .
Possible error codes are:
.DD GD_E_ACCMODE
The specified
.ARG dirfile
was opened read-only.
.DD GD_E_ALLOC
The library was unable to allocate memory.
.DD GD_E_BAD_CODE
The field specified by
.ARG field_code ,
or one of the fields it uses for input, was not found in the database.
.DD GD_E_BAD_DIRFILE
An invalid
.ARG dirfile
was supplied.
.DD GD_E_BAD_FIELD_TYPE
Either the field specified by
.ARG field_code ,
or one of the fields it uses for input, was of
.BR MULTIPLY ,
.BR DIVIDE ,
.BR WINDOW ,
.BR INDIR ,
or
.B SINDIR
type, or a
.B LINCOM
with more than one input field, or a
.B POLYNOM
with quadratic or higer terms.  Alternately, the caller may have attempted to
write to the implicit INDEX field, which is not possible.
.DD GD_E_BAD_TYPE
An invalid
.ARG data_type
was specified.
.DD GD_E_DIMENSION
The field specified by
.ARG field_code
was not a vector field.  The caller should use
.F3 gd_put_carray ,
.F3 gd_put_constant ,
or
.F3 gd_put_string
instead.  Or, a scalar field was found where a vector field was expected in
the definition of
.ARG field_code .
.DD GD_E_DOMAIN
An attempt was made to write to a
.B LINTERP
field with a look-up table which was not monotonic or not purely real.
.DD GD_E_INTERNAL_ERROR
An internal error occurred in the library while trying to perform the task.
This indicates a bug in the library.  Please report the incident to the
maintainer.
.DD GD_E_IO
An error occurred while trying to open, read from, or write to a file on disk
containing a raw field or a
.B LINTERP
table.
.DD GD_E_LUT
A
.B LINTERP
table was malformed.
.DD GD_E_PROTECTED
The data of the
.B RAW
field backing
.ARG field_code
was protected from change by a /PROTECT directive.
.DD GD_E_RANGE
An attempt was made to write data either before the beginning-of-frame marker
for
.ARG field_code ,
or the raw field it depends on, or else outside the addressable Dirfile range
(more than 2**63 samples beyond the start of the Dirfile).
.DD GD_E_RECURSE_LEVEL
Too many levels of recursion were encountered while trying to resolve
.ARG field_code .
This usually indicates a circular dependency in field specification in the
dirfile.
.DD GD_E_UNSUPPORTED
Reading from dirfiles with the encoding scheme of the specified dirfile is not
supported by the library.  See
dirfile-encoding(5)
for details on dirfile encoding schemes.
.PP
A descriptive error string for the error may be obtained by calling
.F3 gd_error_string .

.SH NOTES
When operating on a platform whose
.B size_t
is
.IR N -bytes
wide, a single call of
.FN gd_putdata
will never write more than (2**(\fIN\fR-\fIM\fR) - 1) samples, where \fIM\fR is
the size, in bytes, of the largest data type used to calculate the stored field.
If a larger request is specified, less data than requested will be written,
without raising an error.  This limit is imposed even when 
.ARG data_type
is
.B GD_NULL
(i.e., even when no actual I/O or calculation occurs).  In all cases, the actual
amount of data is returned.

.SH HISTORY
The
.FN putdata
function appeared in GetData-0.3.0.

In GetData-0.7.0, this function was renamed to
.FN gd_getdata .

The
.B GD_HERE
symbol used for sequential writes appeared in GetData-0.8.0.

.SH SEE ALSO
.F3 GD_SIZE ,
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_getdata ,
.F3 gd_open ,
.F3 gd_put_carray ,
.F3 gd_put_constant ,
.F3 gd_put_sarray ,
.F3 gd_put_string ,
.F3 gd_seek ,
.F3 gd_spf ,
dirfile(5), dirfile-encoding(5)