.\" gd_add.3in.  The gd_add man page.
.\"
.\" Copyright (C) 2008, 2009, 2010, 2012, 2013, 2014, 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_add 3 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_add, gd_madd \(em add a field to a Dirfile

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "int gd_add(DIRFILE *" dirfile ", const gd_entry_t *" entry );
.HP
.BI "int gd_madd(DIRFILE *" dirfile ", const gd_entry_t *" entry ,
.BI "const char *" parent );
.EC

.SH DESCRIPTION
The
.FN gd_add
function adds the field described by
.ARG entry
to the dirfile specified by
.ARG dirfile .
The
.FN gd_madd
function behaves similarly, but adds the field as a metafield under the
field indicated by the field code
.ARG parent .

The form of
.ARG entry
is described in detail on the
.F3 gd_entry
man page.  All relevant members of
.ARG entry
for the field type specified must be properly initialised.  If
.ARG entry
specifies a
.B CONST
or
.B CARRAY
field, the field's data will be set to zero.  If
.ARG entry
specifies a
.B STRING
field, the field data will be set to the empty string.

The only flags in the
.SPM entry flags
member which are honoured are
.BR GD_EN_HIDDEN ,
which should be set or cleared to set the hiddenness of the entry (see
.F3 gd_hidden ),
and
.BR GD_EN_COMPSCAL ,
which indicates whether scalar parameters are initialised from the complex
valued or purely real member, which both are present
.RB ( LINCOM ,
.BR POLYNOM ,
.BR RECIP ).

A metafield may be added either by calling
.FN gd_madd
with
.SPM entry field
containing only the metafield's name, or else by calling
.FN gd_add
with the fully formed
.RI """" <parent-field> / <meta-field> """"
field code in
.SPM entry field .
Regardless of which interface is used, when adding a metafield the value of
.SPM entry fragment_index
is ignored and GetData will add the new metafield to the same format
specification fragment in which the parent field is defined.  If the specified
parent field name is an alias, the canonical name of the field will be
substituted.

Fields added with this interface may contain either literal parameters or
parameters based on scalar fields.  If an element of the
.SPM entry scalar
array defined for the specified field type is non-NULL, this element will be
used as the scalar field code, and the corresponding numerical member will be
ignored, and need not be initialised.  Conversely, if numerical parameters are
intended, the corresponding
.SPM entry scalar
elements should be set to NULL.  If using an element of a
.B CARRAY
field,
.SPM entry scalar_ind
should also be set.

.SH RETURN VALUE
On success,
.FN gd_add
and
.FN gd_madd
return zero.   On error, a negative-valued error code is returned.  Possible
error codes are:
.DD GD_E_ACCMODE
The specified dirfile was opened read-only.
.DD GD_E_ALLOC
The library was unable to allocate memory.
.DD GD_E_BAD_CODE
The field name provided in
.SPM entry field
contained invalid characters; or it or an input field did not contain the
affected fragment's prefix or suffix. Alternately, the
.ARG parent
field code was not found, or was already a metafield.
.DD GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.DD GD_E_BAD_ENTRY
There was an error in the specification of the field described by
.ARG entry ,
or the caller attempted to add a field of type
.B RAW
as a metafield.
.DD GD_E_BAD_INDEX
The
.SPM entry fragment_index
parameter was out of range.
.DD GD_E_BAD_TYPE
The
.SPM entry data_type
parameter provided with a
.BR RAW
entry, or the
.SPM entry const_type
parameter provided with a
.B CONST
or
.B CARRAY
entry, was invalid.
.DD GD_E_DUPLICATE
The field name provided in
.SPM entry field
duplicated that of an already existing field.
.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
GetData developers.
.DD GD_E_IO
An I/O error occurred while creating an empty binary file to be associated with
a newly added
.B RAW
field.
.DD GD_E_PROTECTED
The metadata of the fragment was protected from change.  Or, the creation of a
.B RAW
field was attempted and the data of the fragment was protected.
.DD GD_E_UNKNOWN_ENCODING
The encoding scheme of the indicated format specification fragment is not known
to the library.  As a result, the library was unable to create an empty binary
file to be associated with a newly added
.B RAW
field.
.DD GD_E_UNSUPPORTED
The encoding scheme of the indicated format specification fragment does not
support creating an empty binary file to be associated with a newly added
.B RAW
field.
.PP
The error code is also stored in the
.B DIRFILE
object and may be retrieved after this function returns by calling
.F3 gd_error .
A descriptive error string for the error may be obtained by calling
.F3 gd_error_string .

.SH HISTORY
The functions
.FN dirfile_add
and
.FN dirfile_madd
appeared in GetData-0.4.0.

In GetData-0.7.0, the functions were renamed to
.FN gd_add
and
.FN gd_madd .

In GetData-0.8.0,
.FN gd_add
first allowed adding metafields by providing the full (slashed) field name.
This was the first version supporting fragment affixes, and in this version,
.FN gd_add
would apply the destination fragment's affixes to the supplied
.SC
.SPM entry field
.EC
name.  In GetData-0.8.1, this changed:
.FN gd_add
now assumes
.SC
.SPM entry field
.EC
contains the full field name, including any necessary affixes.

In GetData-0.10.0, the error return from these functions changed from -1 to a
negative-valued error code.

See
.F3 gd_entry
for the history of the
.B gd_entry_t
structure.

.SH SEE ALSO
.F3 gd_add_bit ,
.F3 gd_add_carray ,
.F3 gd_add_const ,
.F3 gd_add_divide ,
.F3 gd_add_lincom ,
.F3 gd_add_linterp ,
.F3 gd_add_multiply ,
.F3 gd_add_phase ,
.F3 gd_add_polynom ,
.F3 gd_add_raw ,
.F3 gd_add_recip ,
.F3 gd_add_sbit ,
.F3 gd_add_spec ,
.F3 gd_add_string ,
.F3 gd_entry ,
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_madd_bit ,
.F3 gd_madd_carray ,
.F3 gd_madd_const ,
.F3 gd_madd_divide ,
.F3 gd_madd_lincom ,
.F3 gd_madd_linterp ,
.F3 gd_madd_multiply ,
.F3 gd_madd_phase ,
.F3 gd_madd_polynom ,
.F3 gd_madd_recip ,
.F3 gd_madd_sbit ,
.F3 gd_madd_spec ,
.F3 gd_madd_string ,
.F3 gd_metaflush ,
.F3 gd_open ,
dirfile-format(5)