Difference between revisions of "SDK Shared Library Functions"

From Recital Documentation Wiki
Jump to: navigation, search
 
 
(One intermediate revision by one user not shown)
Line 1: Line 1:
{{todo: paths etc to be updated}}
 
 
 
'C' functions defined in shared libraries can be used with the following Recital products:
 
'C' functions defined in shared libraries can be used with the following Recital products:
  
Line 7: Line 5:
 
!Product||Executables
 
!Product||Executables
 
|-
 
|-
|Recital Terminal Developer for Linux||<path>/db.exe
+
|Recital for Linux/UNIX||<path>/db.exe
|-
+
|Recital Terminal Developer for UNIX||<path>/db.exe
+
|-
+
|Recital Terminal Developer for Windows||<path>/db.exe
+
 
|-
 
|-
|Recital Server for Linux||<path>/db_netserver
+
|Recital Server for Linux/UNIX||<path>/db_netserver
<path>/db_recserver
+
|-
+
|Recital Server for UNIX||<path>/db_netserver
+
 
<path>/db_recserver
 
<path>/db_recserver
 
|-
 
|-
Line 23: Line 14:
  
 
==Defining the C functions==
 
==Defining the C functions==
 
Samples to demonstrate the usage of shared libraries are included in the following directories:
 
 
 
{| class="wikitable"
 
!Product||Default API Linked Directory
 
|-
 
|Recital Terminal Developer for Linux||<path>/sdk/api/shared
 
|-
 
|Recital Terminal Developer for UNIX||<path>/sdk/api/shared
 
|-
 
|Recital Terminal Developer for Windows||<path>/sdk/api/shared
 
|-
 
|Recital Server for Linux||<path>/api/shared
 
|-
 
|Recital Server for UNIX||<path>/api/shared
 
|-
 
|}
 
 
 
 
The shared library must include the following four elements:
 
The shared library must include the following four elements:
  
Line 101: Line 72:
 
==Using the 'C' functions and classes:==
 
==Using the 'C' functions and classes:==
  
Shared libraries are loaded using the SET LIBRARY TO <library> [ADDITIVE] command.  By default library files are accessed from the directory defined by the DB_LIBDIR environment variable.  This is set in the 'profile' file of the Recital product:
+
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 Files|configuration file]].
 
+
 
+
{| class="wikitable"
+
!Product||Profile
+
|-
+
|Recital Terminal Developer for Linux||<path>/profile.db
+
|-
+
|Recital Terminal Developer for UNIX||<path>/profile.db
+
|-
+
|Recital Terminal Developer for Windows||<path>/profile.db
+
|-
+
|Recital Server for Linux||<path>/profile.uas
+
|-
+
|Recital Server for UNIX||<path>/profile.uas
+
|-
+
|}
+
 
+
  
By default, [[DB_LIBDIR]] is set to the sharedlib sub-directory of the recital root.  If full path information is specified, the shared library files can be loaded from other directories, e.g.
+
If full path information is specified, the shared library files can be loaded from other directories, e.g.
  
  
Line 132: Line 86:
  
  
The Recital/4GL function [[LOADLIBRARY()|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 Recital function [[LOADLIBRARY()|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|SET LIBRARY TO]] or [[RELEASE LIBRARY|RELEASE LIBRARY <library>]] commands are used to close all or specified shared libraries.
 
The [[SET LIBRARY|SET LIBRARY TO]] or [[RELEASE LIBRARY|RELEASE LIBRARY <library>]] commands are used to close all or specified shared libraries.
  
The Recital/4GL [[LIST PROCEDURE]] and [[DISPLAY PROCEDURE]] commands include loaded shared library function names in their listings and the Recital/4GL [[LIST CLASSES]] and [[DISPLAY CLASSES]] commands include loaded shared library class names in their listings.
+
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.
 
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.

Latest revision as of 16:42, 2 March 2010

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


Product Executables
Recital for Linux/UNIX <path>/db.exe
Recital Server for Linux/UNIX <path>/db_netserver

<path>/db_recserver


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.