TCL command in C, a simple example Nguyen Truong – GCS VN Aug 5, 2004

Introduction Introduce how to build a simple TCL command In this document, TCL command is a command (procedure) is implemented in C and called in TCL

Requirements Make splus command, that receives a number and return number + number, in C language. Deploy splus command as a TCL library so that splus command can be called from TCL code

Steps Step 1: Create C DLL Step 2: Deploy C DLL as a TCL library Step 3: Test

Step 1.1a: Create DLL Visual C++ project If you are familiar with Microsoft Visual C++, please skip this step Run Microsoft Visual C++, select menu File>New Select tab Projects Select Win 32 Dynamic-Link Library Select Location and type Project name Press OK

Step 1.1b: Create DLL Visual C++ project Select A simple DLL project Press Finish. Press OK on New Project Information dialog

Step 1.2a: Implement DLL body After finish creating project, there are several files created. We focus into splus.cpp only In order to easily follow subsequent slices, please print out splus.cpp in sample folder.

Step 1.2b: Impl. DLL body – Directives TCL library header This file resides in <TCLROOT>/include This file declares interfaces to C #include "stdafx.h" #include "stdlib.h" #include "tcl.h" #define SPLUS_API extern "C" __declspec(dllexport) Define constant for function-exporting. Functions declared with SPLUS_API are exported so that other applications can access In this example, only one function is exported, Spluspackage_Init

Step 1.2c: Impl. DLL body - TCL command In this document, TCL command is a command (procedure) is implemented in C and called in TCL A standard interface provided by TCL C-Library In TCL command code, behavior of a TCL command is implemented. For this sample, number + number is implemented. It is possible to implement several TCL commands in the same DLL

Step 1.2d: Impl. DLL body - TCL command, Interface Arbitrary data passed to command Not used in this example In fact, it is pointer to void. Return TCL_OK or TCL_ERROR. int splusCommand(ClientData clientData, Tcl_Interp *interp, int argc, char *argv[]) { . . . } TCL Interpreter data structure Number of arguments came from TCL command Argument values came from TCL command

Step 1.2e: Impl. DLL body - TCL command, Error processing Need 1 parameter at TCL command argv[0] contains DLL name int splusCommand(ClientData clientData, Tcl_Interp* interp, int argc, char* argv[]) { if (argc != 2) // Tell TCL splus needs 'number' parameter interp->result = "wrong # args: should be \"splus number\""; return TCL_ERROR; } . . . Return Error Message to TCL interpreter

Step 1.2f: Impl. DLL body - TCL command, Main function Result is returned as a string int splusCommand(ClientData clientData, Tcl_Interp* interp, int argc, char* argv[]) { . . . char buf[16]; int number = atoi(argv[1]); sprintf(buf, "%d", number + number); // Set result to TCL interpreter Tcl_SetResult(interp, buf, TCL_VOLATILE); return TCL_OK; } Return result to interpreter TCL_VOLATILE means buf will not be available after Tcl_SetResult. Return OK

Step 1.3a: Impl. DLL body – Package Initiation, Interface See Directives Function name must be compliant following pattern: <packagename>_Init SPLUS_API int Spluspackage_Init (Tcl_Interp *interp) { . . . } This function is automatically called by TCL shell when ever user calls package require SplusPackage command or equivalent commands

Step 1.3b: Impl. DLL body – Package Initiation, Stub initiation Ensure that the correct version of TCL is loaded Returns string contains actual version of loaded TCL or NULL SPLUS_API int Spluspackage_Init(Tcl_Interp *interp) { if (Tcl_InitStubs (interp, "8.1", 0) == NULL) return TCL_ERROR; } . . . TCL 8.1 is required TCL 8.x is also accepted as long as x >= 1

Step 1.3c: Impl. DLL body – Package Initiation, Command registration Define new command in TCL interpreter Can register more than one command Add new function, ‘splus’, to TCL interpreter SPLUS_API int Spluspackage_Init(Tcl_Interp *interp) { . . . Tcl_CreateCommand (interp, "splus", splusCommand, ClientData)NULL, Tcl_CmdDeleteProc *)NULL); } Command implementation See Step 1.2

Step 1.3d: Impl. DLL body – Package Initiation, Package registration Indicate package name and version of new package Like TCL command package provide. Package version SPLUS_API int Spluspackage_Init(Tcl_Interp *interp) { . . . Tcl_PkgProvide (interp, "SplusPackage", "1.0); } Package name

Step 1.4a: Compile and build – Project settings In MS Visual C++, select menu Project>Settings In tab Link, add tcl83.lib into end of box Object/library modules. Press OK

Step 1.4b: Compile and build – Environment settings In MS Visual C++, select menu Tools>Options In tab Directories, select Include files in box Show directories for. Click new button and enter <TCLHOME>\include in box Directories. See next slice

Step 1.4c: Compile and build – Environment settings Select Library files in box Show directories for. Click new button and enter <TCLHOME>\lib in box Directories. Press OK

Step 1.4d: Compile and build – Build In MS Visual C++, select menu Build>Build splus.dll. File splus.dll is created

Step 2: Deploy C DLL as a TCL library Create a text file named pkgIndex.tcl with 1 line in the content: package ifneeded SplusPackage 1.0 [list load [file join $dir splus.dll] SplusPackage] Please see article TCL Library - a simple example for further information. Copy splus.dll produced in step 1.4 and pkgIndex.tcl to deployment directory, for example, C:\MyTclCmd. Add deployment directory to environment variable TCLLIBPATH, for example TCLLIBPATH=C:/tcl C:/MyTclCmd Noted: using SPACE as separators between directories

Step 3: Test Start TCL shell Run commands and see result like picture below