generic/interface/UserData.h

/*
 *  UserData.h
 *  by Kirk Abbott and Ben Allan
 *  Created: 1/94
 *  Version: $Revision: 1.6 $
 *  Version control file: $RCSfile: UserData.h,v $
 *  Date last modified: $Date: 2003/08/23 18:43:09 $
 *  Last modified by: $Author: ballan $
 *
 *  This file is part of the ASCEND Tcl/Tk interface
 *
 *  Copyright 1997, Carnegie Mellon University
 *
 *  The ASCEND Tcl/Tk interface is free software; you can redistribute
 *  it and/or modify it under the terms of the GNU General Public License as
 *  published by the Free Software Foundation; either version 2 of the
 *  License, or (at your option) any later version.
 *
 *  The ASCEND Tcl/Tk interface is distributed in hope that it will be
 *  useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with the program; if not, write to the Free Software Foundation,
 *  Inc., 675 Mass Ave, Cambridge, MA 02139 USA.  Check the file named
 *  COPYING.  COPYING is found in ../compiler.
 */

/** @file
 *  User data procedures.
 *  <pre>
 *  To include this header, you must include the following:
 *      #include "tcl.h"
 *      #include "utilities/ascConfig.h"
 *      #include "interface/UserData.h"
 *  </pre>
 *  @todo See note at bottom of interface/UserData.h.
 */

#ifndef ASCTK_USERPROC_H
#define ASCTK_USERPROC_H

extern void Asc_UserDataLibraryInitialize(void);
/**<
 *  Initializes the user data library to NULL. Should only be
 *  called once. Does not check for existence or anything.
 */

extern int Asc_UserDataInitializeCmd(ClientData cdata, Tcl_Interp *interp,
                                     int argc, CONST84 char *argv[]);
/**<
 *  The tcl command to allow initialization interactively.
 *  Initializes the user data library to NULL. Should only be
 *  called once. Does not check for existence or anything.<br><br>
 *
 *  Registered as:  __userdata_init
 */

extern int Asc_UserDataDestroyCmd(ClientData cdata, Tcl_Interp *interp,
                                  int argc, CONST84 char *argv[]);
/**<
 *  Will deallocate the memory associated with the user data with given
 *  id. In the 'all' mode, will deallocate everything and set up the
 *  user data library for initializion. This is the mode that would be
 *  used if the entire library were to be flushed if say, a simulation
 *  were to be deleted.<br><br>
 *
 *  Usage :
 *    - __userdata_destroy one foo;
 *    - __userdata_destroy all;
 *
 *  Registered as: __userdata_destroy ?one?all? id
 */

extern int Asc_UserDataCreateCmd(ClientData cdata, Tcl_Interp *interp,
                                 int argc, CONST84 char *argv[]);
/**<
 *  This creates a node and stores it in the UserData table.
 *  Type is any valid string of "real_info", "inst_info",
 *  "probe_info", "list_info". The id of the user_data node created will
 *  be returned and has to be the refence id for subsequent queries on the
 *  object.<br><br>
 *
 *  Registered as : __userdata_create type
 */

extern int Asc_UserDataSaveValuesCmd(ClientData cdata, Tcl_Interp *interp,
                                     int argc, CONST84 char *argv[]);
/**<
 *  The userdata library is searched for the given from instance. If found
 *  will simply update the REAL_ATOM_INST in the virtual file. Otherwise
 *  it will create a userdata node, visit the instance tree to write to the
 *  virtual file, and add this node to the userdata table.
 *  The id of the node is returned if all goes well.
 *  Here 'from' is either of current, search, of an id which has been
 *  previously been stored in the table as an inst_info.<br><br>
 *
 *  Registered as : __userdata_save from to
 */

extern int Asc_UserDataRestoreValuesCmd(ClientData cdata, Tcl_Interp *interp,
                                        int argc, CONST84 char *argv[]);
/**<
 *  The id is looked up in the userdata library. If not found an error will
 *  be returned. Otherwise the values stored in the virtual file will be
 *  copied back to the instance tree. The userdata associated with this id
 *  must be of type real_info.<br><br>
 *
 *  Registered as : __userdata_restore id
 */

extern int Asc_UserDataQueryCmd(ClientData cdata, Tcl_Interp *interp,
                                int argc, CONST84 char *argv[]);
/**<
 *  This provides some general query commands. At the moment the only
 *  queries supported are the type of an id and whether a given id
 *  exists within the user_data library. In case a given id does not
 *  exist the string "error_info" will be returned.<br><br>
 *
 *  Registered as : __userdata_query ?type?exist? id.
 */

extern int Asc_UserDataPrintLibrary(ClientData cdata, Tcl_Interp *interp,
                                    int argc, CONST84 char *argv[]);
/**<
 *  This command will return a formatted string of containing the contents
 *  of the user_data library. The string will be a proper list with list
 *  elements of the form {id type}.<br><br>
 *
 *  Registered as : __userdata_print
 */

/*
 * It is hoped to register two functions of the form.
 * __userdata__apply
 *       ?to_inst_info?to_list_info?to_real_info?to_probe_info?
 *       id funcname.
 *
 * where: id is the id of a user data stored in the user data library.
 *    funcname is the id of a function possibly also stored in
 *    the user data library, or maybe the external function library.
 *    that will operate over the different user data types stored in
 *    in the userdata library.
 */

#endif  /* ASCTK_USERPROC_H */

1	aw0a	1	/*
2			* UserData.h
3			* by Kirk Abbott and Ben Allan
4			* Created: 1/94
5			* Version: $Revision: 1.6 $
6			* Version control file: $RCSfile: UserData.h,v $
7			* Date last modified: $Date: 2003/08/23 18:43:09 $
8			* Last modified by: $Author: ballan $
9			*
10			* This file is part of the ASCEND Tcl/Tk interface
11			*
12			* Copyright 1997, Carnegie Mellon University
13			*
14			* The ASCEND Tcl/Tk interface is free software; you can redistribute
15			* it and/or modify it under the terms of the GNU General Public License as
16			* published by the Free Software Foundation; either version 2 of the
17			* License, or (at your option) any later version.
18			*
19			* The ASCEND Tcl/Tk interface is distributed in hope that it will be
20			* useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
21			* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22			* General Public License for more details.
23			*
24			* You should have received a copy of the GNU General Public License
25			* along with the program; if not, write to the Free Software Foundation,
26			* Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
27			* COPYING. COPYING is found in ../compiler.
28			*/
29
30	jds	54	/** @file
31			* User data procedures.
32			* <pre>
33	aw0a	1	* To include this header, you must include the following:
34			* #include "tcl.h"
35	jds	54	* #include "utilities/ascConfig.h"
36	aw0a	1	* #include "interface/UserData.h"
37	jds	54	* </pre>
38			* @todo See note at bottom of interface/UserData.h.
39	aw0a	1	*/
40
41	johnpye	67	#ifndef ASCTK_USERPROC_H
42			#define ASCTK_USERPROC_H
43	aw0a	1
44			extern void Asc_UserDataLibraryInitialize(void);
45	jds	54	/**<
46	aw0a	1	* Initializes the user data library to NULL. Should only be
47			* called once. Does not check for existence or anything.
48			*/
49
50			extern int Asc_UserDataInitializeCmd(ClientData cdata, Tcl_Interp *interp,
51			int argc, CONST84 char *argv[]);
52	jds	54	/**<
53	aw0a	1	* The tcl command to allow initialization interactively.
54			* Initializes the user data library to NULL. Should only be
55	jds	54	* called once. Does not check for existence or anything.<br><br>
56			*
57			* Registered as: __userdata_init
58	aw0a	1	*/
59
60			extern int Asc_UserDataDestroyCmd(ClientData cdata, Tcl_Interp *interp,
61	jds	54	int argc, CONST84 char *argv[]);
62			/**<
63	aw0a	1	* Will deallocate the memory associated with the user data with given
64			* id. In the 'all' mode, will deallocate everything and set up the
65			* user data library for initializion. This is the mode that would be
66			* used if the entire library were to be flushed if say, a simulation
67	jds	54	* were to be deleted.<br><br>
68			*
69			* Usage :
70			* - __userdata_destroy one foo;
71			* - __userdata_destroy all;
72			*
73			* Registered as: __userdata_destroy ?one?all? id
74	aw0a	1	*/
75
76			extern int Asc_UserDataCreateCmd(ClientData cdata, Tcl_Interp *interp,
77	jds	54	int argc, CONST84 char *argv[]);
78			/**<
79	aw0a	1	* This creates a node and stores it in the UserData table.
80			* Type is any valid string of "real_info", "inst_info",
81			* "probe_info", "list_info". The id of the user_data node created will
82			* be returned and has to be the refence id for subsequent queries on the
83	jds	54	* object.<br><br>
84			*
85			* Registered as : __userdata_create type
86	aw0a	1	*/
87
88			extern int Asc_UserDataSaveValuesCmd(ClientData cdata, Tcl_Interp *interp,
89	jds	54	int argc, CONST84 char *argv[]);
90			/**<
91	aw0a	1	* The userdata library is searched for the given from instance. If found
92			* will simply update the REAL_ATOM_INST in the virtual file. Otherwise
93			* it will create a userdata node, visit the instance tree to write to the
94			* virtual file, and add this node to the userdata table.
95			* The id of the node is returned if all goes well.
96	jds	54	* Here 'from' is either of current, search, of an id which has been
97			* previously been stored in the table as an inst_info.<br><br>
98			*
99			* Registered as : __userdata_save from to
100	aw0a	1	*/
101
102			extern int Asc_UserDataRestoreValuesCmd(ClientData cdata, Tcl_Interp *interp,
103	jds	54	int argc, CONST84 char *argv[]);
104			/**<
105	aw0a	1	* The id is looked up in the userdata library. If not found an error will
106			* be returned. Otherwise the values stored in the virtual file will be
107			* copied back to the instance tree. The userdata associated with this id
108	jds	54	* must be of type real_info.<br><br>
109			*
110			* Registered as : __userdata_restore id
111	aw0a	1	*/
112
113			extern int Asc_UserDataQueryCmd(ClientData cdata, Tcl_Interp *interp,
114	jds	54	int argc, CONST84 char *argv[]);
115			/**<
116	aw0a	1	* This provides some general query commands. At the moment the only
117			* queries supported are the type of an id and whether a given id
118			* exists within the user_data library. In case a given id does not
119	jds	54	* exist the string "error_info" will be returned.<br><br>
120			*
121			* Registered as : __userdata_query ?type?exist? id.
122	aw0a	1	*/
123
124			extern int Asc_UserDataPrintLibrary(ClientData cdata, Tcl_Interp *interp,
125	jds	54	int argc, CONST84 char *argv[]);
126			/**<
127	aw0a	1	* This command will return a formatted string of containing the contents
128			* of the user_data library. The string will be a proper list with list
129	jds	54	* elements of the form {id type}.<br><br>
130			*
131			* Registered as : __userdata_print
132	aw0a	1	*/
133
134			/*
135			* It is hoped to register two functions of the form.
136			* __userdata__apply
137			* ?to_inst_info?to_list_info?to_real_info?to_probe_info?
138			* id funcname.
139			*
140			* where: id is the id of a user data stored in the user data library.
141			* funcname is the id of a function possibly also stored in
142			* the user data library, or maybe the external function library.
143			* that will operate over the different user data types stored in
144			* in the userdata library.
145			*/
146	jds	54
147	johnpye	67	#endif /* ASCTK_USERPROC_H */
148	jds	54