The osextusr.h required header file, available in the install_path\extrc\include folder, is used to map TIBCO Object Service Broker syntax to C syntax. It contains a list of the supplied functions used to manipulate the arguments passed to TIBCO Object Service Broker. It must be in your include library during compilation.
There are no exceptions trapped during external routine invocation and execution, such as, if the external routine is not found or it fails. A message is written to the message log and a traceback is generated if a failure occurs.
Key Elements The key elements in the prototype are:
Sample Routines for Compiling and Linking under Windows The following contains a set of sample external routines for Windows. As noted in the comments, they implement a function rule and a procedure rule:
the arguments passed from TIBCO Object Service Broker. */
This function accepts two arguments: a cost and a tax rate.
It returns the cost with the tax applied. If an access
routine fails (indicated by the return of a value of -1)
the external routine returns immediately.
/* Get first argument. */
if (hrnGetDoubleArg (param, 1, &cost))
/* Get second argument. */
if (hrnGetDoubleArg (param, 2, &tax_rate))
/* Calculate total cost with tax. */
taxed_cost = cost + cost * tax_rate;
/* Set returned value. Returned value is placed in
parameter in position 0.*/
if (hrnSetDoubleArg (param, 0, taxed_cost))
This function accepts one arguments: a string. It modifies
the string by concatenating "HELLO WORLD". If an access
routine fails (indicated by the return of a value of -1) the
external routine returns immediately.
char *concat_string = "HELLO WORLD";
int concat_string_length = 11;
/* Get the length of the string argument.
If a negative string length is returned,
the access function failed - return immediately. */
string_length = hrnGetCharArgLen (param, 1);
/* Allocate and initialize memory for the length of the
string plus the concatenation string length plus the
trailing '\0' character. Return if unable to allocate the
string_length + concat_string_length + 1);
string_length + concat_string_length + 1);
/* Get string argument. Concatenate "HELLO WORLD" to
if (hrnGetCharArg (param, 1, pszstring,
strcat (pszstring, concat_string);
if (hrnSetCharArg (param, 1, pszstring))
Sample Import/Export Definitions File The sample code for the Import/Export definitions (
test.def) is:
Sample Routines for Compiling and Linking under Solaris The following contains a set of sample external routines for Solaris:
if (hrnGetIntArg (param, 1, &op1))
if (hrnGetIntArg(param, 2, &op2))
if (hrnSetIntArg(param, 0, sum))
External Routine for the Windows Platform The external routine DLL can be built with any compiler able to produce 32-bit code compatible with the Microsoft Visual C++ runtime environment. The DLL must be linked with the osextusr.lib import library.
Compiling and Linking External Routines on Solaris On Solaris, external routines are compiled as shared libraries. Use the following commands to create a C
++ version of the shared libraries.
In this example, install_path refers to the TIBCO Object Service Broker installation folder:
-U_XOPEN_SOURCE -D_XOPEN_SOURCE -D__EXTENSIONS__ -D_REENTRANT\
-I<install_path>/extrc/include extrtest.c
So that external routines can call functions external to TIBCO Object Service Broker, the libraries containing these functions must reside in the search path for osMon. In Windows, this is in the PATH environment variable. In Solaris, this is in the LD_LIBRARY_PATH.
The external routine and its load module name are identified to TIBCO Object Service Broker through an entry in the ROUTINES table. If the routine has arguments, these are specified in a table instance of the ARGUMENTS table. Ensure that you have adequate security to insert data into these tables before editing them.
Use the Table Editor to add information to these tables. To use this option, enter the required table name beside the ED edit table option on the workbench and press Enter to display the table.
|
|
|
The language in which the external routine is written. This field is used for descriptive purposes only and is not required. Syntax: C, Length: 16
|
|
|
|
If the external routine is a function, specify the TIBCO Object Service Broker semantic type of the value returned. Syntax: C, Length: 1
|
|
If the external routine is a function, specify the TIBCO Object Service Broker syntax of the value returned. Syntax: C, Length: 1
|
|
|
|
If the external routine is a function that returns a value with digits to the right of the decimal, specify the number of digits. Syntax: B, Length: 2
|
|
This name must be exported uppercase in the exports definition file. The symbol to be loaded can be lowercase or mixed case in the external routine, but it must be exported uppercase to the LOADNAME field.
|
|
The point when the external library is unloaded. At present the only valid value is SESSION (that is, the external library must be unloaded when the session ends).
|
|
NODENAME can be either left blank or set to @SESSION, meaning that the C routine executes in the same process as the Execution Environment. Syntax: V, Length: 255
|
|
Specify the full path name of the C routine. It must be a dynamic link library for Windows or a shared object library for Solaris. Syntax: V, Length: 255
|
If your external routine has arguments, to identify the arguments to TIBCO Object Service Broker add a table instance to the ARGUMENTS table. The parameter value for the table instance of the ARGUMENTS table must be the name of the external routine (that is, the value in the
NAME field of the ROUTINES table). You can have a maximum of 16 arguments.
TIBCO Object Service Broker Managing Data for information about how to use the Table Editor.
TIBCO Object Service Broker Programming in Rules about valid TIBCO Object Service Broker syntax and semantic data types.