Defining Data Fields and Prompt Text with fld_def()

A data field and its associated prompt are defined using the field definition function, fld_def():

DFIELDPTR fld_def(prompt_rb, prompt_cb, prompt, fld_cb, picp, fld_type, datap, dfmp)

int prompt_rb;        /* Beginning row for prompt string            */

int prompt_cb;        /* Beginning column for prompt string        */

char *prompt;        /* Prompt string                        */

int fld_cb;            /* Column for field to begin in            */

char *picp;            /* Picture string                        */

int fld_type;        /* Type of data field                    */

PTR datap;            /* Pointer to data variable                */

DFORMPTR dfmp;        /* Pointer to a data form                */

Naming Tip: All functions that deal with data fields contain the abbreviation "fld".

The arguments of fld_def() define where the field is located on the form, the prompt associated with the field, the type of data that can be entered in the field, and where the entered data should be placed. An explanation of each of the arguments in fld_def() follows.

Specifying the Prompt and Its Location (prompt_rb, prompt_cb, prompt)

The first three parameters specify the location of the prompt and the prompt string that accompanies the data field. The coordinate at which the prompt string is to start is specified with prompt_rb and prompt_cb. It is important to remember that these coordinates are measured relative to the origin of the working area of the form (not the screen). Since you cannot place items on the borders, the working area of the form is considered to be within the border. Thus, the coordinate (0,0) is just inside the border of the form.

If you do not want to specify a prompt for a field, specify NULLP as the prompt string and the location at which the field should start for prompt_rb and prompt_cb.

Specifying Where the Field Is Located (fld_cb)

The field is located on the form based on the value of the fld_cb argument. If you specify a column number, the field will start on the same row as the prompt and at the specified column, that is, at (prompt_rb, fld_cb).

You can also specify one of the following special values for fld_cb:

In the example program, both fld_def() calls have FADJACENT for the fld_cb argument. This means that the field starts immediately after the prompt string. Note the extra spaces that were put at the end of the prompt strings so the two fields would line up on the form.

Specifying What Can Be Entered in the Field (picp)

For the picp argument, you specify a picture string. A picture string is composed of picture control characters that specify the length of the data field and what characters the user can enter in the field. Table 6.3 lists the picture control characters and what characters they allow to be entered.

Table 6.3: Picture Control Characters

In the fld_def() call for the last name field, the picture string is an '!' followed by 13 Xs. The picture control characters 'X' and '!' allow the user to enter any printable character. Thus, the user can enter fourteen printable characters in the field, and the first character in the field is automatically converted to an uppercase character.

The picture string for the phone number field is (UUU)UUU-UUUU and signifies that the user can only enter spaces and the digits 0 to 9 for each 'U' in the picture string. The parentheses and hyphen in the picture string are protected characters in the field. Any character that is not a valid picture control character for the field type is a protected character for that field. Protected characters appear in the data field, but the user will skip over these places in the field when entering characters in the field. Field pictures and protected characters are discussed in detail in Chapter 7, "Standard Data Field Types."

In the program example, picture strings for the fields are defined by explicitly typing the picture string within the fld_def() call. An alternative is to use the picture define function, pic_def(), which creates a picture string that contains a specified number of a specified control character. This function also has memory management advantages.

The call for pic_def() is as follows:

UCHAR *pic_def(pic_ch, length)

UCHAR pic_ch;        /* Picture control character            */

int length;            /* Number of characters in  picture     */

pic_def() allocates memory from the heap to hold a picture string of the specified length, fills the string with the specified picture control character, appends a terminal null character ('\0'), and returns a pointer to the string.

For example,

pic_def('X', 15)

could be substituted for an explicit string of 15 Xs, that is, "XXXXXXXXXXXXXXX". The fld_def() call would then read:

UCHAR *stp;



stp = pic_def('X', 15);

fld_def(0, 0, "Last name: ", FADJACENT, stp, F_STRING, lastname, dfmp);

pic_def() creates only "pure" strings, i.e., strings of a single character. If the picture string you need is a complicated mixture of characters, it is easiest to type it explicitly. When only one or two characters need to be different, you may find it more convenient to use pic_def() and change the defined picture string by replacing individual characters in the string.

The Vermont Views system keeps track of the memory allocated by pic_def(). When a form is freed with a call to fm_free(), the memory allocated for pictures defined with pic_def() is also freed. If many different forms are defined in the course of a program, using pic_def() instead of explicit picture strings will save significant amounts of memory.

Caution: Because pictures allocated by pic_def() are freed when a form is freed, you should be cautious about using a picture defined with pic_def() in more than one form. You must ensure that the picture is not freed before you are done using it in another form.

Specifying the Type of Data Field (fld_type)

With the fld_type argument, you specify what type of data is being collected. There is a field type for most C data types, plus a number of additional Vermont Views-defined field types. The possible field types are listed in Table 6.4.

In the example program, both fields are for entering string data, thus F_STRING is used in the call. See Chapter 7, "Standard Data Field Types," and Chapter 8, "Extended Data Field Types," for information on how to define fields for other types of data.

Table 6.4: Field Types

Specifying the Pointer to the Data Variable (datap)

Upon exit from a form, the data entered in the field will be converted to the proper data type and placed in the data variable pointed to in the call to fld_def(). fld_def() expects a pointer to this data variable in the call.

If you want to write the code that displays and collects information in a field, specify NULLP as the data pointer.

Since a string variable is, by definition in C, a pointer to an array of characters, simply specifying the variable name in the fld_def() call is correct. Chapter 7, "Standard Data Fields," and Chapter 8, "Extended Data Field Types," explain what you must do when defining fields for other types of data.

Step 6: Process the form with fm_proc().

After the form and its contents have been defined, you can display the form and give control to the user for entry of data by calling the form processing function, fm_proc():

fm_proc(start_item, dfmp)

int start_item;        /* Item to start processing at        */

DFORMPTR dfmp;        /* data form to process                */

Step 7: Transfer or use the values in the field data variables.

If you plan to reuse the data form to collect more information, you should collect the data from the variables and either use the data or store the data elsewhere (in a database, for instance). You should also reinitialize the data variables to the values you want displayed in the fields when the form is redisplayed. (You do not have to reinitialize the data variable if the INITIALBLANKS field option is set for the field.)

Step 8: Free the memory allocated for the form with fm_free().

You can use a data form repeatedly; however, if you want to free the memory for the data form structure after you are finished using it, call the form free function, fm_free():

void fm_free(dfmp)

DFORMPTR dfmp;        /* Pointer to data form to free    */

fm_free() frees all memory associated with the form. This includes all memory allocated for the active and background items on the form, the linked list of active and background items on the form, and the form structure itself.

Memory is not released for data variables, strings, and other data for which you allocated memory separately. For instance, if you allocate memory for a prompt string and use a pointer to that string in the call to fld_def(), this prompt string is not freed by fm_free(). Use mem_free() (see below) to free variables for which memory is allocated separately.

Memory Management Note: fm_def() and fm_free() are examples of how allocating and freeing memory is accomplished in Vermont Views. fm_def() and many other definition functions in Vermont Views allocate memory to hold structures and other data variables. The allocated memory can be returned to the pool of available memory when the data structures are no longer needed. Whenever a Vermont Views function allocates memory from the heap, a related function is provided to return it to the heap (to "free" it).

Step 9: Free any memory allocated for the data variables.

If you allocated memory from the heap for data variables by using the functions mem_get() or mem_stblank(), this memory must be freed separately. To do this, use the memory free function, mem_free():

void mem_free(p)

PTR p;                /* Pointer to memory to free            */

Always use mem_free() rather than standard library functions, such as free(), to release memory allocated by Vermont Views functions. Using mem_free() enables the VCS error reporting system to assist you in tracking errors.