Difference between revisions of "SDK Shared Library Functions"

Revision as of 16:41, 2 March 2010

'C' functions defined in shared libraries can be used with the following Recital products:

Defining the C functions

The shared library 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 objects included in the library:

// Recital API function address table 
static		struct 	API_FUNCTION_ADDRESS_TABLE	*api_function_address_table = NULL;
 
// Add all functions and objects  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.
int	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.
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 system-wide configuration file.

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

// pdf.so is in the DB_LIBDIR directory
set library to pdf
 
//mylib.so is in /usr/recital/myapplibs
set library to /usr/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.