gd_put_sarray, gd_put_sarray_slice — write STRING or SARRAY data to a Dirfile database
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);
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.
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:
- The specified dirfile was opened read-only.
- The library was unable to allocate memory.
- The field specified by field_code was not found in the database.
- An invalid dirfile was supplied.
- The supplied field_code was not a STRING nor a SARRAY.
- A request for data beyond the end of the field was made.
- 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.
- 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).
The gd_put_sarray() and gd_put_sarray_slice() functions appeared in GetData-0.10.0.
|25 December 2016||Version 0.10.0|