3.3 Writing a User Edit Routine

Form calls your user edit routine many times during the data entry session; whenever form's mode changes (as a response to the operator pressing a form function key), and when fields have changed.

The user edit routine is called with five parameters:

user_edit (type, edit_name, old_value, new_value, exit_char)

int type; /* type of edit to be done */

char *edit_name; /* edit name for field */

char *old_value; /* old field value */

char *new_value; /* new field value */

int exit_char; /* character typed to exit field */

The first parameter, type, describes the user edit action; the reason form is calling your user_edit routine. This parameter contains a constant defined in the file \cbase\include\cbase\form.h, and these constants can be included in the program file with the statement:

#include <cbase/form.h>

The constants defined here are:

User Edit Types

U_ADD enter ADD mode; beginning of ADD

U_BADDELETE delete failed

U_BADUPDATE update failed

U_BEGINFORM beginning of a form

U_BEGINVAL begin validation form


U_CHANGED user edit field changed


U_DIE HANGUP signal received

U_ENDVAL end validation form

U_ENTERFIELD enter user edit field

U_EXIT termination

U_FILEFULL prepared record not stored

U_FIND FIND a record

U_FIRSTFORM go to the first form

U_FKEY unknown function key

U_INITIALIZE initialization

U_MATCH record found after FIND

U_NEXTFORM go to the next form

U_PREPARE STORE after an ADD or UPDATE; prepare record


U_QUERY enter QUERY mode

U_STORED prepared record stored in file

U_UPDATE enter UPDATE mode; beginning of UPDATE

U_USEREDIT exit user edit field

Your user_edit routine should return NULL if it is called with a value of type that is not in the above list, or is a value that your user_edit routine does not use. This will increase the odds that your program will work with a future version of form.

The values passed in the other parameters depend upon the value of the type parameter. In all cases, form performs all its edit checking before calling the user edit routine. If the user edit routine returns a pointer to a string, that string is written as an error message on the screen, and the function is not performed.

If the user edit routine returns a NULL pointer, the function requested will be performed. Otherwise, the user edit routine must return a pointer to a character string that form displays as an error.