Using One Data Form

This section guides you through the steps that display and process one Designer form in your application. This is the simplest case. If you use the Main Generator, all of these steps are automatically included in your main() module for you.

Step 1: In main.c, #include the proper header files.

The first lines in main.c are the include statements. You must #include all the appropriate header files for your application. This includes all the Vermont Views header files for the facilities you are using in your application, plus the header file listing all the function prototypes, the header file containing the function list, and the header file for the form you are using.

Note the inclusion of the Vermont Views header file vv_des.h. This header file must be included before vv_main.h in the main program and in any module that uses the Vermont Views Designer interface routines. It enables the processing of a Designer form within a Vermont Views application.

The order in which you include the header files is important. All other Vermont Views header files must be included before vv_main.h. If you are using prototyping in your code, the header file listing the function prototypes must be included before the header file containing the function list. Finally, the header file containing the data for the form must be included only in the modules where this data is actually used: the module where the form is read out of the library, the modules where the form is processed, and the modules where the data in the variables are initialized or used.

Step 2: Declare, allocate storage for, and initialize the data variables.

You must allocate memory for the data structure holding the underlying data variables either from the stack or from the heap. If you allocate memory from the stack, you need only declare a variable for the data structure. Check your header file for the typedef name of the data structure used for your form. For example, if your form is called des_form, the Designer gives the data structure a typedef name of DES_FORM. The statement to allocate this data structure on the stack is as follows:

DES_FORM des_data;

Variables and data structures allocated from the stack are not initialized. To avoid having garbage displayed in the fields, you should do one of the following:

• Initialize the individual members of your data structure.
  
  
• Use the ANSI C function mem_set() to initialize the entire structure to zeros.
  
  
• Set the INITIALBLANKS option to ON for each of your data fields.

If you want to allocate memory for the data structure from the heap, you need to declare a variable for a pointer to the structure containing the underlying data variables. In this example, the statement would be as follows:

DES_FORM *des_datap;

Then you must allocate storage from the heap by using the function mem_get():

mem_get() allocates a block of memory of the specified size in bytes and returns a pointer to the allocated memory or NULLP on error. The allocated bytes are initialized to zero. In the example, the call would be as follows:

des_datap = (DES_FORM *) mem_get( sizeof(DES_FORM) );

Note that you must cast the allocated memory to be a pointer to a DES_FORM structure type.

Step 3: Declare a library pointer and a form pointer.

Declare a pointer to a library and a pointer to a form. The code for the example form is as follows:

DFORMPTR dfmp;

/* Pointer to form

*/

DLIBPTR dlibp;

/* Pointer to library

*/

DFORMPTR and DLIBPTR are Vermont Views defined data types. DFORMPTR is a typedef for a pointer to a data form structure. DLIBPTR is a typedef for a pointer to a Designer library structure. The structure definitions can be found in the "Structures" section of the Function Reference.

Step 4: Open the library containing the form.

Before you can use the form, you must open the library file that contains the form. Opening a Designer library is done with the Designer library open function dl_open():

DLIBPTR dl_open(lib_name_stp)

UCHAR *lib_name_stp;

/* Name of library file to open

*/

dl_open() opens the file specified in the call and uses the data in the file to initialize a library structure. A pointer to the library structure is returned.

In applications using several library files, you can keep as many library files open as the operating system can handle. Under PCDOS, this is determined by the number of FILE entries in the config.sys file for the machine.

Step 5: Get the form from the library.

Once the library is open, the form can be read into memory with dl_fmget(). This function allocates memory for a form structure and then initializes it from the information it reads from the library about the form. dl_fmget() returns a pointer to the initialized form structure. In addition to initializing the data form structure, dl_fmget() can resolve all external references to data, functions, and choice list memory files that the form uses.

The call is as follows:

DFORMPTR dl_fmget(fmname_stp, datastructp, funclistp, clist_mfp, dlibp)

UCHAR *fmname_stp;        /* Name of data form to get from library        */

PTR datastructp;            /* Pointer to data structure to            */

                        /* hold data collected from form            */

FUNCLISTPTR funclistp;        /* Pointer to list                     */

                        /* containing functions called from form        */

MFILEPTR clist_mfp;        /* Pointer to memory file                  */

                        /* holding choice lists used by fields        */

DLIBPTR dlibp;            /* Pointer to library                    */

By default, while the form is being read out of the library, dl_fmget() locks the library and no other user can use the library. After reading the form, dl_fmget() unlocks the library. To learn more about Designer library locking and security of the library for distributed applications, see Chapter 52, "Preparing Your Application for Distribution."

You do not have to resolve all external references when you read the form out of the library with dl_fmget(). If you pass NULLP for the datastructp, funclistp, or clist_mfp, these references are not resolved. Functions are provided so that you can resolve the data pointer, function, or choice list memory file references at another time. These functions are described later in this chapter.

Step 6: Use the form.

From this point, you can use any of the Vermont Views functions that take a form pointer to act on the Designer form. In our example, we process the form with a call to fm_proc().

Step 7: Free the form.

dl_fmget() allocates a form structure and then initializes it based on the information found in the library for the specified form. You must pair a call to dl_fmget() with fm_free() so that this form structure is freed:

void fm_free(dfmp)

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

Step 8: Free allocated memory.

If you have allocated memory from the heap for any data variables associated with the data form, you must free that memory. You can use the memory free function, mem_free():

void mem_free(p)

PTR p;    /* Pointer to allocated memory        */

Step 9: Close the library.

After you read the form out of the library, the library file can be closed. This is accomplished with the Designer library close function, dl_close():

int dl_close(libp)

DLIBPTR libp;    /* Pointer to library to close        */

The following code example uses the Designer form des_form stored in the library des_tut.vvd. This example is available in the tutorial des_form.c. The form includes fields for first and last name, job type, date of birth, age, and salary. The data structure for this form, as generated by the Designer, is as follows:

typedef struct    /* Data form data structure            */

{

    UCHAR first_name[20];

    UCHAR last_name[20];

    UCHAR job_type[15];

    UCHAR dob[10];

    int age;

    long salary;

} DES_FORM;

The des_form.c file included here demonstrates the steps needed to use a Designer form in an application. To keep the keep examples simple, tutorial code does no error checking.

#include <vv_str.h>        /* String fields on des_form            */

#include <vv_date.h>        /* Date fields on des_form            */

#include <vv_int.h>        /* Integer fields on des_form            */

#include <vv_dec.h>        /* Decimal fields on des_form            */

#include <vv_help.h>        /* Enable the help system            */

#include <vv_des.h>        /* Use Designer form                */

#include <vv_main.h>        /* Include global system declarations    */

#include <prototyp.h>        /* Function prototypes for form        */

#include <des_tut.h>        /* Function list for all functions        */

#include <des_form.h>        /* Data structure for des_form            */



#ifdef LINT_ARGS

int CDECL main(void);

#else

int CDECL main();

#endif



int CDECL main()

{

    DES_FORM des_data;        /* Local storage for des_form data        */

    DFORMPTR dfmp;            /* VV form pointer for read in form        */

    DLIBPTR libp;            /* VV Designer library pointer        */



    vv_init();            /* Initialize Vermont Views            */

    vs_clr();            /* Clear the screen                */



    /* Open the Designer library "des_tut.vvd"                    */

    libp = dl_open("des_tut.vvd");



    /* Read out "des_form" store data in des_data, use function list    */

    /* des_tut, there is no choice list                        */

    dfmp = dl_fmget("des_form", &des_data, des_tut, (MFILEPTR)NULLP,

                libp);

    dl_close(libp);        /* Close the Designer library            */

    fm_proc(0, dfmp);        /* Process the form                */

    fm_free(dfmp);          /* Free the form                    */

    vv_exit();            /* Exit Vermont Views            */

    return(0);

}