Both the Tcl and C APIs provide access to all the WTX protocol commands. Which API to use for a particular application or module depends on whether an interactive or a compiled environment is more appropriate to the specific task. For example, you might write a development tool in C for which you wish to provide the same level of configurability as the rest of Tornado. The Tcl API is well suited to this application, and in fact is used to configure the various Tornado tools.

When using Tcl and C APIs together, an important question to address is: within which API will the target server connection be created? The API which creates the connection also creates the handle name. The handle must be passed to the other API in order for it to access the target server.

If connections are to be created by Tcl code using the wtxToolAttach command, the C code can obtain the HWTX structure associated with a Tcl handle name with the C routine wtxTclHandle( ):

    HWTX wtxTclHandle (char * handleName) 

If you call this routine with a NULL argument, it returns the handle at the top of the Tcl handle stack.

If connections are to be created by C code calling wtxToolAttach( ), the C program can pass the C API handle to the Tcl interpreter by calling wtxTclHandleGrant( ):

    char * wtxTclHandleGrant (HWTX hWtx) 

If you call this routine with a C API handle, a Tcl handle is created and placed on the top of the Tcl handle stack. The routine returns the handle name used by Tcl. If the C program wishes to close one of these connections, it should first revoke the Tcl handle with wtxTclHandleRevoke( ):

    void wtxTclHandleRevoke (HWTX hWtx) 

You can integrate WTX Tcl with other Tcl interpreters. The shared library installDir/host/hostType/lib/libwtxtcl can be linked with any Tcl 8.0 application. You must initialize the library with a call to wtxTclInit( ), supplying the Tcl interpreter handle as an argument:

    int wtxTclInit (Tcl_Interp * pInterp)

Once you initialize the library, all the WTX Tcl commands are available to the Tcl interpreter. For example, to attach to a target, you can evaluate a wtxToolAttach Tcl expression.