NAME

   dced_hostdata_create - Creates a hostdata item and the associated
                          entry in dced on a specific host

 SYNOPSIS

   #include <dce/dced.h>

   void dced_hostdata_create( dced_binding_handle_t  dced_bh,
                              dced_entry_t           *entry,
                              dced_attr_list_t       *data,
                              error_status_t         *status );

 PARAMETERS

   Input

   dced_bh
       Specifies the dced binding handle for the host data service
       on a specific host.

   Input/Output

   entry
       Specifies the hostdata entry to create.  You supply a name
       (entry->name), description (entry->description), and file
       name (entry->storage_tag), in the form of dced strings.  You
       can supply a UUID (entry->id) for dced to use or you can use
       a NULL value and dced will generate a new UUID for the entry.

   Input

   data
       Specifies the data created and written to a file on the host.
       The dced_attr_list_t consists of a count of the number of
       attributes, and an array of attributes of type sec_attr_t.
       The reference OSF implementation has one attribute for a
       hostdata item (file contents).  However some vendors may
       provide multiple attributes.

   Output

   status
       Returns the status code from this routine.  This status code
       indicates whether the routine completed successfully or, if
       not, why not.  The possible status codes are:

            error_status_ok
            db_s_key_not_found
            db_s_readonly
            db_s_store_failed
            dced_s_already_exists
            dced_s_bad_binding
            dced_s_cant_open_storage_file
            dced_s_import_already_exists
            dced_s_unknown_attr_type
            sec_acl_invalid_permission

 DESCRIPTION

   The dced_hostdata_create() routine creates a new host data item in
   a file on the host to which the dced binding handle refers, and it
   generates the associated hostdata entry in the host's dced.

   If data that you want to add to the host data service already exists
   on the host (in a file), you can add it to the service by calling
   dced_entry_add(), which only creates the new data entry for dced.

   Prior to calling the dced_hostdata_create() routine, the
   application must have established a valid dced binding handle
   to the hostdata service by calling either the dced_binding_create()
   or dced_binding_from_rpc_binding() routine.

 EXAMPLES

   The following example creates a binding to the host data service
   on the local host, creates the entry data, and fills in the data
   structure for one attribute to a hypothetical printer configuration.
   The attribute represents a plain-text file containing one string of
   data.

        dced_binding_handle_t    dced_bh;
        error_status_t           status;
        dced_entry_t             entry;
        dced_attr_list_t         data;
        int                      num_strings, str_size;
        sec_attr_enc_str_array_t *attr_array;

        dced_binding_create( dced_c_service_hostdata,
                             dced_c_binding_syntax_default,
                             &dced_bh,
                             &status );

        /*Create an Entry. */
        uuid_create(&entry.id, &status);
        entry.name        = (dced_string_t)("NEWERprinter");
        entry.description = (dced_string_t)
                            ("Configuration for a new printer.");
        entry.storage_tag = (dced_string_t)("/etc/NEWprinter");

        /* create the attributes */
        data.count  = 1;
        num_strings = 1;
        data.list   = (sec_attr_t *)
                      malloc( data.count * sizeof(sec_attr_t) );
        data.list->attr_id = dced_g_uuid_fileattr;
        data.list->attr_value.attr_encoding =
                                   sec_attr_enc_printstring_array;
        str_size    = sizeof(sec_attr_enc_str_array_t) + num_strings
                      * sizeof(sec_attr_enc_printstring_p_t);
        attr_array  = (sec_attr_enc_str_array_t *)malloc(str_size);
        data.list->attr_value.tagged_union.string_array = attr_array;
        attr_array->num_strings = num_strings;
        attr_array->strings[0]  = (dced_string_t)
                                  ("New printer configuration data");

        dced_hostdata_create( dced_bh, &entry, &data, &status );
        dced_binding_free( dced_bh, &status );

 RELATED INFORMATION

   Routines:   dced_entry_add
               dced_hostdata_read
               dced_binding_create
               dced_binding_from_rpc_binding

   Books: OSF DCE Application Development Guide.