\section{trees\_\-addremoverings.c File Reference}
\label{trees__addremoverings_8c}\index{trees_addremoverings.c@{trees\_\-addremoverings.c}}
Glue code for using the C add and remove ring operations with Tcl/Tk. 

{\tt \#include $<$tcl.h$>$}\par
{\tt \#include $<$tk.h$>$}\par
{\tt \#include \char`\"{}logerr.h\char`\"{}}\par
{\tt \#include $<$sadie.h$>$}\par
{\tt \#include \char`\"{}chain.h\char`\"{}}\par
{\tt \#include \char`\"{}chain\_\-provisional.h\char`\"{}}\par
\subsection*{Classes}
\begin{CompactItemize}
\item 
struct {\bf Ring\_\-candidate}
\begin{CompactList}\small\item\em One ring in a list of rings (e.g., candidates for insertion or removal). \item\end{CompactList}\item 
struct {\bf Boxed\_\-boundary}
\begin{CompactList}\small\item\em The association of a chaincoded boundary and its bounding box. \item\end{CompactList}\end{CompactItemize}
\subsection*{Defines}
\begin{CompactItemize}
\item 
\#define {\bf TEMP\_\-OBJ\_\-ARRAY\_\-LEN}\ 4\label{trees__addremoverings_8c_a0}

\end{CompactItemize}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
typedef {\bf Ring\_\-candidate} $\ast$ {\bf ring\_\-candidatep\_\-t}\label{trees__addremoverings_8c_a1}

\begin{CompactList}\small\item\em Points to a list of (non-contiguous) rings. \item\end{CompactList}\item 
typedef {\bf Boxed\_\-boundary} $\ast$ {\bf boxed\_\-boundaryp\_\-t}\label{trees__addremoverings_8c_a2}

\begin{CompactList}\small\item\em Points to a list of chaincoded boundaries and their bounding boxes. \item\end{CompactList}\item 
typedef int($\ast$ {\bf data\_\-accessor\_\-t} )(char $\ast$doc, char $\ast$pname, int $\ast$n, Tcl\_\-Obj $\ast$objarr[$\,$])\label{trees__addremoverings_8c_a8}

\begin{CompactList}\small\item\em An accessor function turns various saved data into Tcl object arrays. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
int {\bf TREES\_\-add\_\-provisional\-Cmd} (Client\-Data client\-Data, Tcl\_\-Interp $\ast$interp, int objc, Tcl\_\-Obj $\ast$const objv[$\,$])
\begin{CompactList}\small\item\em Add a new ring boundary between two existing chain-coded boundaries. \item\end{CompactList}\item 
int {\bf TREES\_\-remove\_\-provisional\-Cmd} (Client\-Data client\-Data, Tcl\_\-Interp $\ast$interp, int objc, Tcl\_\-Obj $\ast$const objv[$\,$])
\begin{CompactList}\small\item\em Remove an existing ring boundary (re-computing the affected measurements). \item\end{CompactList}\item 
int {\bf TREES\_\-missing\_\-provisional\-Cmd} (Client\-Data client\-Data, Tcl\_\-Interp $\ast$interp, int objc, Tcl\_\-Obj $\ast$const objv[$\,$])
\begin{CompactList}\small\item\em Insert a missing ring at an existing ring boundary. \item\end{CompactList}\item 
int {\bf TREES\_\-display\_\-provisional\-Cmd} (Client\-Data client\-Data, Tcl\_\-Interp $\ast$interp, int objc, Tcl\_\-Obj $\ast$const objv[$\,$])
\begin{CompactList}\small\item\em Draw a full-resolution provisional ring boundary. \item\end{CompactList}\item 
int {\bf TREES\_\-display\_\-small\_\-provisional\-Cmd} (Client\-Data client\-Data, Tcl\_\-Interp $\ast$interp, int objc, Tcl\_\-Obj $\ast$const objv[$\,$])
\begin{CompactList}\small\item\em Draw a low-resolution provisional ring boundary. \item\end{CompactList}\item 
int {\bf TREES\_\-undisplay\_\-provisional\-Cmd} (Client\-Data client\-Data, Tcl\_\-Interp $\ast$interp, int objc, Tcl\_\-Obj $\ast$const objv[$\,$])
\begin{CompactList}\small\item\em Delete a provisional ring boundary from the Tk canvas. \item\end{CompactList}\item 
int {\bf TREES\_\-color\_\-provisional\-Cmd} (Client\-Data client\-Data, Tcl\_\-Interp $\ast$interp, int objc, Tcl\_\-Obj $\ast$const objv[$\,$])
\begin{CompactList}\small\item\em Change the color of a boundary that is already on the Tk canvas. \item\end{CompactList}\item 
int {\bf TREES\_\-commit\_\-provisional\-Cmd} (Client\-Data client\-Data, Tcl\_\-Interp $\ast$interp, int objc, Tcl\_\-Obj $\ast$const objv[$\,$])
\begin{CompactList}\small\item\em Commit a provisional boundary addition to the main Tcl structures of TREES. \item\end{CompactList}\item 
int {\bf TREES\_\-commit\_\-removal\-Cmd} (Client\-Data client\-Data, Tcl\_\-Interp $\ast$interp, int objc, Tcl\_\-Obj $\ast$const objv[$\,$])
\begin{CompactList}\small\item\em Commit a provisional boundary removal to the main Tcl structures of TREES. \item\end{CompactList}\item 
int {\bf TREES\_\-addremoverings\_\-Init} (Tcl\_\-Interp $\ast$interp)
\begin{CompactList}\small\item\em Create the new Tcl commands associated with adding and removing boundaries. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Glue code for using the C add and remove ring operations with Tcl/Tk. 

There are two aspects to this. We determine provisional changes (provisionally inserted or deleted ring boundaries), and save the revised measurements, but do not modify the main data structures used by the Tcl parts of TREES immediately. Subsequently (presumably with some user interaction) we do commit the provisional changes so that they become indistinguishable from the original contents of the main TREES data structures. Other parts of the program handle the re-analysis (interpolating ring boundaries, computing revised measurements, and so on) and storage of the provisional data: see the {\bf chain\_\-provisional.c}{\rm (p.\,\pageref{chain__provisional_8c})} and {\bf chain\_\-provisional.h}{\rm (p.\,\pageref{chain__provisional_8h})} files for the details.

\begin{Desc}
\item[Author:]University of Arizona Digital Image Analysis Lab \end{Desc}
\begin{Desc}
\item[Date:]2004 \end{Desc}
\begin{Desc}
\item[Version:]\begin{Desc}
\item[Id]{\bf trees\_\-addremoverings.c}{\rm (p.\,\pageref{trees__addremoverings_8c})},v 1.4 2004/11/12 22:50:00 mmunro Exp \end{Desc}
\end{Desc}


\subsection{Function Documentation}
\index{trees_addremoverings.c@{trees\_\-addremoverings.c}!TREES_add_provisionalCmd@{TREES\_\-add\_\-provisionalCmd}}
\index{TREES_add_provisionalCmd@{TREES\_\-add\_\-provisionalCmd}!trees_addremoverings.c@{trees\_\-addremoverings.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int TREES\_\-add\_\-provisional\-Cmd (Client\-Data {\em client\-Data}, Tcl\_\-Interp $\ast$ {\em interp}, int {\em objc}, Tcl\_\-Obj $\ast$const  {\em objv}[$\,$])}\label{trees__addremoverings_8c_a19}


Add a new ring boundary between two existing chain-coded boundaries. 

Follow the standard Tcl\_\-Obj\-Cmd\-Proc prototype for C glue code in Tcl. On the Tcl side of things, document identifies the grouping of saved settings for a particular analysis, provbnum will identify the new boundary and the two sets of measurements associated with it, mosaic is the string encoding the storage location of the image mosaic, index identifies the data structure holding the region-of-interest definition and other indices into this mosaic, chainmap identifies the lists of full-resolution chain-coded boundaries, scale is the downsampling factor used when creating low-resolution boundaries, x\_\-coord and y\_\-coord are the coordinates within the image mosaic near where we will construct the interpolated boundary, and bbox\_\-name is the name of the Tcl list of bounding box coordinates. The changes get saved into an entry in the hash table and not immediately incorporated into changes to the chain map and measurements. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em client\-Data}]currently unused (but required for a Tcl\_\-Obj\-Cmd\-Proc). \item[{\em interp}]the Tcl interpreter within which to define the command. \item[{\em objc}]the number of Tcl objects passed to the command. \item[{\em objv}]the array of Tcl objects. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the TCL\_\-OK code on success, the TCL\_\-ERROR code on failure. \end{Desc}
\index{trees_addremoverings.c@{trees\_\-addremoverings.c}!TREES_addremoverings_Init@{TREES\_\-addremoverings\_\-Init}}
\index{TREES_addremoverings_Init@{TREES\_\-addremoverings\_\-Init}!trees_addremoverings.c@{trees\_\-addremoverings.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int TREES\_\-addremoverings\_\-Init (Tcl\_\-Interp $\ast$ {\em interp})}\label{trees__addremoverings_8c_a48}


Create the new Tcl commands associated with adding and removing boundaries. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em interp}]the Tcl interpreter within which to define the commands. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the TCL\_\-OK code on success, the TCL\_\-ERROR code on failure. \end{Desc}
\index{trees_addremoverings.c@{trees\_\-addremoverings.c}!TREES_color_provisionalCmd@{TREES\_\-color\_\-provisionalCmd}}
\index{TREES_color_provisionalCmd@{TREES\_\-color\_\-provisionalCmd}!trees_addremoverings.c@{trees\_\-addremoverings.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int TREES\_\-color\_\-provisional\-Cmd (Client\-Data {\em client\-Data}, Tcl\_\-Interp $\ast$ {\em interp}, int {\em objc}, Tcl\_\-Obj $\ast$const  {\em objv}[$\,$])}\label{trees__addremoverings_8c_a27}


Change the color of a boundary that is already on the Tk canvas. 

Follow the standard Tcl\_\-Obj\-Cmd\-Proc prototype for C glue code in Tcl. On the Tcl side of things, canvas specifies the Tk canvas within which the drawing takes place, doc identifies the grouping of saved settings for a particular analysis, and provbnum is the number identifying the provisional boundary, and color is the new color to use. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em client\-Data}]currently unused (but required for a Tcl\_\-Obj\-Cmd\-Proc). \item[{\em interp}]the Tcl interpreter within which to define the command. \item[{\em objc}]the number of Tcl objects passed to the command. \item[{\em objv}]the array of Tcl objects. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the TCL\_\-OK code on success, the TCL\_\-ERROR code on failure. \end{Desc}
\index{trees_addremoverings.c@{trees\_\-addremoverings.c}!TREES_commit_provisionalCmd@{TREES\_\-commit\_\-provisionalCmd}}
\index{TREES_commit_provisionalCmd@{TREES\_\-commit\_\-provisionalCmd}!trees_addremoverings.c@{trees\_\-addremoverings.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int TREES\_\-commit\_\-provisional\-Cmd (Client\-Data {\em client\-Data}, Tcl\_\-Interp $\ast$ {\em interp}, int {\em objc}, Tcl\_\-Obj $\ast$const  {\em objv}[$\,$])}\label{trees__addremoverings_8c_a46}


Commit a provisional boundary addition to the main Tcl structures of TREES. 

Follow the standard Tcl\_\-Obj\-Cmd\-Proc prototype for C glue code in Tcl. On the Tcl side of things, document identifies the grouping of saved settings for a particular analysis, provbnum identifies the provisional boundary and the sets of measurements associated with it, chain identifies the lists of full-resolution chain-coded boundaries, smallchain identifies the lists of low-resolution chain-coded boundaries, widthlist names the list of total ring widths, profilelist names the list of brightness profile data, diff\_\-profilelist names the list of first-differenced brightness profiles, earlywidthlist names the list of earlywood widths, latewidthlist names the list of latewood widths, boundboxlist names the list of bounding box coordinates, masterlist names the list of ring boundaries (in a form suitable for use in the skeleton plot display with their associated data), and notes is the list of short textual notes by the tree-ring analyst. We return the (integer) index position of the insertion point within the Tcl list in the Tcl result object. The provisional data must already exist, stored in the location identified by document and provbnum. When we commit them, we modify all the primary data structures used by the Tcl parts of TREES to store measurements and housekeeping information, and the next save to a data file should make the changes permanent. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em client\-Data}]currently unused (but required for a Tcl\_\-Obj\-Cmd\-Proc). \item[{\em interp}]the Tcl interpreter within which to define the command. \item[{\em objc}]the number of Tcl objects passed to the command. \item[{\em objv}]the array of Tcl objects. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the TCL\_\-OK code on success, the TCL\_\-ERROR code on failure. \end{Desc}
\index{trees_addremoverings.c@{trees\_\-addremoverings.c}!TREES_commit_removalCmd@{TREES\_\-commit\_\-removalCmd}}
\index{TREES_commit_removalCmd@{TREES\_\-commit\_\-removalCmd}!trees_addremoverings.c@{trees\_\-addremoverings.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int TREES\_\-commit\_\-removal\-Cmd (Client\-Data {\em client\-Data}, Tcl\_\-Interp $\ast$ {\em interp}, int {\em objc}, Tcl\_\-Obj $\ast$const  {\em objv}[$\,$])}\label{trees__addremoverings_8c_a47}


Commit a provisional boundary removal to the main Tcl structures of TREES. 

Follow the standard Tcl\_\-Obj\-Cmd\-Proc prototype for C glue code in Tcl. On the Tcl side of things, document identifies the grouping of saved settings for a particular analysis, provbnum identifies the removed boundary and the sets of measurements associated with it, chain identifies the lists of full-resolution chain-coded boundaries, smallchain identifies the lists of low-resolution chain-coded boundaries, widthlist names the list of total ring widths, profilelist names the list of brightness profile data, diff\_\-profilelist names the list of first-differenced brightness profiles, earlywidthlist names the list of earlywood widths, latewidthlist names the list of latewood widths, boundboxlist names the list of bounding box coordinates, masterlist names the list of ring boundaries, and notes is the list of short textual notes by the tree-ring analyst. We return the (integer) index position of the removal point within the Tcl list in the Tcl result object. The provisional data must already exist, stored in the location identified by document and provbnum. When we commit them, we modify all the primary data structures used by the Tcl parts of TREES to store measurements and housekeeping information, and the next save to a data file should make the changes permanent. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em client\-Data}]currently unused (but required for a Tcl\_\-Obj\-Cmd\-Proc). \item[{\em interp}]the Tcl interpreter within which to define the command. \item[{\em objc}]the number of Tcl objects passed to the command. \item[{\em objv}]the array of Tcl objects. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the TCL\_\-OK code on success, the TCL\_\-ERROR code on failure. \end{Desc}
\index{trees_addremoverings.c@{trees\_\-addremoverings.c}!TREES_display_provisionalCmd@{TREES\_\-display\_\-provisionalCmd}}
\index{TREES_display_provisionalCmd@{TREES\_\-display\_\-provisionalCmd}!trees_addremoverings.c@{trees\_\-addremoverings.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int TREES\_\-display\_\-provisional\-Cmd (Client\-Data {\em client\-Data}, Tcl\_\-Interp $\ast$ {\em interp}, int {\em objc}, Tcl\_\-Obj $\ast$const  {\em objv}[$\,$])}\label{trees__addremoverings_8c_a23}


Draw a full-resolution provisional ring boundary. 

Follow the standard Tcl\_\-Obj\-Cmd\-Proc prototype for C glue code in Tcl. On the Tcl side of things, canvas specifies the Tk canvas within which the drawing takes place (such as the zoom window), x\_\-origin and y\_\-origin define the offsets between the origin used in the image mosaic and the canvas origin, doc identifies the grouping of saved settings for a particular analysis, provbnum is the number identifying the provisional boundary, and color is the color for the lines making up the boundary. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em client\-Data}]currently unused (but required for a Tcl\_\-Obj\-Cmd\-Proc). \item[{\em interp}]the Tcl interpreter within which to define the command. \item[{\em objc}]the number of Tcl objects passed to the command. \item[{\em objv}]the array of Tcl objects. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the TCL\_\-OK code on success, the TCL\_\-ERROR code on failure. \end{Desc}
\index{trees_addremoverings.c@{trees\_\-addremoverings.c}!TREES_display_small_provisionalCmd@{TREES\_\-display\_\-small\_\-provisionalCmd}}
\index{TREES_display_small_provisionalCmd@{TREES\_\-display\_\-small\_\-provisionalCmd}!trees_addremoverings.c@{trees\_\-addremoverings.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int TREES\_\-display\_\-small\_\-provisional\-Cmd (Client\-Data {\em client\-Data}, Tcl\_\-Interp $\ast$ {\em interp}, int {\em objc}, Tcl\_\-Obj $\ast$const  {\em objv}[$\,$])}\label{trees__addremoverings_8c_a24}


Draw a low-resolution provisional ring boundary. 

Follow the standard Tcl\_\-Obj\-Cmd\-Proc prototype for C glue code in Tcl. On the Tcl side of things, canvas specifies the Tk canvas within which the drawing takes place (such as the browse window), doc identifies the grouping of saved settings for a particular analysis, provbnum is the number identifying the provisional boundary, and color is the color for the lines making up the boundary. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em client\-Data}]currently unused (but required for a Tcl\_\-Obj\-Cmd\-Proc). \item[{\em interp}]the Tcl interpreter within which to define the command. \item[{\em objc}]the number of Tcl objects passed to the command. \item[{\em objv}]the array of Tcl objects. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the TCL\_\-OK code on success, the TCL\_\-ERROR code on failure. \end{Desc}
\index{trees_addremoverings.c@{trees\_\-addremoverings.c}!TREES_missing_provisionalCmd@{TREES\_\-missing\_\-provisionalCmd}}
\index{TREES_missing_provisionalCmd@{TREES\_\-missing\_\-provisionalCmd}!trees_addremoverings.c@{trees\_\-addremoverings.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int TREES\_\-missing\_\-provisional\-Cmd (Client\-Data {\em client\-Data}, Tcl\_\-Interp $\ast$ {\em interp}, int {\em objc}, Tcl\_\-Obj $\ast$const  {\em objv}[$\,$])}\label{trees__addremoverings_8c_a21}


Insert a missing ring at an existing ring boundary. 

Follow the standard Tcl\_\-Obj\-Cmd\-Proc prototype for C glue code in Tcl. On the Tcl side of things, document identifies the grouping of saved settings for a particular analysis, provbnum will identify the modified set of measurements associated with the removed boundary, mosaic is the string encoding the storage location of the image mosaic, index identifies the data structure holding the region-of-interest definition and other indices into this mosaic, chainmap identifies the lists of full-resolution chain-coded boundaries, smallchainmap identifies the lists of low-resolution chain-coded boundaries, x\_\-coord and y\_\-coord are the coordinates within the image mosaic near the existing boundary, and bbox\_\-name is the name of the Tcl list of bounding box coordinates. The changes get saved into an entry in the hash table and not immediately incorporated into changes to the chain map and measurements. We set the Tcl result object to a boolean flag showing whether the missing ring insertion was successful. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em client\-Data}]currently unused (but required for a Tcl\_\-Obj\-Cmd\-Proc). \item[{\em interp}]the Tcl interpreter within which to define the command. \item[{\em objc}]the number of Tcl objects passed to the command. \item[{\em objv}]the array of Tcl objects. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the TCL\_\-OK code on success, the TCL\_\-ERROR code on failure. \end{Desc}
\index{trees_addremoverings.c@{trees\_\-addremoverings.c}!TREES_remove_provisionalCmd@{TREES\_\-remove\_\-provisionalCmd}}
\index{TREES_remove_provisionalCmd@{TREES\_\-remove\_\-provisionalCmd}!trees_addremoverings.c@{trees\_\-addremoverings.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int TREES\_\-remove\_\-provisional\-Cmd (Client\-Data {\em client\-Data}, Tcl\_\-Interp $\ast$ {\em interp}, int {\em objc}, Tcl\_\-Obj $\ast$const  {\em objv}[$\,$])}\label{trees__addremoverings_8c_a20}


Remove an existing ring boundary (re-computing the affected measurements). 

Follow the standard Tcl\_\-Obj\-Cmd\-Proc prototype for C glue code in Tcl. On the Tcl side of things, document identifies the grouping of saved settings for a particular analysis, provbnum will identify the modified set of measurements associated with the removed boundary, mosaic is the string encoding the storage location of the image mosaic, index identifies the data structure holding the region-of-interest definition and other indices into this mosaic, chainmap identifies the lists of full-resolution chain-coded boundaries, smallchainmap identifies the lists of low-resolution chain-coded boundaries, x\_\-coord and y\_\-coord are the coordinates within the image mosaic near the existing boundary, and bbox\_\-name is the name of the Tcl list of bounding box coordinates. The changes get saved into an entry in the hash table and not immediately incorporated into changes to the chain map and measurements. We set the Tcl result object to a boolean flag showing whether the provisional boundary deletion was successful. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em client\-Data}]currently unused (but required for a Tcl\_\-Obj\-Cmd\-Proc). \item[{\em interp}]the Tcl interpreter within which to define the command. \item[{\em objc}]the number of Tcl objects passed to the command. \item[{\em objv}]the array of Tcl objects. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the TCL\_\-OK code on success, the TCL\_\-ERROR code on failure. \end{Desc}
\index{trees_addremoverings.c@{trees\_\-addremoverings.c}!TREES_undisplay_provisionalCmd@{TREES\_\-undisplay\_\-provisionalCmd}}
\index{TREES_undisplay_provisionalCmd@{TREES\_\-undisplay\_\-provisionalCmd}!trees_addremoverings.c@{trees\_\-addremoverings.c}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int TREES\_\-undisplay\_\-provisional\-Cmd (Client\-Data {\em client\-Data}, Tcl\_\-Interp $\ast$ {\em interp}, int {\em objc}, Tcl\_\-Obj $\ast$const  {\em objv}[$\,$])}\label{trees__addremoverings_8c_a25}


Delete a provisional ring boundary from the Tk canvas. 

Follow the standard Tcl\_\-Obj\-Cmd\-Proc prototype for C glue code in Tcl. On the Tcl side of things, canvas specifies the Tk canvas within which the drawing takes place, doc identifies the grouping of saved settings for a particular analysis, and provbnum is the number identifying the provisional boundary. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em client\-Data}]currently unused (but required for a Tcl\_\-Obj\-Cmd\-Proc). \item[{\em interp}]the Tcl interpreter within which to define the command. \item[{\em objc}]the number of Tcl objects passed to the command. \item[{\em objv}]the array of Tcl objects. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the TCL\_\-OK code on success, the TCL\_\-ERROR code on failure. \end{Desc}
