00001 /* 00002 COSTA: Problem solving environment for data assimilation 00003 Copyright (C) 2005 Nils van Velzen 00004 00005 This library is free software; you can redistribute it and/or 00006 modify it under the terms of the GNU Lesser General Public 00007 License as published by the Free Software Foundation; either 00008 version 2.1 of the License, or (at your option) any later version. 00009 00010 This library is distributed in the hope that it will be useful, 00011 but WITHOUT ANY WARRANTY; without even the implied warranty of 00012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00013 Lesser General Public License for more details. 00014 00015 You should have received a copy of the GNU Lesser General Public 00016 License along with this library; if not, write to the Free Software 00017 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00018 */ 00019 00020 /** 00021 \file cta_usr_obs_desc.h 00022 00023 \brief In this file a description is given of the interface of user observation descriptor functions. 00024 When creating your own user observation descriptor class use the following as template. 00025 00026 The CTA_Usr_ObsDescr to which is being referred in this template can be substituted by your own user observation descriptor object. 00027 00028 <b>Step 1</b>: for creating your own user model class call the function CTA_Model_DefineClass(). 00029 00030 Example: 00031 00032 \code 00033 typedef CTA_Handle CTA_ObsDescrClass; 00034 00035 CTA_Func h_func[CTA_OBSDESCR_NUMFUNC]; 00036 CTA_ObsDescrClass my_own_obsdescr_class; 00037 00038 ierr=CTA_Func_Create(" ",&usr_obsdescr_create_size, hintf, &h_func[CTA_OBSDESCR_CREATE_SIZE]); 00039 //...for all implementation functions... 00040 00041 CTA_ObsDescr_DefineClass("classname", h_func, &my_own_obsdescr_class);\endcode 00042 00043 Making a new observation descriptor class involves the implementation of the following functions: 00044 00045 CTA_OBSDESCR_CREATE_SIZE \n 00046 CTA_OBSDESCR_CREATE_INIT \n 00047 CTA_OBSDESCR_FREE \n 00048 CTA_OBSDESCR_GET_PROPERTIES \n 00049 CTA_OBSDESCR_GET_KEYS \n 00050 CTA_OBSDESCR_COUNT_OBSERVATIONS \n 00051 CTA_OBSDESCR_COUNT_PROPERTIES \n 00052 CTA_OBSDESCR_EXPORT 00053 00054 For creating an implementation function see documentation of CTA_Func_Create(). 00055 00056 <b>Step 2</b>: to create an object of the newly defined observation descriptor class call CTA_ObsDescr_Create() in the 00057 same way as creating a CTA_ObsDescr object but with a different class handle, i.e. the user class handle from step 1 above. 00058 00059 Example: 00060 00061 \code 00062 Usr_ObsDescr usrobsdescr; //user observation descriptor object 00063 CTA_Handle userdata = CTA_NULL; 00064 CTA_ObsDescr_Create(my_own_obsdescr_class, &userdata, &usrobsdescr); 00065 \endcode 00066 \n 00067 <b>Note 1: </b> with object data is meant only the object itself including pointer(s) to its contents, but 00068 not the contents of the observation descriptor.\n\n 00069 */ 00070 00071 00072 00073 //#define CTA_OBSDESCR_CREATE_SIZE ( 1) 00074 /** \brief Implementation that forms part of the create process. 00075 * 00076 * Must give the memory size of a new object. 00077 * 00078 * Example: 00079 * \code 00080 //in header file: 00081 typedef struct { 00082 //your own user object data goes here... 00083 }USR_OBSDESCR; 00084 00085 //user implementation: 00086 void usr_obsdescr_create_size(...){ 00087 *memsize = sizeof(USR_OBSDESCR); 00088 *retval = CTA_OK; 00089 } 00090 \endcode 00091 * 00092 * \note At index CTA_OBSDESCR_CREATE_SIZE in the function list of the class descriptor. 00093 * 00094 * \param memsize O must receive the number of bytes which are necessary to store one 00095 user stochastic observer class, with a pointer to the contents (data), but without the 00096 contents themselves 00097 * \param retval O must receive return value of user implementation function 00098 00099 * \return no return value 00100 */ 00101 void usr_obsdescr_create_size(int *memsize, int *retval); 00102 00103 00104 //#define CTA_OBSDESCR_CREATE_INIT ( 2) 00105 /** \brief Implementation that forms part of the create process. 00106 * 00107 * The user observation descriptor object needs to be made ready for use. 00108 * 00109 * \note At index CTA_OBSDESCR_CREATE_INIT in the function list of the class descriptor. 00110 * 00111 * \param myhandle I Handle assigned by COSTA 00112 * \param objectdata I pointer to object data of user stochastic observer 00113 * \param userdata IO user data 00114 * \param retval O must receive return value of user implementation function 00115 * \return no return value 00116 */ 00117 void usr_obsdescr_create_init(CTA_ObsDescr myhandle, Usr_ObsDescr *objectdata, 00118 void *userdata, int *retval); 00119 00120 00121 //#define CTA_OBSDESCR_FREE ( 3) 00122 /** \brief Implementation for freeing the object data and associated resources. 00123 * 00124 * \note At index CTA_OBSDESCR_FREE in the function list of the class descriptor. 00125 * 00126 * \param objectdata I pointer to object data of user stochastic observer 00127 * \param retval O must receive return value of user implementation function 00128 * \return no return value 00129 */ 00130 void usr_obsdescr_free(Usr_ObsDescr *objectdata, int *retval); 00131 00132 00133 //#define CTA_OBSDESCR_GET_PROPERTIES ( 4) 00134 /** \brief Implementation for gettings properties associated with given key. 00135 * 00136 * \note At index CTA_OBSDESCR_GET_PROPERTIES in the function list of the class descriptor. 00137 * 00138 * \param objectdata I pointer to object data of user stochastic observer 00139 * \param key I description of property key 00140 * \param properties O vector that must receive properties associated with given key; must exist before calling 00141 * \param datatype I data type of elements in properties vector 00142 * \param retval O must receive return value of user implementation function 00143 * \return no return value 00144 */ 00145 void usr_obsdescr_get_properties(Usr_ObsDescr *objectdata, 00146 const char *key, CTA_Vector *properties, CTA_Datatype *datatype, int *retval); 00147 00148 00149 //#define CTA_OBSDESCR_GET_KEYS ( 5) 00150 /** \brief Implementation for getting all key names of user observation descriptor. 00151 * 00152 * \note At index CTA_OBSDESCR_GET_KEYS in the function list of the class descriptor. 00153 * 00154 * \param objectdata I pointer to object data of user stochastic observer 00155 * \param keys O handle vector that must receive key descriptions; must exist before calling 00156 * \param retval O must receive return value of user implementation function 00157 * \return no return value 00158 */ 00159 void usr_obsdescr_get_keys(Usr_ObsDescr *objectdata, CTA_Vector *keys, int *retval); 00160 00161 00162 //#define CTA_OBSDESCR_COUNT_OBSERVATIONS ( 6) 00163 /** \brief Implementation for counting number of observations. 00164 * 00165 * \note At index CTA_OBSDESCR_COUNT_OBSERVATIONS in the function list of the class descriptor. 00166 * 00167 * \param objectdata I pointer to object data of user stochastic observer 00168 * \param nobs O must receive number of observations 00169 * \param retval O must receive return value of user implementation function 00170 * \return no return value 00171 */ 00172 void usr_obsdescr_count_observations(Usr_ObsDescr *objectdata, int* nobs, int *retval); 00173 00174 00175 //#define CTA_OBSDESCR_COUNT_PROPERTIES ( 7) 00176 /** \brief Implementation for counting number of properties. 00177 * 00178 * \note At index CTA_OBSDESCR_COUNT_PROPERTIES in the function list of the class descriptor. 00179 * 00180 * \param objectdata I pointer to object data of user stochastic observer 00181 * \param nkeys O must receive number of property keys 00182 * \param retval O must receive return value of user implementation function 00183 * \return no return value 00184 */ 00185 void usr_obsdescr_count_properties(Usr_ObsDescr *objectdata, int* nkeys, int *retval); 00186 00187 00188 //#define CTA_OBSDESCR_EXPORT ( 8) 00189 /** \brief Implementation for exporting user observation descriptor. 00190 * 00191 * \note At index CTA_OBSDESCR_EXPORT in the function list of the class descriptor. 00192 * 00193 * \param objectdata I pointer to object data of user stochastic observer 00194 * \param userdata IO user data 00195 * \param retval O must receive return value of user implementation function 00196 * \return no return value 00197 */ 00198 void usr_obsdescr_export(Usr_ObsDescr *objectdata, void *userdata, int *retval); 00199 00200 00201 //#define CTA_OBSDESCR_SELECTION ( 9) 00202 /** \brief Create a new observation description that is subset of existing 00203 * observation description. 00204 * 00205 * \param objectdata I object data of observation description of the 00206 * initial observation description insntance 00207 * \param selection I selection criterion (subset of SQL) 00208 * \param reltab O Relation table specifying the relation between 00209 * the original and new observation description 00210 * component. Note no relation table is created when 00211 * reltab==CTA_NULL on enty 00212 * \param objectdata_out O new observation description created subset 00213 * \param retval O receives return value 00214 */ 00215 void usr_obsdescr_createsel(Usr_ObsDescr *descr, 00216 CTA_String *selection, CTA_RelTable reltab, 00217 CTA_ObsDescr myhandle_out, 00218 Usr_ObsDescr *descrout, int *retval); 00219 00220