C-API Overview Foundation

The C-API of Xbase++ is provided for C developers. Using the C-API, functions developed in C can be used with Xbase++. The __cdecl convention is used for both Xbase++ functions and C-API functions.

After compilation, the C-code may be treated like Xbase++ object files. It can simply be linked into the Xbase++ application either static or as a DLL. It is not possible to use 16 bit code with Xbase++. Note that for the debugging of C code within a Xbase++ application, a C-Debugger must be used.

Important: The declaration for a C function to be called from Xbase++ looks like this:

XPPRET XPPENTRY xppFunction(XppParamList paramList); 

The functions can then be called from Xbase++ with any parameters. In order to be able to call the C-function via macro expressions, the Xbase++ code must have the following statement:

REQUEST xppFunction 

This is true even if the function is already called in normal Xbase++ code.

Important:

To ensure correct operation, each function called from Xbase++ must post a return value using either one of the _ret...()functions or _conReturn(). If a return value is not posted, the result is unpredictable and can lead to a process hangup. This also applies to procedures which are defined as functions with a return value of NIL. Also, all functions must be re-entrant, since Xbase++ applications are multi-threaded.

As long as the multi-threading C-library is used, almost no limitations relating to the use of C-library functions exist. For example, although the memory-API makes complete memory management available, malloc() can also be used without a problem. However, some functions (e.g. printf) require that the C-library is initialized first. These subjects are discussed in the following chapters.

Note that the Xbase++ libraries must always be linked before the C-libraries. Otherwise it is not guaranteed that the program is initialized as an Xbase++ application.

If you are using a C-compiler which defines the same calling convention as XPPENTRY for the following standard C-library functions, there will be a name conflict between them and the standard Xbase++ functions:

abs()    exp()    fclose()   ferror()   fopen() 
fread()  fseek()  fwrite()   getenv()   log() 
sqrt()   time() 

In this rare case, these C-functions cannot be used if the C-Code is linked statically into the Xbase++ application because they are exported both from the C-library and from the Xbase++ import library. If one of these functions is needed, the C-code has to be linked into a separate DLL. Most C-compilers define a different calling convention for built-in functions, though.