Various utility TCL verbs

  • handleListFromType
  • nameGetFromType
  • typeGetFromName
  • verboseSet
  • treePrint
  • treeGet
  • mallinfoPrint
  • mallinfoGet
  • thingNew
  • thingDel
  • shMalloc
  • shCalloc
  • shFree
  • In addition there is the C routine shTclDeclare which should be used in order to declare your extensions to Tcl.

    handleListFromType

    Return a Tcl list of the handle names that are attached to a structure of the given type (i.e. REGION, PT, HDR... ). This is a Tcl procedure. TCL SYNTAX: handleListFromType <type> <type> An ASCII type.

    nameGetFromType

    Return the ASCII name associated with an integer type. The object whose type is<elem_size> given must have a schema defined within Dervish. TCL SYNTAX: nameGetFromType <integer type> <integer type> The integer value of the type of the object. RETURNS: TCL_OK Successful completion. The ASCII name associated with the type is returned. TCL_ERROR Error occurred.

    typeGetFromName

    Return the integer type value associated with an ASCII type name. The object whose ASCII type name is given must have a schema defined within Dervish. TCL SYNTAX: typeGetFromName <ASCII type name> <ASCII type name> The ASCII type name of the object. RETURNS: TCL_OK Successful completion. The integer type associated with the ASCII type name is returned. TCL_ERROR Error occurred.

    verboseSet

    Set the level of verbosity for shDebug. TCL SYNTAX: verboseSet <level> <level> Desired level RETURNS: TCL_OK Successful completion. The previous verbosity is returned TCL_ERROR Error occurred. If the level is negative, the current level is returned, but not changed.

    treePrint

    Print out all addresses that have been malloced with shMalloc and have not been freed. When possible, the handle name and type of handle are also printed out. Many things are malloced in Dervish that are not tied to a handle (such as region pixel areas and pixel vectors). In these cases only the address is printed out. The size of the malloced area is not saved and therefore not available.

    It is expected that this command will be useful in finding suspected memory leaks. After mallocing and then freeing many items, this command will list those addresses that were not freed and thus slipped through the cracks. In combination with the debugger, it will be possible to more acurately pinpoint memory problems and solve them.

    TCL SYNTAX: treePrint RETURNS: TCL_OK Successful completion. The total number of items is returned. TCL_ERROR Error occurred.

    treeGet

    Return all addresses that have been malloced with shMalloc and have not been freed as a Tcl list. When possible, the handle name and type of handle are included in the list. Many things are malloced in Dervish that are not tied to a handle (such as region pixel areas and pixel vectors). In these cases only the address is printed out. The size of the malloced area is not saved and therefore not available. For example, after doing a single regNew command, the following list could be generated -

    0x10105a0c 0x1011ce50 {0x10122978 h1 REGION}

    This Tcl list consists of 3 elements -

  • 0x10105a0c
  • 0x1011ce50
  • 0x10122978 h1 REGION
  • Notice that the third element is itself a Tcl list with 3 elements.

    It is expected that this command will be useful in finding suspected memory leaks. After mallocing and then freeing many items, this command will list those addresses that were not freed and thus slipped through the cracks. In combination with the debugger, it will be possible to more acurately pinpoint memory problems and solve them.

    TCL SYNTAX: treeGet RETURNS: TCL_OK Successful completion. TCL_ERROR Error occurred.

    mallinfoPrint

    Print out all elements of the mallinfo structure. This structure describes the current space usage of the program.

    TCL SYNTAX: mallinfoPrint RETURNS: TCL_OK Successful completion. TCL_ERROR Error occurred.

    mallinfoGet

    Return the mallinfo structure as a Tcl list. The structure elements have the following meaning -

    This structure describes the current space usage of the program. TCL SYNTAX: mallinfoGet RETURNS: TCL_OK Successful completion. The mallinfo structure is returned as a Tcl list. TCL_ERROR Error occurred.

    thingNew

    Create a new thing of the specified type pointing to address addr (default: NULL). TCL SYNTAX: thingNew <type> [addr] <type> Type of thing to create [addr] Address to which the newly created thing should point. RETURNS: TCL_OK Successful completion. The handle name of the new thing is returned. TCL_ERROR Error occurred.

    thingDel

    Delete a thing; it must contain a NULL pointer. TCL SYNTAX: thingNew <thing> <thing> Handle of thing to delete. RETURNS: TCL_OK Successful completion. TCL_ERROR Error occurred.

    shMalloc

    Malloc some space using shMalloc, and return it in a handle. TCL SYNTAX: shMalloc <len> <len> Number of bytes to malloc. RETURNS: TCL_OK Successful completion. The handle name is returned. TCL_ERROR Error occurred.

    shCalloc

    Malloc some space using shCalloc, and return it in a handle. TCL SYNTAX: shCalloc <num_elem> <elem_size> <num_elem> Number of elements to malloc. <elem_size> Size of each element to malloc RETURNS: TCL_OK Successful completion. The handle name is returned. TCL_ERROR Error occurred.

    shFree

    Use shFree to Free some shMalloced space, associated with the passed handle. TCL SYNTAX: shFree <handle> <handle> Handle to space to free. RETURNS: TCL_OK Successful completion. TCL_ERROR Error occurred.

    shTclDeclare

    This procedure is the supported jacket for declaring dervish TCL extensions to an interpreter. Users should NOT call Tcl_CreateCommand directly. This procedure loads the FTCL run-time help facility and then creates the command in the given interp. The HELPFACILITY string should be chosen to name the set of commands you are writing uniquely. The CMDPROTOYPE is not yet checked, but should, for future compatibility, be a valid FTCL PARSE prototype. The HELPTEXT should contain a brief, plain language description of what the command does. Help shown to the user will be built from the concatenation of all the strings. DATA and PROC are passed directly to Tcl_CreateCommand.

    C SYNTAX: int shTclDeclare ( Tcl_Interp *interp /* MOD: Interpreter to declare the command to*/ char *cmdName /* IN: Name of the command */ Tcl_CmdProc *cmdProc /* IN: Address of the c routine for the */ /* command */ Client_Data data /* In: Passed directly to Tcl_CreateCommand*/ Tcl_CmdDeleteProc *proc /* IN: Passed directly to Tcl_CreateCommand */ char *helpFacility /* IN: Pointer to string identifying this */ /* command's facility */ char *helpText /* IN: Pointer to string giving brief help */ /* text for this command*/ char *cmdProtoype /* IN: Pointer to string with TFCL prototype*/ ) RETURNS: TCL_OK TCL_ERROR