DP4 C Program Structure

The code below shows a skeleton DP4 C program. 

 1
 2
 3 
 4 
 5 
 6 
 7 
 8 
 9
10
11
12 
13 
14
15
16
17
18
 
   /* Template for DP4 C programs */

   /*
   #c
   #db SALESORD
   #private
   #tables CUSTOMER,
           REGION;
   #end
   */

   #include "dp4capi.h"
   #include "template.h"

   void process()
   {
     /* Your code goes here! */
   }

The first thing you will notice is there appears to be (almost) no code! However the comment beginning at line 3 contains lines that are ignored by the C compiler, but processed by the DP4 LIBMAKE program, to generate the include file template.h . These lines are called directives, and always start with a hash sign. Lines 4-9 of the template above contain 5 LIBMAKE directives:

  1. #c tells LIBMAKE to generate an include file for the C language. LIBMAKE also supports C++, Delphi, VB, and several other languages.

  2. #db salesord selects the database used to generate the include file. In this case the include file will also contain initialisation and termination functions that open and close the database.

  3. #private enables the DP4 "private database" facility discussed elsewhere.

  4. #tables introduces a list of DP4 tables for which appropriate structures (and variables) are declared in the template.h include file.

  5. #end tells LIBMAKE there are no more DP4 directives in the file.

You can learn more about LIBMAKE and these directives in Using LIBMAKE to Generate Code and Declarations.

After the LIBMAKE directives, two standard #include statements appear. The first one is: #include "dp4capi.h"
DP4CAPI.H (formerly DATAFIT.H) is provided as part of DP4 and must be accessible to your C program as an include file. It contains definitions of all the functions and global variables mentioned in this manual. Older programs may include the file DP4.H instead of DP4CAPI.H. DP4.H enables some old names for various DP4 APIs and variables.

The second #include statement specifies the file that LIBMAKE generates. This will have the same name as your program, but with the file extension .h (at least for C programs). For example, if your program is called enquiry.c, use the statement: #include "enquiry.h" The contents of this file are described here. You can, of course, use the #include statement for any other include files. We recommend that standard include files such as stdlib.h are included before any other include files, using the <> form of the #include statement. This minimises any potential problems with clashing declarations.

Following the include files you can include any other declarations required by your program. Although C and C++ permit great flexibility in the order of declarations we recommend that you adhere to some well-defined standard such as putting #define pre-processor directives first, then any typedefs, then variable declarations, and then forward declarations of the functions in this source module arranged in order of definition (and we recommend functions are ordered top down rather than bottom up).

You must also provide a function called process() that contains the main loop of the program.

Where did main() go?

DP4 C programs typically begin with process() rather than main() (or WinMain()) because the DP4 C library has a main() that loads and enables the DP4 database API and the DP4 User interface API. A variant of this main(), which only enables the database API, is supplied in the file NOTRM.C. The process() function can be declared as void process(int argc,char **argv) if desired, though you won't usually need to do this as the DP4 C API also contains functions for processing command line options that can be called from anywhere in a program.

If you really want to you can provide your own main() function, but in this case you will need to include your own code to load and enable DP4 APIs. You can adapt the code contained in the source file CCMAIN.C or NOTRM.C in this case.

If you want to pass an exit code back to the operating system when your program terminates you can call the function dp4_halt() which is analogous to the standard C exit() function, and in fact calls it as its last operation. You should not call exit() directly because this will bypass the normal DP4 termination code. (In order to minimise its use of the ANSI C runtime library DP4 does not itself use the atexit() function). If a program exits by returning from process() it will return exit code 0.

If you wish you can declare process() with two parameters like this:

void process(int argc,char **argv)

This may be useful if you want to perform your own command line analysis, or adapting a previously written program that did not use DP4. However, it is more usual to use the DP4 tail_() functions to do this, and these don't need the argc or argv variables.