NAME

       Tcl_CreateCommand - implement new commands in C


SYNOPSIS

       #include <tcl.h>

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


ARGUMENTS

       Tcl_Interp          *interp           (in)      Inter­
                                                       preter  in
                                                       which   to
                                                       create new
                                                       command.

       char                *cmdName          (in)      Name    of
                                                       command.

       Tcl_CmdProc         *proc             (in)      Implemen­
                                                       tation  of
                                                       new   com­
                                                       mand:
                                                       proc  will
                                                       be  called
                                                       whenever
                                                       cmdName is
                                                       invoked as
                                                       a command.

       ClientData          clientData        (in)      Arbitrary
                                                       one-word
                                                       value   to
                                                       pass    to
                                                       proc   and
                                                       deleteProc.

       Tcl_CmdDeleteProc   *deleteProc       (in)      Procedure
                                                       to    call
                                                       before
                                                       cmdName is
                                                       deleted
                                                       from   the
                                                       inter­
                                                       preter;
                                                       allows for
                                                       command-
                                                       specific
                                                       cleanup.
                                                       If   NULL,
                                                       then    no
                                                       before the
                                                       command is
                                                       deleted.
_________________________________________________________________



DESCRIPTION

       Tcl_CreateCommand defines a  new  command  in  interp  and
       associates  it with procedure proc such that whenever cmd­
       Name is invoked as a Tcl command (via a call to  Tcl_Eval)
       the Tcl interpreter will call proc to process the command.
       It differs from Tcl_CreateObjCommand in that a new string-
       based  command is defined; that is, a command procedure is
       defined that takes an array of argument strings instead of
       objects.   The  object-based command procedures registered
       by Tcl_CreateObjCommand can execute  significantly  faster
       than   the  string-based  command  procedures  defined  by
       Tcl_CreateCommand.  This is because they take Tcl  objects
       as arguments and those objects can retain an internal rep­
       resentation that  can  be  manipulated  more  efficiently.
       Also,  Tcl's  interpreter now uses objects internally.  In
       order to invoke a string-based  command  procedure  regis­
       tered  by  Tcl_CreateCommand, it must generate and fetch a
       string representation from each argument object before the
       call and create a new Tcl object to hold the string result
       returned by the string-based command procedure.  New  com­
       mands  should  be  defined using Tcl_CreateObjCommand.  We
       support Tcl_CreateCommand for backwards compatibility.

       The procedures Tcl_DeleteCommand, Tcl_GetCommandInfo,  and
       Tcl_SetCommandInfo  are  used in conjunction with Tcl_Cre­
       ateCommand.

       Tcl_CreateCommand will delete an existing command cmdName,
       if  one  is  already  associated with the interpreter.  It
       returns a token that may be used to refer to  the  command
       in  subsequent  calls  to  Tcl_GetCommandName.  If cmdName
       contains any :: namespace qualifiers, then the command  is
       added to the specified namespace; otherwise the command is
       added to the global namespace.   If  Tcl_CreateCommand  is
       called  for an interpreter that is in the process of being
       deleted, then it does not create  a  new  command  and  it
       returns  NULL.  Proc should have arguments and result that
       match the type Tcl_CmdProc:
              typedef int Tcl_CmdProc(
                ClientData clientData,
                Tcl_Interp *interp,
                int argc,
                char *argv[]);
       When proc is invoked the clientData and interp  parameters
       will  be  copies  of  the  clientData and interp arguments
       given to Tcl_CreateCommand.  Typically, clientData  points
       and  argv describe the arguments to the command, argc giv­
       ing the number of arguments (including the  command  name)
       and  argv  giving  the values of the arguments as strings.
       The argv array will contain argc+1 values; the first  argc
       values  point  to the argument strings, and the last value
       is NULL.  Note that the argument  strings  should  not  be |
       modified  as  they may point to constant strings or may be |
       shared with other parts of the interpreter.

       Proc must return an integer code that  is  either  TCL_OK,
       TCL_ERROR,  TCL_RETURN,  TCL_BREAK,  or TCL_CONTINUE.  See
       the Tcl overview man page for details on what these  codes
       mean.   Most  normal  commands  will only return TCL_OK or
       TCL_ERROR.  In addition, proc  must  set  the  interpreter
       result to point to a string value; in the case of a TCL_OK
       return code this gives the result of the command,  and  in
       the  case  of  TCL_ERROR  it  gives an error message.  The
       Tcl_SetResult procedure provides  an  easy  interface  for
       setting the return value;  for complete details on how the
       the  interpreter  result  field  is   managed,   see   the
       Tcl_Interp man page.  Before invoking a command procedure,
       Tcl_Eval sets the interpreter result to point to an  empty
       string,  so  simple commands can return an empty result by
       doing nothing at all.

       The contents of the argv array belong to Tcl and  are  not
       guaranteed  to persist once proc returns:  proc should not
       modify them, nor should it set the interpreter  result  to
       point anywhere within the argv values.  Call Tcl_SetResult
       with status TCL_VOLATILE if you want to  return  something
       from the argv array.

       DeleteProc  will  be invoked when (if) cmdName is deleted.
       This can occur through  a  call  to  Tcl_DeleteCommand  or
       Tcl_DeleteInterp,  or by replacing cmdName in another call
       to Tcl_CreateCommand.  DeleteProc is  invoked  before  the
       command  is deleted, and gives the application an opportu­
       nity to release any structures associated  with  the  com­
       mand.   DeleteProc  should  have arguments and result that
       match the type Tcl_CmdDeleteProc:
              typedef void Tcl_CmdDeleteProc(ClientData clientData);
       The clientData argument will be the same as the clientData
       argument passed to Tcl_CreateCommand.




SEE ALSO

       Tcl_CreateObjCommand,  Tcl_DeleteCommand,  Tcl_GetCommand­
       Info, Tcl_SetCommandInfo,  Tcl_GetCommandName,  Tcl_SetOb­
       jResult


       bind, command, create, delete, interpreter, namespace