.\" 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_alter_affixes.3.  The gd_alter_affixes man page.
.\"
.\" Copyright (C) 2012, 2016, 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_alter_affixes 3 "27 January 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_alter_affixes \(em modify the field affixes of a fragments in a Dirfile

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "int gd_alter_affixes(DIRFILE *" dirfile ", int " fragment_index ,
.BI "const char *" prefix ", const char *" suffix );
.EC

.SH DESCRIPTION
The
.FN gd_alter_affixes
function sets the root namespace, field prefix and suffix of fields defined in
the format specification fragment given by
.ARG fragment_index
to
.ARG prefix
and
.ARG suffix
in the dirfile(5) database specified by
.ARG dirfile .

The
.ARG prefix
may contain a root namespace for the fragment, separated from the prefix by a
dot
.RB ( . ).
If it does not contain a namespace, the fragment's root namespace is not
changed.  To remove a root namespace, explicitly specify the null namespace via
a leading dot in
.ARG prefix .

The field prefix and suffix are affixed to all field codes found in the
specified fragment.  If the parent fragment to the modified fragment contains
field affixes themselves, they should be included in the affixes passed to
.FN gd_alter_affixes .
If
.ARG prefix
or
.ARG suffix
is NULL, the corresponding affix will be unchanged.  To remove an affix, set it
to the parent fragment's corresponding affix, which may be the empty string
("").

It is not possible to set affixes on the root format file (i.e.
.ARG fragment_index
may not be zero).

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

.SH RETURN VALUE
Upon successful completion,
.FN gd_alter_affixes
returns zero.  On error, it returns a negative-valued error code.  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 supplied
.ARG prefix
or
.ARG suffix
contained invalid characters.
.DD GD_E_BAD_DIRFILE
The supplied dirfile was invalid.
.DD GD_E_BAD_INDEX
The supplied index was out of range.
.DD GD_E_DUPLICATE
The supplied affixes would result in one or more field codes duplicating an
existing field code.
.DD GD_E_PROTECTED
The metadata of the given fragment's parent fragment was protected from
change.
.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 NOTES
The function
.F3 gd_fragment_namespace
can also be used to modify the root namespace.

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

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

.SH SEE ALSO
.F3 gd_error ,
.F3 gd_error_string ,
.F3 gd_fragment_affixes ,
.F3 gd_include_affix ,
.F3 gd_open ,
dirfile(5),
dirfile-format(5)