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  func‐
       tion.

       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-val‐
       ued 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)

Version 0.10.0                                  25 December 2016                          gd_put_sarray_slice(3)