Nesting of Header Files

Figure 2.1: Nesting of Header Files

We recommend creating your own header file that #includes all the Vermont Views header files that you will need for your application. For example, suppose you are developing an application that uses the Vermont Views data-entry facility. On your data form, you collect decimal, Boolean, string, and date information. You would then create the following header file:

Instead of #including each Vermont Views header file individually, the statement in your main program would be:

Add this statement to all other modules that call Vermont Views functions. If you later add integer fields to your application, simply edit my_header.h and recompile main() and all modules using the new facility. This saves you from making changes in your main program and in every module that #includes Vermont Views header files.

Tip for Programmers Starting a New Application: When starting a new application, it is often hard to determine which facilities of Vermont Views you might use. To save time, create your own header file that #includes all Vermont Views header files except vv_errf.h, which disables the debugging system, and vv_cua.h, which disables the Vermont Views keyboard interface and installs the CUA (Common User Access) keyboard interface. #include this header file in main() and other appropriate modules. When you are finished, delete any unneeded #include statements from this master header file and recompile.

Step 1a: (Optional) Include the header file vv_free.h in main().

The inclusion of the header file vv_free.h ensures that all memory used by Vermont Views is freed upon exit from a Vermont Views application. This is a useful feature for those applications in which the application exits Vermont Views to run another, non-Vermont Views segment and later returns to restart a new Vermont Views section.

Note that if you allocate any memory for your own use, you are responsible for freeing that memory yourself. Vermont Views only frees memory allocated by Vermont Views functions.

Step 2: Include the main header file vv_main.h in main().

File vv_main.h must be #included in the main program only. It must be the last Vermont Views header file #included in the main program. vv_main.h #includes another header file, vv_glob.h. These two files contain all of the globally-defined variables and structures used by the system. vv_glob.h contains the most frequently modified global variables.

Warning: It is important that the Vermont Views header files be the last header files #included in main() and your modules. Some naming conflicts occur between Vermont Views and certain other products if this is not the case. Notably, we #define data types in Vermont Views. Other products use TYPEDEFS for the same data types (for instance, unsigned long). Conflicts can be resolved (1) by modifying the header files to use #defines instead of TYPEDEFS or (2) by always #including our header files last.

Step 3: Initialize Vermont Views with vv_init().

Initialize Vermont Views with a call to vv_init():

vv_init();

This function initializes all of the global variables used by Vermont Views. These include variables for the size of the screen, the video mode, and the logical attribute system. In the terminal-based versions, such as XENIX, UNIX, POSIX, and VMS, vv_init() also initializes the terminal interface.

vv_init() must be called before most other Vermont Views routines. If you do not initialize the system, you will get either garbage on the screen or no screen output. If you get no screen output or only partial screen output from a program, first check to see if your main program has called vv_init().

Step 4: (Optional) Clear the screen with vs_clr().

Use the Vermont Views function vs_clr() to clear the screen when entering and exiting a Vermont Views application. vs_clr() is passed no arguments and returns no value.

Step 5: Add your application code.

Create and use data forms, menus, and windows.

Step 6: Exit Vermont Views with vv_exit().

If you are using Designer panels (data forms, menus or windows), are using a mouse, or are running on a terminal-based system, you must call vv_exit() just before returning to the operating system. vv_exit() closes any open Designer libraries before returning. It also frees memory allocated by vv_init(), and removes the mouse handler if vv_init() installed it. On terminal-based systems, Vermont Views functions change the state of the terminal, and this function restores the terminal to its original state when exiting from Vermont Views.

We recommend that you include this call in all your Vermont Views applications, regardless of whether you use Designer panels or are running on a terminal-based operating system.