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_obsdescr.h 00022 \brief Interface description of the COSTA default observation descriptor component. For user implementation see cta_usr_obs_descr.h. 00023 00024 CTA_ObsDescr is used for describing observations. 00025 */ 00026 00027 #ifndef CTA_OBSDESCR_H 00028 #define CTA_OBSDESCR_H 00029 #include "cta_system.h" 00030 #include "cta_handles.h" 00031 #include "cta_datatypes.h" 00032 #include "cta_functions.h" 00033 #include "cta_string.h" 00034 #include "cta_vector.h" 00035 #include "cta_matrix.h" 00036 #include "cta_reltable.h" 00037 00038 /* Function Handle */ 00039 typedef CTA_Handle CTA_ObsDescr; 00040 typedef CTA_Handle CTA_ObsDescrClass; 00041 00042 #include "cta_sobs.h" 00043 00044 /* parameters for different functions */ 00045 #define I_CTA_OBSDESCR_CREATE_SIZE ( 1) 00046 #define I_CTA_OBSDESCR_CREATE_INIT ( 2) 00047 #define I_CTA_OBSDESCR_FREE ( 3) 00048 #define I_CTA_OBSDESCR_GET_PROPERTIES ( 4) 00049 #define I_CTA_OBSDESCR_GET_KEYS ( 5) 00050 #define I_CTA_OBSDESCR_COUNT_OBSERVATIONS ( 6) 00051 #define I_CTA_OBSDESCR_COUNT_PROPERTIES ( 7) 00052 #define I_CTA_OBSDESCR_EXPORT ( 8) 00053 #define I_CTA_OBSDESCR_SELECTION ( 9) 00054 #define I_CTA_OBSDESCR_NUMFUNC (10) 00055 00056 #ifdef __cplusplus 00057 extern "C" { 00058 #endif 00059 00060 /** \brief Create a new class (=implementation) of a COSTA observation description component. 00061 * 00062 * \param name I name of the new observation description class 00063 * \param h_func I COSTA function handles for functions that implement class, 00064 * missing functions must have value CTA_NULL 00065 * \param hobsdscrcl O receives handle of new observation description class 00066 * \return error status: CTA_OK if successful 00067 */ 00068 CTAEXPORT int CTA_ObsDescr_DefineClass(const char *name, 00069 const CTA_Func h_func[I_CTA_OBSDESCR_NUMFUNC], 00070 CTA_ObsDescrClass *hobsdscrcl); 00071 00072 00073 /** \brief Create a new observation description instance. 00074 * 00075 * \param hsobscl I class of new observation description 00076 * \param usrdat IO data of the stochastic observer for which 00077 * a descriptor is to be created 00078 * \param hobsdscr O receives handle of created observation description 00079 * object 00080 * \return error status: CTA_OK if successful 00081 */ 00082 CTAEXPORT int CTA_ObsDescr_Create( CTA_ObsDescrClass hsobscl, 00083 CTA_Handle usrdat, CTA_ObsDescr *hobsdscr); 00084 00085 /** \brief Create a new observation description that is subset of existing observation description. 00086 * 00087 * \param hobsdescr I the observation description to create a subset 00088 * from 00089 * \param selection I selection criterion (subset of SQL) 00090 * \param reltab O Relation table specifying the relation between 00091 * the original and new observation description 00092 * component. Note no relation table is created when 00093 * reltab==CTA_NULL on entry 00094 * \param hobsdescrout O the new COSTA-stochastic observer, empty before 00095 * calling, caller responsible for freeing after use 00096 * \return error status: CTA_OK if successful 00097 */ 00098 CTAEXPORT int CTA_ObsDescr_CreateSel( CTA_StochObs hobsdescr, CTA_String selection, 00099 CTA_RelTable reltab, CTA_StochObs *hobsdescrout); 00100 00101 /** \brief Create a new observation description that is subset of existing observation description. 00102 * All observations in the interval (t1,t2] (note t1 is not part 00103 * of the interval!) of the time span are selected. 00104 * 00105 * \param hobsdescr I the observation description to create a subset 00106 * from 00107 * \param timespan I time span over which selection has to be made 00108 * \param reltab O Relation table specifying the relation between 00109 * the original and new observation description 00110 * component. Note no relation table is created when 00111 * reltab==CTA_NULL on enty 00112 * \param hobsdescrout O the new COSTA-stochastic observer, empty before 00113 * calling, caller responsible for freeing after use 00114 * \return error status: CTA_OK if successful 00115 */ 00116 00117 CTAEXPORT int CTA_ObsDescr_CreateTimSel( CTA_ObsDescr hobsdescr, CTA_Time timespan, 00118 CTA_RelTable reltab, CTA_ObsDescr *hobsdescrout); 00119 00120 /** \brief Get properties/values that correspond to a given key. 00121 * 00122 * \param hobsdscr I handle of observation description 00123 * \param Key I key for which the value is asked 00124 * \param Properties IO COSTA-vector that is to receive the values 00125 * \param datatype I data type of elements in properties vector, must be the same as of queried properties 00126 * \return error status: CTA_OK if successful 00127 */ 00128 CTAEXPORT int CTA_ObsDescr_Get_ValueProperties( CTA_ObsDescr hobsdscr, const char* Key, 00129 CTA_Vector Properties, CTA_Datatype datatype); 00130 00131 /** \brief Get all keys names. 00132 * 00133 * \param hobsdscr I handle of observation description 00134 * \param Keys O receives all keys (COSTA-string vector); must exist before calling and be large enough 00135 * \return error status: CTA_OK if successful 00136 */ 00137 CTAEXPORT int CTA_ObsDescr_Get_PropertyKeys(CTA_ObsDescr hobsdscr, CTA_Vector Keys); 00138 00139 /** \brief Get number of properties/keys. 00140 * 00141 * \param hobsdscr I handle of observation description 00142 * \param nkeys O receives number of properties/keys 00143 * \return error status: CTA_OK if successful 00144 */ 00145 CTAEXPORT int CTA_ObsDescr_Property_Count( CTA_ObsDescr hobsdscr, int *nkeys); 00146 00147 /** \brief Get number of observations. 00148 * 00149 * \param hobsdscr I handle of observation description 00150 * \param nobs O receives the number of observations 00151 * \return error status: CTA_OK if successful 00152 */ 00153 CTAEXPORT int CTA_ObsDescr_Observation_Count( CTA_ObsDescr hobsdscr, int *nobs); 00154 00155 /** \brief Export observation description. 00156 * 00157 * The default observation description CTA_DEFAULT_OBSDESC supports exporting to:\n 00158 * TODO 00159 * 00160 * \param hdescr I handle of observation description 00161 * \param usrdat IO export configuration/medium 00162 * \return error status: CTA_OK if successful 00163 */ 00164 CTAEXPORT int CTA_ObsDescr_Export(CTA_ObsDescr hdescr, CTA_Handle usrdat); 00165 00166 /** \brief Free observation description object. 00167 * 00168 * \param hobsdscr IO handle of observation description, replaced by CTA_NULL on return. 00169 * \return error status: CTA_OK if successful 00170 */ 00171 CTAEXPORT int CTA_ObsDescr_Free( 00172 CTA_ObsDescr *hobsdscr /* Handle of observation description */ 00173 ); 00174 00175 #ifdef __cplusplus 00176 } 00177 #endif 00178 00179 #endif
1.6.1