NAME

       gd_put_string — write a STRING or SARRAY element to a Dirfile database

SYNOPSIS

       #include <getdata.h>

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

DESCRIPTION

       The gd_put_string() function queries a dirfile(5) database specified by dirfile and stores
       the character  string  data_in  in  the  STRING  or  SARRAY  scalar  field,  specified  by
       field_code.   If field_code specifies a SARRAY field, the supplied string is stored as the
       first element.

       The dirfile argument must point to a valid DIRFILE object previously created by a call  to
       gd_open(3).

       Because  string  values  are  stored  in the dirfile metadata, the new value of field_code
       won't be written to disk until the dirfile metadata is flushed  with  gd_metaflush(3),  or
       until the dirfile is closed with gd_close(3).

       The  gd_put_sarray(3) function provides another way of storing STRING and SARRAY data to a
       Dirfile.

RETURN VALUE

       On success, gd_put_string() returns zero.  On error, this a  negative-valued  error  code.
       Possible error codes are:

       GD_E_ACCMODE
               The specified dirfile was opened read-only.

       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 referred to a field of type other than SARRAY or STRING.

       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 string 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 put_string() function apepared in GetData-0.4.0.   It  returned  a  size_t  cotnaining
       length of the string written, or zero on error.

       In GetData-0.7.0, this function was renamed to gd_put_strint().

       In  GetData-0.10.0,  this function's return value changed to zero on success, or or else a
       negative-valued error code.

SEE ALSO

       dirfile(5),    gd_close(3),     gd_get_string(3),     gd_error(3),     gd_error_string(3),
       gd_metaflush(3), gd_open(3), gd_put_sarray(3).