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)