ETI forms

Setting and reading the field status

Every field has an associated status flag that is set whenever the field's value (field buffer 0) changes. The following functions enable you to set and access this flag.

SYNOPSIS

   int set_field_status (field, status)
   FIELD  field;
   int status;
   
   int field_status (field)
   FIELD  field;

The field status is TRUE if set or FALSE if cleared. By default, the field status is FALSE when the field is created.

These routines promote increased efficiency where processing need occur only if a field has been changed since some previous state. Two examples are undo operations and database updates. Function update in ``Using the field status to update a database'' for instance, loops through your field pointer array to save the data in each field if it has been changed (if its field_status is TRUE).

   void update (form)
   FORM * form;
   void save_field_data (f)
   FIELD * f;
   {
   	char * data = field_buffer (f, 0);  /* fetch data in field */
   
   	/* save data */
   

   }
   

   {
   	FIELD ** f = form_fields (form);  /* fetch pointer to field pointer array */
   

   	while (*f)
   	{
   		if (field_status (*f))        /* field data changed ? */
   		{
   			save_field_data (*f);          /* yes, save new data */
   			set_field_status (*f, FALSE);  /* set field status back */
   		}
   		++f;
   	}
   }

Using the field status to update a database

If successful, set_field_status returns E_OK. If not, it returns the following:

E_SYSTEM_ERROR -: system error

The initial ETI default field status is clear. As always, you can change the default by passing set_field_status a NULL field pointer.

Like the function field_buffer, function field_status always returns the correct value if the field is not current. However, if the field is current, the function is sometimes inaccurate because the status flag is not set immediately. You may rest assured that field_status is accurate on the current field if

it is called from the field check validation routine, if any
it is called from the form or field initialization or termination routines, if any
it is called just after a REQ_VALIDATION request to the form driver

See the sections ``Creating a field type with validation functions'', ``Establishing field and form initialization and termination routines'' and ``Field validation requests'' for details on these routines.