API

This chapter describes how to use APIs to develop applications.

1. Overview

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.

tdlcall2

Calls the latest version of a dynamic module function.

tdlcall2s

Calls the latest version of a dynamic module function.

tdlcall2v

Calls the latest version of a dynamic module function.

tdlcallva

Calls the latest version of a dynamic module function.

tdlcallva2

Calls the latest version of a dynamic module function.

tdlclose

Resets the reference count of the module to 0, or directly unloads the module from memory.

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

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).

tdldone

Initializes shared memory.

tdlend

Terminates maintaining explicit version consistency maintenance.

tdlerror

When an error for tdlcall() occurs, convert it into a string form.

tdlfind

Retrieves the index of the module.

tdlfind2

Retrieves the index of the module.

tdlgetseqno

retrieves and returns the global sequence number.

tdlinit

Initializes shared memory.

tdlload

Performs hashtable lookup and library loading in advance, storing the corresponding module information in the local cache before tdlcall().

tdlload2

Performs hashtable lookup and library loading in advance, storing the corresponding module information in the local cache before tdlcall().

tdlresume

Resumes temporarily suspended version consistency maintenance.

tdlstart

Starts keeping the explicit version consistency.

tdlstat

Displays TDL statistics information.

tdlstat2

Displays TDL statistics information.

tdlsuspend

Suspends keeping the version consistency.

2. tdlcall

The tdlcall function invokes the latest version of a dynamic module function. This dynamic module function must use the signature of long funcname(void *args). tdlcall works only when the TDL configuration file (tdl.cfg) version is set to 1 or 2. Dynamic modules are loaded when tdlcall() is executed. To avoid performance degradation, they are reused unless an update is triggered with tdlupdate.

  • Prototype

    #include <tdlcall.h>
int tdlcall(char *funcname, void *args, long *urcode, int flags)

  • Parameter

    Parameter Description

    funcname

    The function name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    args

    A parameter for the dynamic module function to call.

    urcode

    The return value from the dynamic module function.

    flags

    The following flags are available:

    • TDLTRAN : With this flag setting, the global sequence number must be returned through urcode.

    • TDL_RTLD_GLOBAL : Enables the RTLD_GLOBAL option, which allows access to externally defined variables or functions. With this option, other modules can also reference external symbols.

    • TDL_NOFLAGS : No flags are applied.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

3. tdlcall2

The tdlcall2 function calls the latest version of a dynamic module using the library name and function name as keys. The dynamic module must have the signature of long funcname(void *args). Except for using the library and function names as keys, tdlcall2() behaves the same as tdlcall().

tdlcall2() is available only when the version of the 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 the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    funcname

    The function name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    args

    A parameter for the dynamic module function to call.

    urcode

    The return value from the dynamic module function.

    flags

    The following flags are available:

    • TDLTRAN : When this flag is set, the global sequence number must be returned through urcode.

    • TDL_RTLD_GLOBAL : Enables the RTLD_GLOBAL option, which allows access to externally defined variables or functions. With this option, other modules can also reference external symbols.

    • TDL_NOFLAGS : No flags are applied.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

4. tdlcall2s

The tdlcall2 function calls the latest version of a dynamic module using the library name and function name as keys. The dynamic module must have the signature of long funcname(void *input, void *output). Except for using the library and function names as keys, tdlcall2s() behaves the same as tdlcall().

tdlcall2s() is available only when the version of the 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 the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    funcname

    The function name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    input

    Pointer to the input buffer of the calling dynamic module function.

    output

    Pointer to the output buffer of the calling dynamic module function.

    urcode

    The return value from the dynamic module function.

    flags

    The following flags are available:

    • TDLTRAN : When this flag is set, the global sequence number must be returned through urcode.

    • TDL_RTLD_GLOBAL : Enables the RTLD_GLOBAL option, which allows access to externally defined variables or functions. With this option, other modules can also reference external symbols.

    • TDL_NOFLAGS : No flags are applied.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

5. tdlcall2v

The tdlcall2v function invokes the latest version of a dynamic module, using the library name and function name as keys. The dynamic module function must have the signature of long funcname(int argc, char *argv[]). Except for using the library and function names as keys, tdlcall2v() behaves the same as tdlcall().

tdlcall2v() is available only when the version of the 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 the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    funcname

    The function name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    argc

    The number of parameters of the dynamic module function.

    argv

    The parameter vector of the dynamic module function.

    urcode

    The return value from the dynamic module function.

    flags

    The following flags are available:

    • TDLTRAN : When this flag is set, the global sequence number must be returned through urcode.

    • TDL_RTLD_GLOBAL : Enables the RTLD_GLOBAL option, which allows access to externally defined variables or functions. With this option, other modules can also reference external symbols.

    • TDL_NOFLAGS : No flags are applied.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

6. tdlcallva

The tdlcallva function invokes the latest version of a dynamic module, using the function name as the key. For dynamic module functions with non-fixed prototypes, parameters are passed as-is. All arguments must be of type void *, and in the dynamic module function, all received parameters must also be declared as void *.

tdlcallva() is available only when the version of the TDL configuration file (tdl.cfg) is set to 1 or 2.

  • Prototype

    #include <tdlcall.h>
int tdlcallva(char *funcname, long urcode, int flags, int rettype, void *retval,
              int argc, …);

  • Parameter

    Parameter Description

    funcname

    The name of the dynamic module function (Maximum size: TDL_FUNCNAME_SIZE – 1).

    urcode

    Unlike other tdlcall() fmaily functions, this parameter is used only to pass the global sequence number. When not used, set to 0.

    flags

    The following flags are available:

    • TDLTRAN : When this flag is set, the global sequence number must be returned through urcode.

    • TDL_RTLD_GLOBAL : Enables the RTLD_GLOBAL option, which allows access to externally defined variables or functions. With this option, other modules can also reference external symbols.

    • TDL_NOFLAGS : No flags are applied.

    rettype

    The return type of the dynamic module function to call.

    The following settings are available.

    • TDL_VA_CHAR : char type.

    • TDL_VA_SHORT : short type.

    • TDL_VA_INT : int type.

    • TDL_VA_LONG : long type.

    • TDL_VA_FLOAT : float type.

    • TDL_VA_DOUBLE : double type.

    • TDL_VA_PVOID : void * type.

    • TDL_VA_VOID : void type.

    retval

    A pointer to the buffer storing the return value of the dynamic module function called.

    argc

    The number of arguments to be passed with the dynamic module function. Currently up to 10 arguments are supported.

    …​

    Parameters to be passed with the dynamic module function as variable arguments. Must be of the (void *) pointer type.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The 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;
    }
}

7. tdlcallva2

The tdlcallva2 function invokes the latest version of a dynamic module, using the library name and function name as keys. For dynamic module functions with non-fixed prototypes, parameters are passed as-is. All arguments must be of type void *, and in the dynamic module function, all received parameters must also be declared as void *. Except for using the library and function names as keys, tdlcallva2() behaves the same as tdlcallva().

tdlcallva2() is available only when the version of the TDL configuration file (tdl.cfg) is set to 3.

  • 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 the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    funcname

    The function name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    urcode

    Unlike other tdlcall() fmaily functions, this parameter is used only to pass the global sequence number. When not used, set to 0.

    flags

    The following flags are available:

    • TDLTRAN : When this flag is set, the global sequence number must be returned through urcode.

    • TDL_RTLD_GLOBAL : Enables the RTLD_GLOBAL option, which allows access to externally defined variables or functions. With this option, other modules can also reference external symbols.

    • TDL_NOFLAGS : No flags are applied.

    rettype

    The return type of the dynamic module function to call.

    The following settings are available.

    • TDL_VA_CHAR : char type.

    • TDL_VA_SHORT : short type.

    • TDL_VA_INT : int type.

    • TDL_VA_LONG : long type.

    • TDL_VA_FLOAT : float type.

    • TDL_VA_DOUBLE : double type.

    • TDL_VA_PVOID : void * type.

    • TDL_VA_VOID : void type.

    retval

    A pointer to the buffer storing the return value of the dynamic module function called.

    argc

    The number of arguments to be passed with the dynamic module function. Currently up to 127 arguments are supported.

    …​

    Parameters to be passed with the dynamic module function as variable arguments. Must be of the (void *) pointer type.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

8. tdlclose

The tdlclose function either resets a module’s reference count to 0 or unloads the module from memory.

  • Prototype

    #include <tdlcall.h>
int tdlclose(char *name, int flags)

  • Parameter

    Parameter Description

    name

    The module name.

    flags

    If set to 0, the module’s reference count is set to 0 and the module will not be unloaded from memory. If set to TDLCLOSE_HARD, the module will be unloaded from memory through dlclose().

  • Return Value

    Value Description

    TDL_OK

    The function call succeeded.

    TDL_ENOLIB

    No module with the specified name exists.

9. tdlcreate

The tdlcreate function creates a class instance using a class factory in the latest version of a dynamic module. The instance is created using the library name, namespace, and class name as keys.

tdlcreate() is available only when the TDL configuration file (tdl.cfg) version is set to 4.

An instance created with this function must be destroyed with tdldestroy(). Between tdlcreate() and tdldestroy(), if tdlupdate() is invoked, the current instance continues to operate on the previous version even if the dynamic module has been updated. After destroying the instance with tdldestroy(), invoking tdlcreate() again creates a new instance from the updated 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

    The library name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    namespace

    The namespace. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    classname

    The name of the class to create an instance.

    (Maximum size: TDL_FUNCNAME_SIZE – 1)

    args

    User-defined data to be passed to the tdlcreate_cb() callback function.

    object

    Pointer to a variable that stores the reference to the class instance created by tdlcreate_cb(). After the function returns, the user must cast the object parameter to the appropriate type before using it.

    urcode

    The return value from the tdlcreate_cb() callback function.

    flags

    Set to TDLTRAN. When this flag is set, the global sequence number must be returned through urcode. When using no flag, set to TDL_NOFLAGS.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

To use a class factory in a dynamic module, the user must implement a callback function with the following signature: long tdlcreate_cb(char *namespace, char *classname, void *args, void *object). This callback creates the actual class instance using the parameters passed through tdlcreate(). The user implementation must pass the reference to the created instance through the object parameter.

When using a class factory, the dynamic module must implement both the tdlcreate_cb() and tdldestroy_cb() callback functions.

  • Prototype

    long tdlcreate_cb(char *namespace, char *classname, void *args, void *object)

  • Parameter

    Parameter Description

    namespace

    The namespace passed by tdlcreate().

    classname

    The name of the class to create the instance passed by tdlcreate().

    args

    User-defined data.

    object

    Pointer to a variable that stores the reference to the class instance created by the callback function.

10. tdldestroy

The tdldestroy function destroys a class instance created using a class factory in the latest version of a dynamic module. The library name, namespace, and class name are used as keys.

tdldestroy() is available only when the TDL configuration file (tdl.cfg) version is set to 4.

An instance created with tdlcreate() must be destroyed with this function. Between tdlcreate() and tdldestroy(), if tdlupdate() is invoked, the current instance continues to operate on the previous version even if the dynamic module has been updated. After destroying the instance with tdldestroy(), invoking tdlcreate() again creates a new instance from the updated dynamic module.

  • Prototype

    #include <tdlcall.h>
int tdldestroy(char *libname, char *namespcae, char *classname, void *args,
               void *object, long *urcode, int flags)

  • Parameter

    Parameter Description

    libname

    The library name of the dynamic module. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    namespace

    The namespace. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    classname

    The name of the class whose instance will be destroyed. (Maximum size: TDL_FUNCNAME_SIZE – 1)

    args

    User-defined data to be passed to the tdldestroy_cb() callback function.

    object

    The reference to the class instance to be destroyed by tdldestroy_cb(). The object must be the one created using tdlcreate().

    urcode

    The return value from tdldestroy_cb().

    flags

    Set to TDLTRAN. When this flag is set, the global sequence number must be returned through urcode. When using no flag, set to TDL_NOFLAGS.

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_OPEN_ERROR

    An error occurred during a dlopen() call.

    TDL_SYM_ERROR

    An error occurred during a dlsym() call.

    TDL_CLOSE_ERROR

    An error occurred during a dlclose() call.

    TDL_SYSTEM_ERROR

    An error occurred during another system call.

    TDL_INT _ERROR

    An error occurred within the library.

    TDL_ENOFUNC

    The specified module or function was not found.

    TDL_ENV_ERROR

    An erroneous environment variable exists.

    TDL_VER_ERROR

    The version of the TDL shared memory does not match the configuration file (tdl.cfg)

    TDL_ARG _ERROR

    An invalid parameter was set.

    TDL_ENOLIB

    The specified library could not be found.

    TDL_TRAN_ERROR

    An error occurred while checking version consistency.

    TDL_EINACTIVE

    The module is temporarily inactive.

To use a class factory in a dynamic module, the user must implement a callback function with the following signature: long tdldestroy_cb(char *namespace, char *classname, void *args, void *object). This callback destroys the class instance using the parameters passed through tdldestroy(). The user implementation must pass the reference to the instance through the object parameter.

  • Prototype

    long tdldestroy_cb(char *namespace, char *classname, void *args, void *object)

  • Parameter

    namespace The namespace passed by tdlcreate().

    classname

    The name of the class to create the instance passed by tdlcreate().

    args

    User-defined data.

    object

    The reference to the class instance to be destroyed by the callback function.

11. tdldone

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

    The function call succeeded.

    Smaller than 0

    The function call failed. See tdlerror.

12. tdlend

The tdlend function terminates explicit version consistency maintenance.

  • Prototype

    #include <tdlcall.h>
int tdlend(void)

  • Return Value

    Value Description

    TDL_OK

    The function call succeeded.

    TDL_TRAN_ERROR

    tdlstart() was executed before the required function call. See tdlcall for more information.

13. tdlerror

The tdlerror function converts an error from tdlcall() into a text string. When an error occurs during execution of tdlcall(), tdlerror() returns detailed information about the error.

The return value is a pointer to an internal static variable. Because this memory may be overwritten during the next tdlcall() execution, the data must be copied to another variable if it needs to be preserved or modified.

  • Prototype

    #include <tdlcall.h>
char* tdlerror(int retval)

  • Parameter

    Parameter Description

    retval

    The return value of the previous tdlcall() execution.

  • Return Value

    Value Description

    dlopen fail

    tdlcall() returned TDL_OPEN_ERROR.

    dlsym fai

    tdlcall() returned TDL_SYM_ERROR.

    dlclose fail

    tdlcall() returned TDL_CLOSE_ERROR.

    etc system call error

    tdlcall() returned TDL_SYSTEM_ERROR.

    TDL lib internal error

    tdlcall() returned TDL_INT_ERROR.

    funcname not found

    tdlcall() returned TDL_ENOFUNC.

    environment not found

    tdlcall() returned TDL_ENV_ERROR.

    shared version mismatch

    tdlcall() returned TDL_VER_ERROR.

    invalid arguments

    tdlcall() returned TDL_ARG_ERROR.

    library not found

    tdlcall() returned TDL_ENOLIB.

    transaction error

    tdlcall() returned TDL_TRAN_ERROR.

    inactive funcation

    tdlcall() returned TDL_EINACTIVE.

14. tdlfind

The tdlfind function retrieves the index of a module. It is available when VERSION=1 or VERSION=2 is set in the TDL configuration file (tdl.cfg).

  • Prototype

    #include <tdlcall.h>
int tdlfind(char *funcname, int flags)

  • Parameter

    Parameter Description

    funcname

    The function name to retrieve.

    flags

    Currently not used.

  • Return Value

    Value Description

    Greater than or equal to 0

    The function call succeeded.

    Smaller than 0

    The function call failed. See tdlerror.

15. tdlfind2

The tdlfind2 function retrieves the index of a module. It is available when VERSION=3 is set in the TDL configuration file (tdl.cfg).

  • Prototype

    #include <tdlcall.h>
int tdlfind2(char *libname, char *funcname, int flags)

  • Parameter

    Parameter Description

    libname

    The library name to retrieve.

    funcname

    The function name to retrieve.

    flags

    Currently not used.

  • Return Value

    Value Description

    Greater than or equal to 0

    The function call succeeded.

    Smaller than 0

    The function call failed. See tdlerror.

16. tdlgetseqno

The tdlgetseqno function retrieves and returns a global sequence number.

  • Prototype

    #include <tdlcall.h>
unsigned int tdlgetseqno(void)

  • Return Value

    Value Description

    Greater than 0

    The function call succeeded.

    0

    The function call failed. See tdlerror.

17. tdlinit

The tdlinit function initializes shared memory.

  • Prototype

    #include <tdlcall.h>
int tdlinit(int flags)

  • Parameter

    Parameter Description

    flags

    Currently not used.

  • Return Value

    Value Description

    TDL_OK

    The function call succeeded.

    Smaller than 0

    The function call failed. See tdlerror.

18. tdlload

When a module is invoked for the first time through tdlcall(), initialization may be delayed due to hashtable lookup in shared memory and library loading. To avoid this overhead, the tdlload function performs the hashtable search and library loading in advance, storing the module information in the local cache.

tdlload() is available only when the TDL configuration file (tdl.cfg) version is set to 1 or 2. For version 3, use tdlload2(). For version 4, use tdlload3().

  • Prototype

    #include <tdlcall.h>
int tdlload(char *funcname, int flags)

  • Parameter

    Parameter Description

    funcname

    The name of the function to load.

    flags

    Currently not used.

  • Return Value

    Value Description

    0

    The function call succeeded.

    TDL_ENOFUNC

    The libname or funcname argument was NULL, or the passed value was not found in the hashtable.

    TDL_OPEN_ERROR

    The dynamic library listed in the hashtable could not be loaded into memory.

    TDL_SYSTEM_ERROR

    Allocation of system resources for creating a local cache failed.

19. tdlload2

The tdlload2 function is equivalent to tdlload.

  • Prototype

    #include <tdlcall.h>
int tdlload2(char *libname, char *funcname, int flags)

  • Parameter

    Parameter Description

    libname

    The name of the library to load.

    funcname

    The name of the function to load.

    flags

    Currently not used.

20. tdlresume

The tdlresume function resumes version consistency maintenance that was previously suspended.

  • Prototype

    #include <tdlcall.h>
int tdlresume(int sd)

  • Parameter

    Parameter Description

    sd

    Descriptor received by tdlsuspend().

  • Return Value

    Value Description

    TDL_OK

    Completed successfully.

    TDL_TRAN_ERROR

    The sd value is invalid. See tdlcall for more information.

21. tdlstart

The tdlstart function starts explicit version consistency maintenance.

  • Prototype

    #include <tdlcall.h>
int tdlstart(void)

  • Return Value

    Value Description

    TDL_OK

    The function call succeeded.

    TDL_TRAN_ERROR

    tdlstart() was executed before the required function call. See tdlcall.

22. tdlstat

The tdlstat function displays TDL statistics.

If VERSION=1 or VERSION=2 is set in the TDL configuration file (tdl.cfg), set MONITOR=Y in the 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 the function to collect statistics data.

    svc_time

    The service time record.

    cpu_time

    The CPU time record.

  • Return Value

    Value Description

    TDL_OK

    The function call succeeded.

    Smaller than 0

    The function call failed. See tdlerror.

23. tdlstat2

The tdlstat2 function displays TDL statistics.

If VERSION=3 is set in the TDL configuration file (tdl.cfg), set MONITOR=Y in the 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 the library to collect statistics data.

    funcname

    The name of the function to collect statistics data.

    svc_time

    The service time record.

    cpu_usrtime

    The user CPU time record.

    cpu_systime

    The system CPU time record.

  • Return Value

    Value Description

    TDL_OK

    The function call succeeded.

    Smaller than 0

    The function call failed. See tdlerror.

24. tdlsuspend

The tdlsuspend function suspends version consistency maintenance and returns a suspend descriptor (sd). The maximum number of concurrent suspend descriptors is 8.

  • Prototype

    #include <tdlcall.h>
int tdlsuspend(void)

  • Return Value

    Value Description

    Greater than or equal to 0

    The function call succeeded.

    TDL_TRAN_ERROR

    Version consistency maintenance is not currently active. See tdlcall for more information.