Version 2 of Tcl_CreateObjCommand

Updated 2006-09-19 14:08:54

TR - This C function is used to create a new command usable from the Tcl script level. The definition is

Tcl_Command Tcl_CreateObjCommand(interp, cmdName, proc, clientData, deleteProc)

so it returns a Tcl_Command (which is a token for the command) and takes 5 arguments:

  • interp - the interpreter in which to create the new command
  • cmdName - the name of the new command (possibly in a specific namespace)
  • proc - the name of a C function to handle the command execution when called by a script
  • clientData - some data associated with the command, when a state needs to be taken care of (a file for example); this is typically used where a proc is used to create a whole family of commands, such as the instances of a kind of Tk widget.
  • deleteProc - a C function to call when the command is deleted from the interpreter (used for cleanup of the clientData) which may be NULL if no cleanup is needed.

A full example of the usage can be found in: Hello World as a C extension. Here is an example from the sqlite extension used to create the 'sqlite' command:

 Tcl_CreateObjCommand(interp, "sqlite", (Tcl_ObjCmdProc*)DbMain, 0, 0);

An example using the clientData feature is here (also from sqlite):

 Tcl_CreateObjCommand(interp, zArg, DbObjCmd, (char*)p, DbDeleteCmd);

Here, the clientData are used to "bind" the created command to the database file for which is was created. In this example zArgs is a variable to hold the name of the created command. The command will be handled by the DbObjCmd C function and the clientData are "(char*)p" in this case holding the data for the opened sqlite database, so the otherwise generic DbObjCmd function can operate on the right database file.

Category Tcl Library