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_CANCEL CANCEL
U_CHANGED user edit field changed
U_DELETE DELETE a record
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_PREVFORM unused
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.