Difference between revisions of "SDK Dynamic Link Library Functions"

Latest revision as of 16:38, 2 March 2010

'C' functions and classes defined in dynamic link libraries (DLLs) can be used with the following Recital products:

Defining the C functions

The main source file for the DLL must include the following four elements:

The include file "dbapi.h"

#include "dbapi.h"

The API_SHARED_FUNCTION_TABLE structure

Used to define the 'C' functions and classes included in the library:

// Recital API function address table 
static		struct 	API_FUNCTION_ADDRESS_TABLE	*api_function_address_table = NULL;
 
// Add all functions to this structure as follows:
//	Recital Name,	C Function Name ,	Type
//
// Make sure the last entry is NULL.
//
static		struct	API_SHARED_FUNCTION_TABLE	api_function_table[7] = {
			{"schar",		"fnSamplesCharacter", 	API_FUNCTION},
			{"stype",		"fnSamplesType",		API_FUNCTION},
			{"slog",		"fnSamplesLogical",	API_FUNCTION},
			{"snum",		"fnSamplesNumeric",	API_FUNCTION},
			{"sopen",	"fnSamplesOpen",		API_FUNCTION},
			{"myclass", 	"clsMyClass",		API_CLASS},
			{NULL,		NULL,				-1}
} ;

The initAPI() function

// This function is used to define function addresses for API calls.
// C++ example
extern "C" int WINAPI EXPORT initAPI(struct	API_FUNCTION_ADDRESS_TABLE *function_address_table)
{
	api_function_address_table = function_address_table;
	return 0;
}

The getFunctions() function

// This function is used to return the function names of the API.
// C++ example
extern "C" struct API_SHARED_FUNCTION_TABLE *getFunctions(void)
{
	return api_function_table;
}

Using the 'C' functions and classes

Shared libraries are loaded using the SET LIBRARY TO <library> [ADDITIVE] command or the REQUIRE(), REQUIRE_ONCE(), INCLUDE() or INCLUDE_ONCE() functions. By default library files are accessed from the directory defined by the DB_LIBDIR environment variable. This is set in the Recital Server Manager Settings.

If full path information is specified, the shared library files can be loaded from other directories, e.g.

// pdf.dll is in the DB_LIBDIR directory
set library to pdf
 
//mylib.dll is in C:\Program Files\Recital\Myapplibs\myapplibs
set library to "C:\Program Files\Recital\Myapplibs\mylib"

The Recital function LOADLIBRARY(<library>) can also be used to load additional shared libraries. The name of the shared library file including the full path and file extension must be specified.

The SET LIBRARY TO or RELEASE LIBRARY <library> commands are used to close all or specified shared libraries.

The Recital LIST PROCEDURE and DISPLAY PROCEDURE commands include loaded shared library function names in their listings and the Recital LIST CLASSES and DISPLAY CLASSES commands include loaded shared library class names in their listings.

Loaded shared library functions can be used in the same way as an internal Recital function. Loaded shared library classes can be used in the same way as Recital system classes.