JSOC_Documentation: proj/jpe/apps/soi

00001 /*
00002  *  soi_vds.h               $(DIST)/include/soi_vds.h
00003  *
00004  *   Based on code by Phil Scherrer for handling multivariant data
00005  *   and dataset names
00006  *
00007  *  Bugs: yes
00008  *
00009  *  Planned updates:
00010  *
00011  */
00012 
00013 #ifndef SOI_VDS_INCL 
00014 
00015 /****************************************************************************/
00016 /**************************  INCLUDE STATEMENTS  ****************************/
00017 /****************************************************************************/
00018 
00019 #ifndef SOI_VERSION_INCL
00020 #include "soi_version.h"
00021 #endif
00022 
00023 #include "soi_sds.h"
00024 #include "soi_NaN.h"
00025 #include "soi_key.h"
00026 #include "soi_str.h"
00027 #include "soi_at.h"
00028 
00029 /****************************************************************************/
00030 /****************************  DEFINE STATEMENTS  ***************************/
00031 /****************************************************************************/
00032 
00033 #define VDS_CADENCE (1)
00034 
00035 #define VDS_READ    (1)
00036 #define VDS_WRITE   (2)
00037 #define VDS_APPEND  (3)
00038 
00039 #define VDS_INFO    (1)
00040 #define VDS_DATA    (2)
00041 
00042 #define DEFAULT_PROTOCOL    "RDB.FITS"
00043 
00044 #define VDS_CONFORMANCE_VERSION "2003.11.18"
00045 
00046 /****************************************************************************/
00047 /*******************************  TYPEDEFS  *********************************/
00048 /****************************************************************************/
00049 
00050 typedef struct name_list {
00051   struct name_list *next;
00052   char      *name;
00053 } NAMELIST;
00054 
00055 /* add slicing info or keep the keylist around?  */
00056 typedef struct vds_description {
00057   char      *wd;            /* dataset directory name */
00058   char      *bn;            /* basename for filename building */
00059   char      *fmt;           /* format of record part of datafiles */
00060   char      *ov;            /* Full pathname of overview file */
00061   char      *info;          /* */
00062   char      *prog;          /* prog name or NULL if not dataset */
00063   char      *filename;      /* for single file or datacube */
00064   int        fsn;           /* requested first record */
00065   int        lsn;           /* requested last record */
00066   int        first_record;      /* actual first record */
00067   int        last_record;       /* actual last record */
00068   int        mode;          /* read write or ? append ? */
00069   int        vds_extern_type;   /* external data format */
00070   int        vds_intern_type;   /* internal data format */
00071   void      *vds_pointer;       /* for record info and fits records */
00072   SDS       *sds;           /* for data cube */
00073   int       state;          /* Flag for state of vds. */
00074   SDS       *global_attributes;
00075   int        nvars;
00076   NAMELIST  *var_names;
00077 } VDS;
00078 
00079 typedef int VDS_TYPE;
00080 
00081 
00082 /****************************************************************************/
00083 /*********************  GLOBAL & EXTERN DECLARATIONS  ***********************/
00084 /****************************************************************************/
00085 
00086 
00087 /* state flag to control known state of dataset. */
00088 
00089 enum state_types {
00090 VDS_EMPTY=0,    /* after vds_create */
00091 VDS_CLEAN,  /* after vds_opne or vds_new */
00092 VDS_CUBED,  /* after convert_to_cube but before use */
00093 VDS_USED,   /* after data inserted or selected */
00094         /* new state types here */
00095 VDS_NUM_STATES};
00096 
00097 /* index used to process different types of conforming datasets */
00098 
00099 enum conformance_types {
00100 VDS_NOT_CONFORMING, /* =0, must be first */
00101 VDS_TS,         /* time series */
00102 VDS_TS_EQ,      /* time series - equally spaced */
00103 VDS_TS_BLOCKED,     /* time series - blocked */
00104 VDS_L_NU,       /* l-nu diagram */
00105 VDS_MDICAL,     /* calibration */
00106 VDS_MISC,
00107 VDS_TS_EQ_TILE,     /* ts_eq but sn units not T_BLOCK */
00108             /* insert additional types here,
00109                            edit conformance_names accordingly */
00110 VDS_NUM_TYPES};     /* count of conformance types, must be last */
00111 
00112 
00113 /* descriptions of conforming datasets indexed by conformance type */
00114 /* vds attribute value for the key CONFORMS should be one of these names */
00115 
00116 extern char *conformance_names[VDS_NUM_TYPES];  /* definition in libvds.d */
00117 
00118 
00119 /* index which enumerates the way data and attributes are stored externally */
00120 
00121 enum protocol_types {
00122 VDS_NO_PROTOCOL,    /* =0, must be first */
00123 VDS_CDF,
00124 VDS_FITS,
00125 VDS_FITS_MERGE,
00126 VDS_FITS_TABLE,
00127 VDS_RDB,
00128 VDS_NUM_PROTOCOLS}; /* count of external protocol types, must be last */
00129 
00130 
00131 /* info arrays corresponding to protocol types used to determine protocols
00132    and generate names - definitions in libvds.d */
00133 
00134 extern char *protocol_names[VDS_NUM_PROTOCOLS];
00135 extern char *protocol_suffixes[VDS_NUM_PROTOCOLS];
00136 
00137 
00138 /* index which enumerates the way data and attributes are stored internally */
00139 /* use mutually exclusive index sets for external and internal protocols */
00140 
00141 enum internal_protocol_types {
00142 VDS_START_INTERNAL=VDS_NUM_PROTOCOLS,
00143 VDS_CDF_INTERNAL,
00144 VDS_FILE,
00145 VDS_CUBE,
00146 VDS_FILES,
00147 VDS_END_INTERNAL};
00148 
00149 #define VDS_NO_INTERNAL_PROTOCOL 0
00150 #define VDS_FIRST_INTERNAL_PROTOCOL VDS_START_INTERNAL+1
00151 #define VDS_NUM_INTERNAL_PROTOCOLS VDS_END_INTERNAL-VDS_START_INTERNAL
00152 
00153 /****************************************************************************/
00154 /****************************  MACRO DEFINITIONS  ***************************/
00155 /****************************************************************************/
00156 
00157 #define    VDS_QUIT(errcode) {soi_errno=errcode; return(NULL);}
00158 
00159 
00160 
00161 /****************************************************************************/
00162 /***************************  FUNCTION PROTOTYPES  **************************/
00163 /****************************************************************************/
00164 
00165 /* vds constructors */
00166 extern VDS *vds_open (KEY *keylist, char *root_key);
00167 extern VDS *vds_open_all (KEY *keylist, char *root_key);
00168 extern VDS *vds_new (KEY *keylist, char *root_key, int protocol);
00169 extern VDS *vds_create_std(KEY *keylist, char *root_key, int mode);
00170 extern VDS *vds_create(void);   /* create an empty VDS structure */
00171                         /*  vds destructors: vds_new.c  */
00172 extern int vds_close (VDS **vdsptrptr);
00173 extern int vds_flush_data (VDS *, int var);
00174 extern int vds_flush_data_rec (VDS *, int var, int rec);
00175 extern void vds_free(VDS **vdsptrptr);
00176 
00177 /* data insertion */
00178 extern int vds_insert_sds (VDS *vds, SDS *sds, int var_num);
00179 extern int vds_insert_sds_rec (VDS *vds, SDS *sds, int var_num, int rec_num);
00180 
00181 /* data selection */
00182 extern SDS *vds_select (VDS *vds, int var_number, int recStart, int recCount, 
00183                   int recInterval, int *indices, int *counts, int *intervals);
00184 
00185 extern SDS *vds_select_hdr (VDS *vds, int var_number, int rec_number);
00186 extern SDS *vds_select_rec(VDS *vds, int var_number, int rec_number);
00187 extern SDS *vds_select_drec(VDS *vds, int var_number, int rec_number);
00188 extern SDS *vds_select_frec(VDS *vds, int var_number, int rec_number);
00189 
00190 extern SDS *VDS_select_hdr (VDS *vds, int var_number, int rec_number);
00191 extern SDS *VDS_select_rec(VDS *vds, int var_number, int rec_number);
00192 extern SDS *VDS_select_drec(VDS *vds, int var_number, int rec_number);
00193 extern SDS *VDS_select_frec(VDS *vds, int var_number, int rec_number);
00194 
00195 extern SDS *vds_select_key_double(VDS *vds, int var, char *key);
00196 extern SDS *vds_select_vars (VDS *vds, int n_vars, int *var_numbers);
00197 
00198 /* data conversion */
00199 extern int vds_convert_to_cube (VDS *vdsptr, int nrecs);
00200 
00201 /* global attributes */
00202 extern int vds_conform_type(VDS *vds);
00203 extern int vds_protocol_type (VDS *vds, int which);
00204 
00205 extern int vds_check_info(VDS *vds);
00206 extern int vds_copy_conform_info(VDS *vdsout, VDS *vdsin);
00207 extern int vds_set_conform_info(VDS *vds, char *conforms, char *protocol,
00208     char *t_epoch, char *t_block, char *ext_info, char *series_type);
00209 
00210 extern char *vds_getkey_str(VDS *vds, char *key);
00211 extern char *VDS_getkey_str(VDS *vds, char *key);
00212 extern int vds_getkey_int(VDS *vds, char *key);
00213 extern double vds_ketkey_double(VDS *vds, char *key);
00214 extern TIME vds_getkey_time(VDS *vds, char *key);
00215 extern TIME vds_getkey_time_interval(VDS *vds, char *key);
00216 
00217 extern int vds_setkey_str(VDS *vds, char *key, char *val);
00218 extern int vds_setkey_int(VDS *vds, char *key, int val);
00219 extern int vds_setkey_double(VDS *vds, char *key, double val);
00220 extern int vds_setkey_time(VDS *vds, char *key, TIME val);
00221 extern int vds_setkey_time_interval(VDS *vds, char *key, TIME val);
00222 
00223 extern char *vds_getkey_rec_str(VDS *vds, int var, int rec, char *key);
00224 extern char *VDS_getkey_rec_str(VDS *vds, int var, int rec, char *key);
00225 extern int vds_getkey_rec_int(VDS *vds, int var, int rec, char *key);
00226 extern double vds_getkey_rec_double(VDS *vds, int var, int rec, char *key);
00227 extern TIME vds_getkey_rec_time(VDS *vds, int var, int rec, char *key);
00228 extern TIME vds_getkey_rec_time_interval(VDS *vds, int var, int rec, char *key);
00229 
00230 extern int vds_attribute_type(VDS *vds, char *key);
00231 extern int vds_set_attribute(VDS *vds, char *name, void *value, 
00232                  int attrtype, char *comment);
00233 extern int vds_remove_attribute(VDS *vds, char *name);
00234 extern int vds_copy_attribute(VDS *vdsout, VDS *vdsin, char *key);
00235 
00236 extern void *vds_search_attrvalue(VDS *vds, char *key);
00237 extern char *vds_search_attrvalue_str(VDS *vds, char *key);
00238 extern double vds_search_attrvalue_double(VDS *vds, char *key);
00239 
00240 extern int vds_check_record_file(char *filename, int conformance_type);
00241 extern int vds_check_records(AT *recinfo, int conformance_type);
00242 
00243 /* routines that set the structure  */
00244 extern int vds_set_last_record(VDS *vdsptr, int last_record);
00245 extern int vds_set_vds_ptr(VDS *vdsptr, void *vds_ptr);
00246 extern int vds_set_intern_ptr(VDS *vdsptr, void *intern_ptr);
00247 extern int vds_set_extern_type(VDS *vdsptr, int vds_extern_type);
00248 extern int vds_set_intern_type(VDS *vdsptr, int vds_intern_type);
00249 extern int vds_set_filename(VDS *vdsptr, char *filename);
00250 extern int vds_set_var_namelist(VDS *vdsptr, NAMELIST *var_names);
00251 
00252 /* routines that query the vds  */
00253 extern int vds_nrecs(VDS *vds);
00254 extern int vds_last_record(VDS *vds);
00255 
00256 extern int vds_extern_type(VDS *vds);
00257 extern int vds_intern_type(VDS *vds);
00258 extern void *vds_intern_ptr(VDS *vds);
00259 
00260 extern int vds_var_rank(VDS *vds, int var_number);
00261 extern int vds_var_dimn(VDS *vds, int var_number, int axis_number);
00262 extern int *vds_var_lengths(VDS *vds, int var_number);
00263 extern int vds_var_datatype(VDS *vds, int var_number);
00264 extern void *vds_var_fillvalue(VDS *vds, int var_number);
00265 extern void *vds_default_fillvalue(int datatype);
00266 
00267 extern char *vds_wd(VDS *vds);
00268 extern char *vds_get_info_filename(VDS *vds, int var);
00269 extern char *vds_get_data_filename (VDS *vds, int var);
00270 
00271 extern char *vds_title (VDS *vds);
00272 
00273 extern void DEBUGvds(VDS *vds, char *msg);
00274 
00275 /* variable routines  */
00276 extern int vds_nvars (VDS *vds);
00277 extern char *vds_var_name (VDS *vds, int var_number);
00278 extern int vds_add_var_name (VDS *vds, char *varname);
00279 extern int vds_var_number (VDS *vds, char *var_name);
00280 
00281 /* AXIS routines */
00282 extern AXIS *vds_axis (VDS *vds);
00283 extern int vds_promote_axis (VDS *vds);
00284 
00285                                  /*  vds_util.c  */
00286 extern VDS *vds_get_sn_range (KEY *params, char *name, int ds,
00287     int *fsn, int *lsn, int *dsn, int discontinuous);
00288 extern int vds_record_count (KEY *params, char *vds_name, int discontinuous,
00289     int *ds_count);
00290 
00291 #define SOI_VDS_INCL
00292 #endif
00293 
00294 /* Revision History
00295  *
00296  *  v 2.8  98.02.18 Rick Bogart declared obsolete versions of vds_close
00297  *  and vds_flush_data_rec for compatability; removed history prior to v 1
00298  *  v 4.3  99.06.10 R Bogart    added declarations from vds_util
00299  *  v 4.5  99.10.13 R Bogart    modified "
00300  *  v 4.8  01.07.27 R Bogart    removed declarations of unused old_vds*
00301  *  from v 2.8
00302  *  v 5.4  03.11.18 R Bogart    modified conformance version date to
00303  *  reflect tightened rules
00304  */
00305 
00306 /*
00307 $Id: soi_vds.h,v 1.1 2009/04/24 21:53:31 production Exp $
00308 $Source: /home/cvsuser/cvsroot/JSOC/proj/jpe/apps/soi_vds.h,v $
00309 $Author: production $
00310  * $Log: soi_vds.h,v $
00311  * Revision 1.1  2009/04/24 21:53:31  production
00312  * *** empty log message ***
00313  *
00314  * Revision 1.50  2003/11/18  23:15:08  rick
00315  * see above
00316  *
00317  * Revision 1.49  2001/08/28 00:10:15  rick
00318  * see above
00319  *
00320  * Revision 1.48  1999/12/14  00:30:53  rick
00321  * see above
00322  *
00323  * Revision 1.47  1999/07/21  22:31:26  rick
00324  * see above
00325  *
00326  * Revision 1.46  1999/01/20 00:48:57  kay
00327  * added functions vds_check_records and vds_check_record_file
00328  * to implement fix to SSTR 18
00329  *
00330  * Revision 1.45  1998/02/19  00:32:22  rick
00331  * see above
00332  *
00333  * Revision 1.44  1997/12/15  18:17:17  phil
00334  * added more vds_getkey_rec_XXX types
00335  *
00336  * Revision 1.43  1997/05/24  01:28:14  phil
00337  * added TS_EQ_TILE conforming type.
00338  *
00339  * Revision 1.42  1997/04/16  21:58:17  kehcheng
00340  * added #include <soi_version.h>
00341  *
00342  * Revision 1.41  1996/11/13  23:05:49  kay
00343  * recategorized function externs, added extern for DEBUGvds,
00344  * moved externs for GETKEY_str and getkey_time_interval to soi_key.h
00345  * moved externs for sds_getkey*, sds_setkey*, SDS_getkey_str, and DEBUGsds
00346  * to soi_sds.h
00347  *
00348  * Revision 1.40  1996/10/09  22:52:30  kay
00349  * mutually exclusive index sets for external and internal protocols
00350  *
00351  * Revision 1.39  1996/07/10  23:04:54  phil
00352  * added vds_flush_data_rec
00353  *
00354  * Revision 1.38  1996/06/03  20:46:28  phil
00355  * added vds_open_all
00356  *
00357  * Revision 1.37  1996/05/31  00:28:42  phil
00358  * *** empty log message ***
00359  *
00360  * Revision 1.36  1996/05/06  21:04:19  kay
00361  * added sds field to VDS structure and added extern for vds_flush_data
00362  *
00363  * Revision 1.35  1996/04/19  23:28:30  kay
00364  * redefined internal_protocol_types
00365  *
00366  *
00367  */