Table of Contents
This chapter describes how to use APIs to develop applications.
TDL APIs are included in the Tmax server or client libraries and must include the tdlcall.h header file. The Tmax server supports only TCS and UCS types. Clients do not support multi threaded libraries with them. The following is a list of TDL APIs.
| API | Description |
|---|---|
| tdlcall | Calls the latest version of a dynamic module function. Can be used when VERSION is set to 1 or 2 in the TDL environment file. |
| tdlcall2 | Calls the latest version of a dynamic module function. Can be used when VERSION is set to 3 in the TDL environment file. |
| tdlcall2v | Calls the latest version of a dynamic module function. Can be used when VERSION is set to 3 in the TDL environment file. |
| tdlcall2s | Calls the latest version of a dynamic module function. Can be used when VERSION is set to 3 in the TDL environment file. |
| tdlcallva | Calls the latest version of a dynamic module function. Can be used when VERSION is set to 1 or 2 in the TDL environment file. |
| tdlcallva2 | Calls the latest version of a dynamic module function. Can be used when VERSION is set to 3 in the TDL environment file. |
| tdlcreate | Creates class instances by using Class Factory in the latest version of a dynamic module. Can be used when VERSION is set to 4 in the TDL environment file(tdl.cfg). |
| tdldestroy | Destroys class instances by using Class Factory in the latest version of a dynamic module. Can be used when VERSION is set to 4 in the TDL environment file(tdl.cfg). |
| tdlerror | When an error for tdlcall() occurs, convert it into a string form. |
| tdlgetseqno | Gets the Global Sequence number. |
| tdlstart | Starts keeping the explicit version consistency. |
| tdlend | Ends keeping the explicit version consistency. |
| tdlsuspend | Suspends keeping the version consistency. |
| tdlresume | Resumes keeping the version consistency which was suspended. |
| tdlclose | Initializes the reference count of the module to zero or directly removes the module from the memory. |
| tdlload | Loads modules into a shared memory. Can be used when VERSION is set to 1 or 2 in the TDL environment file(tdl.cfg). |
| tdlload2 | Loads modules into a shared memory. Can be used when VERSION is set to 3 in the TDL environment file(tdl.cfg). |
| tdlinit | Configures the shared memory initially. |
| tdldone | Initializes the shared memory. |
| tdlfind | Finds module index. Can be used when VERSION is set to 1 or 2 in the TDL environment file(tdl.cfg). |
| tdlfind2 | Finds module index. Can be used when VERSION is set to 3 in the TDL environment file(tdl.cfg). |
| tdlstat | Outputs TDL statistics information. Can be used when VERSION is set to 1 or 2 in the TDL environment file(tdl.cfg). MONITOR must be set to Y. |
| tdlstat2 | Outputs TDL statistics information. Can be used when VERSION is set to 3 in the TDL environment file(tdl.cfg). MONITOR must be set to Y. |
The latest version of a dynamic module function is called. This dynamic module function must have a long funcname(void *args) signature. A tdlcall function works only when the version of a TDL configuration file(tdl.cfg) is set to 1 or 2. Dynamic modules are loaded when a tdlcall() is called, and to prevent performance deterioration, they are recycled unless an update (tdlupdate) is required.
Prototype
#include <tdlcall.h> int tdlcall(char *funcname, void *args, long *urcode, int flags)
Parameter
| Parameter | Description |
|---|---|
| funcname | The name of dynamic module. (Maximum length: TDL_FUNCNAME_SIZE – 1) |
| args | An argument to a dynamic module function being called. |
| urcode | A return value from a dynamic module function. |
| flags | If set to TDLTRAN, a global sequence number must be passed using a urcode. If unspecified, a TDL_NOFLAGS will be set. |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| TDL_OPEN_ERROR | An error was returned with dlopen(). |
| TDL_SYM_ERROR | An error was returned with dlsym(). |
| TDL_CLOSE_ERROR | An error was returned with dlclose(). |
| TDL_SYSTEM_ERROR | An error with another system function calls. |
| TDL_INT _ERROR | An error with an internal library. |
| TDL_ENOFUNC | Cannot find a target module or function. |
| TDL_ENV_ERROR | An error in an environment configuration. |
| TDL_VER_ERROR | A version mismatch between the versions of a TDL shared memory and a configuration file (tdl.cfg). |
| TDL_ARG _ERROR | An error in an argument. |
| TDL_ENOLIB | Cannot find a target library. |
| TDL_TRAN_ERROR | An error while checking version consistency. |
| TDL_EINACTIVE | A module is temporarily inactive. |
The tdlcall2 function calls the latest version of a dynamic module using a library name and function name as a key. This dynamic module must have a long funcname(void *args) signature. Other than the use of a library name and function name as a key, this function is identical to a tdlcall() function.
A dynamic module function must have a long funcname(void *args) signature. This function is available only when the version of a TDL configuration file (tdl.cfg) is set to 3.
Prototype
#include <tdlcall.h> int tdlcall2(char *libname, char *funcname, void *args, long *urcode, int flags)
Parameter
| Parameter | Description |
|---|---|
| libname | The library name of a dynamic module. (Maximum size : TDL_FUNCNAME_SIZE – 1) |
| funcname | The function name of a dynamic module. (Maximum size : TDL_FUNCNAME_SIZE – 1) |
| args | An argument to a calling dynamic module function. |
| urcode | A return value from a dynamic module function. |
| flags | If set to TDLTRAN, a global sequence number must be passed using a urcode. If unspecified, TDL_NOFLAGS is set. |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| TDL_OPEN_ERROR | An error was returned with dlopen(). |
| TDL_SYM_ERROR | An error was returned with dlsym(). |
| TDL_CLOSE_ERROR | An error was returned with dlclose(). |
| TDL_SYSTEM_ERROR | An error with another system function calls. |
| TDL_INT _ERROR | An error with an internal library. |
| TDL_ENOFUNC | Cannot find a target module or function. |
| TDL_ENV_ERROR | An error with an environment variable configuration. |
| TDL_VER_ERROR | A version mismatch between the versions of a TDL shared memory and a configuration file (tdl.cfg). |
| TDL_ARG _ERROR | An error in an argument. |
| TDL_ENOLIB | Cannot find a target library. |
| TDL_TRAN_ERROR | An error while checking version consistency. |
| TDL_EINACTIVE | A module is temporarily inactive. |
The tdcall2v function calls the latest version of a dynamic module using a library name and a function name as a key. This dynamic module must have a long funcname(int argc, char *argv[]) signature.
Other than the use of a library name and a function name as a key, this function is identical to a tdlcall() function and is available only when the version of a TDL configuration file (tdl.cfg) is set to 3.
Prototype
#include <tdlcall.h>
int tdlcall2v(char *libname, char *funcname, int argc, char *argv[],
long *urcode, int flags)
Parameter
| Parameter | Description |
|---|---|
| libname | The library name of a dynamic module. (Maximum Length : TDL_FUNCNAME_SIZE – 1) |
| funcname | The function name of a dynamic module.(Maximum Length : TDL_FUNCNAME_SIZE – 1) |
| argc | The number of arguments for a dynamic module function. |
| argv | An argument vector for a dynamic module function.. |
| urcode | A return value from a dynamic module function. |
| flags | If set to TDLTRAN, a global sequence number must be passed using a urcode. If unspecified, a TDL_NOFLAGS is set. |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| TDL_OPEN_ERROR | An error was returned with dlopen(). |
| TDL_SYM_ERROR | An error was returned with dlsym(). |
| TDL_CLOSE_ERROR | An error was returned with dlclose(). |
| TDL_SYSTEM_ERROR | An error with another system function calls. |
| TDL_INT _ERROR | An error with an internal library. |
| TDL_ENOFUNC | Cannot find a target module or function. |
| TDL_ENV_ERROR | An error with an environment variable configuration. |
| TDL_VER_ERROR | A version mismatch between the versions of a TDL shared memory and a configuration file (tdl.cfg). |
| TDL_ARG _ERROR | An error in an argument. |
| TDL_ENOLIB | Cannot find a target library. |
| TDL_TRAN_ERROR | An error while checking version consistency. |
| TDL_EINACTIVE | A module is temporarily inactive. |
The tdcall2s function calls the latest version of a dynamic module using a library name and a function name as a key. This dynamic module must have a long funcname(void *input, void *output) signature.
Other than the use of a library name and a function name as a key, this function is identical to a tdlcall() function. This function is available only when the version of a TDL configuration file (tdl.cfg) is set to 3.
Prototype
#include <tdlcall.h>
int tdlcall2s(char *libname, char *funcname, void *input, void *output,
long *urcode, int flags)
Parameter
| Parameter | Description |
|---|---|
| libname | The library name of a dynamic module. (Maximum length: TDL_FUNCNAME_SIZE – 1). |
| funcname | The function name of a dynamic module. (Maximum length: TDL_FUNCNAME_SIZE – 1). |
| input | An input buffer pointer to a calling dynamic module function. |
| output | An output buffer pointer to a calling dynamic module function. |
| urcode | The return value from a dynamic module function. |
| flags | If set to TDLTRAN, a global sequence number must be passed using a urcode. If unspecified, a TDL_NOFLAGS is set. |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| TDL_OPEN_ERROR | An error was returned with dlopen(). |
| TDL_SYM_ERROR | An error was returned with dlsym(). |
| TDL_CLOSE_ERROR | An error was returned with dlclose(). |
| TDL_SYSTEM_ERROR | An error with another system function calls. |
| TDL_INT _ERROR | An error with an internal library. |
| TDL_ENOFUNC | Cannot find a target module or function. |
| TDL_ENV_ERROR | An error with an environment variable configuration. |
| TDL_VER_ERROR | A version mismatch between the versions of a TDL shared memory and a configuration file (tdl.cfg). |
| TDL_ARG _ERROR | An error in an argument. |
| TDL_ENOLIB | Cannot find a target library. |
| TDL_TRAN_ERROR | An error while checking version consistency. |
| TDL_EINACTIVE | A module is temporarily inactive. |
The tdlcallva function calls the latest version of a dynamic module using a function name as a key. A parameter is sent as-is for a dynamic function module that has an unfixed prototype. Delivered arguments must all have a <void *> pointer type. In a dynamical module function, all delivered parameters must be created as <void *> pointer types.
This function can be used when VERSION=1 or VERSION=2 is specified in a TDL configuration file(tdl.cfg).
Prototype
#include <tdlcall.h>
int tdlcallva(char *funcname, long urcode, int flags, int rettype, void *retval,
int argc, …);
Parameter
| Parameter | Description |
|---|---|
| funcname | The library name of a dynamic module. (Maximum Length : TDL_FUNCNAME_SIZE – 1) |
| urcode | Unlike the other tdlcall() functions, a urcode is used only when sending a global sequence number. |
| flags | If set to a TDLTRAN, a global sequence number must be passed using a urcode. If unspecified, a TDL_NOFLAGS will be set. |
| rettype | The return type of a dynamic module function to be called. Available values for this parameter are explained in the table below. |
| retval | A pointer to a buffer to store return values of a dynamic module function. |
| argc | The number of arguments for a dynamic module function. Currently, the maximum available number of arguments is 10. |
| ... | Enters parameters to be sent to a dynamic module function as a variable argument. A pointer (void*) type of parameters must be sent. |
Values for return type
| Parameter | Description |
|---|---|
| TDL_VA_CHAR | The returned type of a dynamic module function is a char type. |
| TDL_VA_SHORT | The returned type of a dynamic module function is a short type. |
| TDL_VA_INT | The returned type of a dynamic module function is an integer type. |
| TDL_VA_LONG | The returned type of a dynamic module function is a long type. |
| TDL_VA_FLOAT | The returned type of a dynamic module function is a short type. |
| TDL_VA_DOUBLE | The returned type of a dynamic module function is a short type. |
| TDL_VA_PVOID | The returned type of a dynamic module function is a void * type. |
| TDL_VA_VOID | The returned type of a dynamic module function is a void type. |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| TDL_OPEN_ERROR | An error was returned with dlopen(). |
| TDL_SYM_ERROR | An error was returned with dlsym(). |
| TDL_CLOSE_ERROR | An error was returned with dlclose(). |
| TDL_SYSTEM_ERROR | An error with another system function calls. |
| TDL_INT _ERROR | An error with an internal library. |
| TDL_ENOFUNC | Cannot find a target module or function. |
| TDL_ENV_ERROR | An error with an environment variable configuration. |
| TDL_VER_ERROR | A version mismatch between the versions of a TDL shared memory and a configuration file (tdl.cfg). |
| TDL_ARG _ERROR | An error in argument. |
| TDL_ENOLIB | Cannot find a target library. |
| TDL_TRAN_ERROR | An error while checking version consistency. |
| TDL_EINACTIVE | A module is temporarily inactive. |
Example
Dynamic module call
int myfunc(double *a, double *b, double *c) {
double sum;
return (int)(((double)(*a) + (double)(*b) + (double)(*c))/3);
}
char * myfunc2(int *type) {
char *msg;
switch (*type) {
case 1: msg = “foo”; break;
case 2: msg = “bar”;break;
}
return msg;
}
Program to be called
#include <tdlcall.h>
int main(int argc, char *argv[]) {
int n;
long urcode;
int retval;
double a, b, c;
int type;
char *retmsg;
urcode = tdlgetseqno();
a = 2.5;
b = 3.0;
c = 3.5;
if ((n = tdlcallva2(“mylib001”, “myfunc”, urcode, TDLTRAN,
TDL_VA_INT, &retval, 3, &a, &b, &c)) != TDL_OK) {
error processing;
}
type = 1;
if ((n = tdlcallva2(“mylib001”, “myfunc2”, urcode, TDLTRAN,
TDL_VA_PVOID, &retmsg, 1, &type)) != TDL_OK) {
error processing;
}
}
The tdlcallva2 function calls the latest version of a dynamic module using a library and function name as a key. A parameter is sent as-is for a dynamic function module that has an unfixed prototype. Delivered arguments must all have a <void *> pointer type. In a dynamical module function, all delivered parameters must be created as <void *> pointer types.
Other than the use of a library and function name as a key, this function is identical to a tdlcalva() function. It is available when VERSION=3 is specified in a TDL configuration file (tdl.cfg).
Prototype
#include <tdlcall.h> int tdlcallva2(char *libname, char *funcname, long urcode, int flags, int rettype, void *retval, int argc, …);
Parameter
| Parameter | Description |
|---|---|
| libname | The library name of a dynamic module. (Maximum Length : TDL_FUNCNAME_SIZE – 1) |
| funcname | The function name of a dynamic module.(Maximum Length : TDL_FUNCNAME_SIZE – 1) |
| urcode | Unlike other tdlcall() functions, it is used only when sending a global sequence number. When not using a global sequence number, set this parameter to 0. |
| flags | If set to TDLTRAN, a global sequence number must be passed using a urcode. If unspecified, a TDL_NOFLAGS will be set. |
| rettype | The return type of a dynamic module function to be called. Available values for this parameter are explained in the table below. |
| retval | A pointer to a buffer to store the return value of a dynamic module function. |
| argc | The number of arguments for a dynamic module function. Currently, the maximum available number of arguments is 10. |
| ... | Enters parameters to be sent to a dynamic module function as a variable argument. A pointer (void*) type of parameters must be sent. |
Return Type
| Item | Description |
|---|---|
| TDL_VA_CHAR | The returned type of a dynamic module function is a char type. |
| TDL_VA_SHORT | The returned type of a dynamic module function is a short type. |
| TDL_VA_INT | The returned type of a dynamic module function is an int type. |
| TDL_VA_LONG | The returned type of a dynamic module function is a long type. |
| TDL_VA_FLOAT | The returned type of a dynamic module function is a short type. |
| TDL_VA_DOUBLE | The returned type of a dynamic module function is a short type. |
| TDL_VA_PVOID | The returned type of a dynamic module function is a void * type. |
| TDL_VA_VOID | The returned type of a dynamic module function is a void type. |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| TDL_OPEN_ERROR | An error was returned with dlopen(). |
| TDL_SYM_ERROR | An error was returned with dlsym(). |
| TDL_CLOSE_ERROR | An error was returned with dlclose(). |
| TDL_SYSTEM_ERROR | An error with another system function calls. |
| TDL_INT _ERROR | An error with an internal library. |
| TDL_ENOFUNC | Cannot find a target module or function. |
| TDL_ENV_ERROR | An error with an environment variable configuration. |
| TDL_VER_ERROR | A version mismatch between the versions of a TDL shared memory and a configuration file (tdl.cfg). |
| TDL_ARG _ERROR | An error in an argument. |
| TDL_ENOLIB | Cannot find a target library. |
| TDL_TRAN_ERROR | An error while checking version consistency. |
| TDL_EINACTIVE | A module is temporarily inactive. |
The tdlcreate function creates a class instance using a Class Factory in the latest version of a dynamic module. It uses a library name, a namespace, and a class name as keys. It can be used when a VERSION is set to 4 in a tdl.cfg TDL configuration file.
To use a Class Factory in a dynamic module, a user must implement a callback function in a long tdlcreate_cb(char *namespace, char *classname, void *args, void *object) format. A callback function creates an actual class instance using arguments which are passed from a tdlcreate() and sends a reference of an instance to an object.
A user must destroy an instance using a tdldestroy() if the instance is no longer used. Although the version of a dynamic module is changed by using a tdlupdate(), an instance that is created using a tdlcreate() will operate for an old version of a dynamic module before being destroyed using a tdldestroy(). To use an instance for a new dynamic module, call a tdldestroy() and then call a tdlcreate().
To use a Class Factory, the following tdlcreate_cb() callback function needs to be implemented in a dynamic module:
Prototype
#include <tdlcall.h> int tdlcreate(char *libname, char *namespace, char *classname, void *args, void *object, long *urcode, int flags)
Parameter
| Parameter | Description |
|---|---|
| libname | A dynamic module library name. (Maximum length: TDL_FUNCNAME_SIZE – 1) |
| namespace | A namespace. (Maximum length: TDL_FUNCNAME_SIZE – 1) |
| classname | The name of a class where an instance is created. (Maximum length: TDL_FUNCNAME_SIZE – 1) |
| args | Passes user-defined data to a tdlcreate_cb() callback function. |
| object | Pointer to a variable for saving the reference of a class instance which is created through a tdlcreate_cb() callback function. |
| urcode | A return value of a tdlcreate_cb() callback function. |
| flags | If set to TDLTRAN, a global sequence number must be passed using a urcode. If unspecified, a TDL_NOFLAGS is set. |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| TDL_OPEN_ERROR | An error was returned with dlopen(). |
| TDL_SYM_ERROR | An error was returned with dlsym(). |
| TDL_CLOSE_ERROR | An error was returned with dlclose(). |
| TDL_SYSTEM_ERROR | An error with another system function calls. |
| TDL_INT _ERROR | An error with an internal library. |
| TDL_ENOFUNC | Cannot find a target module or function. |
| TDL_ENV_ERROR | An error with an environment variable configuration. |
| TDL_VER_ERROR | A version mismatch between the versions of a TDL shared memory and a configuration file (tdl.cfg). |
| TDL_ARG _ERROR | An error in an argument. |
| TDL_ENOLIB | Cannot find a target library. |
| TDL_TRAN_ERROR | An error while checking version consistency. |
| TDL_EINACTIVE | A module is temporarily inactive. |
Callback Function Prototype
long tdlcreate_cb(char *namespace, char *classname, void *args, void *object)
Parameter
| Parameter | Description |
|---|---|
| namespace | A namespace received from a tdlcreate(). |
| classname | A name of a class where an instance received from a tdlcreate() is created. |
| args | User-defined data. |
| object | A pointer to a variable for saving a reference of a class instance that is created through a callback function. |
The tdldestroy function destroys a class instance using a Class Factory in the latest version of a dynamic module. It uses a library name, a namespace, and a class name as keys. It can be used when a VERSION is set to 4 in a tdl.cfg TDL configuration file.
To use a Class Factory in a dynamic module, a user must implement a callback function in a long tdldestroy_cb(char *namespace, char *classname, void *args, void *object) format. The callback function destroys an actual class instance using arguments which are passed from a tdldestroy().
A user must destroy an instance using a tdldestroy() if the instance is no longer used. Although the version of a dynamic module is changed through a tdlupdate(), an instance which is created using a tdlcreate() operates for the old version of a dynamic module before being destroyed using a tdldestroy(). To use an instance for the new dynamic module, call a tdldestroy() and then call a tdlcreate().
Prototype
#include <tdlcall.h> int tdldestroy(char *libname, char *namespcae, char *classname, void *args, void *object, long *urcode, int flags)
Parameter
| Parameter | Description |
|---|---|
| libname | A dynamic module library name. (Maximum length: TDL_FUNCNAME_SIZE – 1) |
| namespace | A nmespace. (Maximum length: TDL_FUNCNAME_SIZE – 1) |
| classname | The name of a class where an instance is created. (Maximum length: TDL_FUNCNAME_SIZE – 1) |
| args | Passes user-defined data to a tdlcreate_cb() callback function. |
| object | Passes a reference of a class instance to be destroyed by a tdldestroy_cb() callback function. This must be an object that is created using a tdlcreate(). |
| urcode | A return value of a tdlcreate_cb() callback function. |
| flags | If set to TDLTRAN, a global sequence number must be passed using a urcode. If unspecified, a TDL_NOFLAGS is set. |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| TDL_OPEN_ERROR | An error was returned with dlopen(). |
| TDL_SYM_ERROR | An error was returned with dlsym(). |
| TDL_CLOSE_ERROR | An error was returned with dlclose(). |
| TDL_SYSTEM_ERROR | An error with another system function calls. |
| TDL_INT _ERROR | An error with an internal library. |
| TDL_ENOFUNC | Cannot find a target module or function. |
| TDL_ENV_ERROR | An error with an environment variable configuration. |
| TDL_VER_ERROR | A version mismatch between the versions of a TDL shared memory and a configuration file (tdl.cfg). |
| TDL_ARG _ERROR | An error in an argument. |
| TDL_ENOLIB | Cannot find a target library. |
| TDL_TRAN_ERROR | An error while checking version consistency. |
| TDL_EINACTIVE | A module is temporarily inactive. |
To use a Class Factory, the following tdldestroy_cb() callback function must be implemented in a dynamic module.
Callback Function Prototype
long tdldestroy_cb(char *namespace, char *classname, void *args, void *object)
Parameter
| Parameter | Description |
|---|---|
| namespace | A namespace received from a tdldestroy(). |
| classname | The name of a class where an instance received from a tdldestroy() will be destroyed. |
| args | User-defined data. |
| object | The reference of a class instance to be destroyed through a callback function. |
The tdlerror function converts a tdlcall function error to a character string. If an error occurred in a previous tdlcall() function call, detailed information will be obtained about the error in a string format. A pointer returned from this function is a pointer to a static variable that may change on a following call to a tdlcall().
To maintain content of this variable, the content should be copied to another variable.
Prototype
#include <tdlcall.h> char* tdlerror(int retval)
Parameter
| Parameter | Description |
|---|---|
| retval | A return value from a previous tdlcall() function call. |
Return Value
| Value | Description |
|---|---|
| dlopen fail | Returned when receiving a TDL_OPEN_ERROR as a return value of a tdlcall(). |
| dlsym fail | Returned when receiving a TDL_SYM_ERROR as a return value of a tdlcall(). |
| dlclose fail | Returned when receiving a TDL_CLOSE_ERROR as a return value of a tdlcall(). |
| etc system call error | Returned when receiving a TDL_SYSTEM_ERROR as a return value of a tdlcall(). |
| TDL lib internal error | Returned when receiving a TDL_SYSTEM_ERROR as a return value of a tdlcall(). |
| funcname not found | Returned when receiving a TDL_ENOFUNC as a return value of a tdlcall(). |
| environment not found | Returned when receiving a TDL_ENV_ERROR as a return value of a tdlcall(). |
| shared version mismatch | Returned when receiving a TDL_VER_ERROR as a return value of a tdlcall(). |
| invalid arguments | Returned when receiving a TDL_ARG_ERROR as a return value of a tdlcall(). |
| library not found | Returned when receiving a TDL_ENOLIB as a return value of a tdlcall(). |
| transaction error | Returned when receiving a TDL_TRAN_ERROR as a return value of a tdlcall(). |
| inactive function | Returned when receiving a TDL_EINACTIVE as a return value of a tdlcall(). |
The tdlgetseqno function gets a global sequence number and returns it as a return value.
Prototype
#include <tdlcall.h> unsigned int tdlgetseqno(void)
Return Value
| Value | Description |
|---|---|
| 0 or greater value | A function call was successful. |
| 0 | A function call failed. Detailed error information can be checked by using a "3.10. tdlerror". |
The tdlstart function starts maintaining Explicit Version Consistency.
Prototype
#include <tdlcall.h> int tdlstart(void)
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| TDL_TRAN _ERROR | A tdlstart() was been carried out before calling a tdlstart(). See "3.2. tdlcall" for detailed information. |
The tdlend function stops maintaining Explicit Version Consistency.
Prototype
#include <tdlcall.h> int tdlend(void)
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| TDL_TRAN _ERROR | A tdlstart() has been carried out before calling a tdlstart(). See "3.2. tdlcall" for detailed information. |
The tdlsuspend function temporarily suspends maintaining explicit version consistency and a SD (suspend descriptor) is returned. There may be a maximum of 8 simultaneous SDs.
Prototype
#include <tdlcall.h> int tdlsuspend(void)
Return Value
| Value | Description |
|---|---|
| 0 or greater value | A function call was successful. |
| TDL_TRAN _ERROR | Not in Explicit Version Consistency mode. See "3.2. tdlcall" for detailed information. |
The tdlresume function resumes a temporarily suspended Explicit Version Consistency.
Prototype
#include <tdlcall.h> int tdlresume(int sd)
Prototype
| Parameter | Description |
|---|---|
| sd | A descriptor from a tdlsuspend(). |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| TDL_TRAN _ERROR | A sd is not a valid value. See "3.2. tdlcall" for detailed information. |
The tdlclose function initializes a reference count of a module to 0 or releases a module from memory.
Prototype
#include <tdlcall.h> int tdlclose(char *name, int flags)
Parameter
| Parameter | Description |
|---|---|
| name | A module name. |
| flags | If set to 0, the reference count of a module is set to 0 and the module will not be released from memory. If set to TDLCLOSE_HARD, the module will be released from memory by a dlclose(). |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| TDL_ENOLIB | A module does not exist. |
When a module is called first through a tdlcall(), a certain period of time is consumed because it needs to search for a hashtable in shared memory as well as load libraries to memory. To prevent a delay, a tdlload function can perform a search for a hashtable and load libraries before calling a tdlcall(). It can also save module information in a local cache.
If VERSION=1 or VERSION=2 is set in TDL configuration file(tdl.cfg), tdlload() will be used. If VERSION=3 is set, tdlload2() will be used and if VERSION=4 is set, tdlload3() will be used.
Prototype
#include <tdlcall.h> int tdlload(char *funcname, int flags)
Parameter
| Parameter | Description |
|---|---|
| funcname | The name of a function to be loaded. |
| flags | Not current supported. |
Return Value
| Value | Description |
|---|---|
| 0 | A function call was successful. |
| TDL_ENOFUNC | An argument is NULL or does not exist in a hashtable. |
| TDL_OPEN_ERROR | Failed to load a dynamic library in a hashtable to memory. |
| TDL_SYSTEM_ERROR | Failed to allocate system resources for creating a local cache. |
The tdlload2 function is the same as a tdlload. For more information, refer to "3.17. tdlload".
Prototype
#include <tdlcall.h> int tdlload2(char *libname, char *funcname, int flags)
Parameter
| Parameter | Description |
|---|---|
| libname | The name of a library to be loaded. |
| funcname | The name of a function to be loaded. |
| flags | Currently not used. |
Return Value
Since return values of a tdlload2() are the same as those of a tdlload(), refer to "3.17. tdlload".
The tdlinit function initially sets shared memory.
Prototype
#include <tdlcall.h> int tdlinit(int flags)
Parameter
| Parameter | Description |
|---|---|
| flags | Currently not used. |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| Value less than 0 | A function call failed. Detailed error information can be checked by using a "3.10. tdlerror". |
The tdldone function initializes shared memory.
Prototype
#include <tdlcall.h> int tdldone(int flags)
Parameter
| Parameter | Description |
|---|---|
| flags | Currently not used. |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| Value less than 0 | A function call failed. Detailed error information can be checked by using a "3.10. tdlerror". |
The tdlfind function searches for a module index. It is used when a VERSION is set to 1 or 2 in a tdl.cfg TDL configuration file.
Prototype
#include <tdlcall.h> int tdlfind(char *funcname, int flags)
Parameter
| Parameter | Description |
|---|---|
| funcname | The name of a function to be found. |
| flags | Currently not used. |
Return Value
| Value | Description |
|---|---|
| 0 or greater value | A function call was successful. |
| Value less than 0 | A function call failed. Detailed error information can be checked by using a "3.10. tdlerror". |
The tdlfind function searches for a module index. It is used when a VERSION is set to 3 in a tdl.cfg TDL configuration file.
Prototype
#include <tdlcall.h> int tdlfind2(char *libname, char *funcname, int flags)
Parameter
| Parameter | Description |
|---|---|
| libname | The name of a library to be found. |
| funcname | The name of a function to be found. |
| flags | Currently not used. |
Return Value
| Value | Description |
|---|---|
| 0 or greater value | A function call was successful. |
| Value less than 0 | A function call failed. Detailed error information can be checked by using a "3.10. tdlerror". |
The tdlstat function displays TDL statistics. It is used when a VERSION is set to 1 or 2 in a tdl.cfg TDL configuration file. It is required to set a MONITOR to Y in a configuration file.
Prototype
#include <tdlcall.h> int tdlstat(char *funcname, struct timeval svc_time, struct timeval cpu_time)
Parameter
| Parameter | Description |
|---|---|
| funcname | The name of a function for which statistics are collected. |
| svc_time | A variable where service time among statistics is saved. |
| cpu_time | A variable where CPU time among statistics is saved. |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| Value less than 0 | A function call failed. Detailed error information can be checked by using a "3.10. tdlerror". |
The tdlstat2 function displays TDL statistics. It is used when a VERSION is set to 3 in a tdl.cfg TDL configuration file. It is required to set a MONITOR to Y in a configuration file.
Prototype
#include <tdlcall.h> int tdlstat2(char *libname, char *funcname, struct timeval svc_time, struct timeval cpu_usrtime, struct timeval cpu_systime)
Parameter
| Parameter | Description |
|---|---|
| libname | The name of a library for which statistics are collected. |
| funcname | The name of a function for which statistics are collected. |
| svc_time | A variable where service time among statistics is saved. |
| cpu_usrtime | A variable where user CPU time among statistics is saved. |
| cpu_systime | A variable where system CPU time among statistics is saved. |
Return Value
| Value | Description |
|---|---|
| TDL_OK | A function call was successful. |
| Value less than 0 | A function call failed. Detailed error information can be checked by using a "3.10. tdlerror". |