ETI forms

Setting and reading field buffers

Recall that you set the number of additional buffers associated with a field upon its creation with new_field. Buffer 0 holds the value of the field. The following functions let you store values in the buffers and later read them.

SYNOPSIS

   int set_field_buffer (field, buffer, value)
   FIELD * field;
   int buffer;
   char * value;
   
   char * field_buffer (field, buffer)
   FIELD * field;
   int buffer;

The parameter buffer should range from 0 through nbuf, where nbuf is the number of additional buffers in the new_field call. All buffers besides 0 may be used to suit your application.

If field in set_field_buffer is a dynamic field and the length of value is greater than the current buffer size, the buffer will expand, up to the specified maximum, if any, to accommodate value. See ``Dynamically growable fields'' for more detail on dynamic fields and setting a maximum growth. If the field is not dynamic or the length of value is greater than any specified maximum field size, then value may be truncated.

As an example, suppose your application kept a field's default value in field buffer 1. It could use the following code to reset the current field to its default value.

   #define VAL_BUF		0
   #define DFL_BUF		1
   
   void reset_current (form)
   FORM * form;
   {
   	/* set f to current field, described in
   	   section "Manipulating the Current
   	   Field" below */
   

   	FIELD * f = current_field (form);
   

   	/* set field f to default value */
   

   	set_field_buffer (f, VAL_BUF,
   	   field_buffer (f, DFL_BUF));
   }

If successful, set_field_buffer returns E_OK. If not, it returns one of the following:

E_SYSTEM_ERROR -: system error
E_BAD_ARGUMENT -: NULL field pointer, NULL value, or buffer out of range

Function field_buffer, however, returns NULL if its field pointer is NULL or buffer is out of range.

The function field_buffer always returns the correct value if the field is not current. However, if the field is current, the function is sometimes inaccurate because data is not moved to field buffer 0 immediately upon entry. You may rest assured that field_buffer 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 ``Creating a field type with validation functions'', ``Establishing field and form initialization and termination routines'' and ``Field validation requests'' for details on these routines.