NAME

       gd_put_sarray, gd_put_sarray_slice — write STRING or SARRAY data to a Dirfile database

SYNOPSIS

       #include <getdata.h>

       int gd_put_sarray_slice(DIRFILE *dirfile, const char *field_code, unsigned int start,
              size_t len, const char **data_in);

       int gd_put_sarray(DIRFILE *dirfile, const char *field_code, const char **data_in);

DESCRIPTION

       The gd_put_sarray_slice() function writes string data to a dirfile(5)  database  specified
       by  dirfile  into the STRING or SARRAY scalar array field_code.  The location of the first
       element of the field into which data is stored is  given  by  start,  and  the  number  of
       elements stored is given by len.

       If  field_code  specifies  a  STRING  field, it is treated as if it were a SARRAY field of
       length one.

       The gd_put_sarray() function behaves similarly, except the whole scalar array is  written,
       as  if  gd_put_sarray_slice() were called with start equal zero and len equal to the value
       returned by gd_array_len(3).

       The argument data_in must point to an array of pointers to character  strings,  which  are
       the  values  to store.  The number of elements which will be stored by gd_put_sarray() may
       be obtained by calling gd_array_len(3).  Unlike gd_putdata(3), writing data past  the  end
       of  the  field  is  not  permitted.  To add data to a SARRAY, first increase its length by
       calling gd_alter_sarray(3), or another equivalent function.

       The gd_put_string(3) function provides another way of writing data to a STRING field.

RETURN VALUE

       On success, gd_put_sarray() and gd_put_sarray_slice() return zero.  On error, they  return
       a negative-valued error code.  Possible error codes are:

       GD_E_ACCMODE
               The specified dirfile was opened read-only.

       GD_E_ALLOC
               The library was unable to allocate memory.

       GD_E_BAD_CODE
               The field specified by field_code was not found in the database.

       GD_E_BAD_DIRFILE
               An invalid dirfile was supplied.

       GD_E_BAD_FIELD_TYPE
               The supplied field_code was not a STRING nor a SARRAY.

       GD_E_BOUNDS
               A request for data beyond the end of the field was made.

       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.

       GD_E_PROTECTED
               The fragment containing the constant was protected from change.

       The error code is also stored in the DIRFILE  object  and  may  be  retrieved  after  this
       function  returns by calling gd_error(3).  A descriptive error string for the error may be
       obtained by calling gd_error_string(3).

HISTORY

       The gd_put_sarray() and gd_put_sarray_slice() functions appeared in GetData-0.10.0.

SEE ALSO

       dirfile(5),    gd_array_len(3),    gd_sarrays(3),     gd_error(3),     gd_error_string(3),
       gd_get_sarray_slice(3), gd_open(3), gd_put_string(3)