ybos.h

Go to the documentation of this file.
00001 /********************************************************************\
00002 
00003   Name:         ybos.h
00004   Created by:   Pierre Amaudruz, Stefan Ritt
00005 
00006   Contents:     Declarations for ybos data format
00007 
00008   Revision history
00009   ------------------------------------------------------------------
00010   date        by    modification
00011   ---------   ---   ------------------------------------------------
00012 *  $Log: ybos.h,v $
00013 *  Revision 1.21  2003/04/14 12:59:51  midas
00014 *  Added 'compression' in channel settings
00015 *
00016 *  Revision 1.20  2003/04/07 23:55:55  olchansk
00017 *  add c++ wrappers
00018 *
00019 *  Revision 1.19  2002/09/19 17:50:34  pierre
00020 *  remove ^m
00021 *
00022 *  Revision 1.18  2002/09/18 16:37:27  pierre
00023 *  remove bk_list()
00024 *
00025 *  Revision 1.17  2002/06/08 06:06:27  pierre
00026 *  add DSP_UNK
00027 *
00028 *  Revision 1.16  2001/12/12 17:50:50  pierre
00029 *  EVID bank handling, 1.8.3-2 doc++
00030 *
00031 *  Revision 1.15  2001/07/20 20:36:19  pierre
00032 *  -Make ybk_close_... return bank size in bytes
00033 *
00034 *  Revision 1.14  2000/07/21 18:28:06  pierre
00035 *  - Include YBOS version >4.0 support by default, otherwise use in Makefile
00036 *    -DYBOS_VERSION_3_3 for MIDAS_PREF_FLAGS
00037 *
00038 *  Revision 1.13  2000/05/04 14:50:20  midas
00039 *  Return yb_tid_size[] via new function ybos_get_tid_size()
00040 *
00041 *  Revision 1.12  2000/04/26 19:11:45  pierre
00042 *  - Moved doc++ comments to ybos.c
00043 *
00044 *  Revision 1.11  2000/04/17 17:22:24  pierre
00045 *  - First round of doc++ comments
00046 *
00047 *  Revision 1.10  1999/12/20 08:38:25  midas
00048 *  Defined ybos_event_get
00049 *
00050 *  Revision 1.9  1999/09/30 22:52:16  pierre
00051 *  - arg of yb_any_bank_display
00052 *
00053 *  Revision 1.8  1999/06/23 09:59:22  midas
00054 *  Added D8_BKTYPE
00055 *
00056 *  Revision 1.7  1999/01/19 19:56:59  pierre
00057 *  - Fix prototype
00058 *  - Added YB_UNKNOWN_FORMAT
00059 *
00060 *  Revision 1.6  1999/01/18 17:34:36  pierre
00061 *  - cleanup definitions and structures for ybos
00062 *  - Correct prototype for ybos
00063 *
00064 \********************************************************************/
00065 
00066 /**dox***************************************************************/
00067 /** @file ybos.h
00068 The YBOS include file
00069 */
00070 
00071 /** @defgroup ybosincludecode The ybos.h & ybos.c
00072  */
00073 /** @defgroup ybosdefineh YBOS #define 
00074  */
00075 /** @defgroup ybosmacroh YBOS Macros 
00076  */
00077 /** @defgroup yboserrorh YBOS error code 
00078  */
00079 
00080 /**dox***************************************************************/
00081 /** @addtogroup ybosincludecode
00082  *  
00083  *  @{  */
00084 
00085 /**dox***************************************************************/
00086 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00087 
00088 #ifdef OS_WINNT
00089 #include <io.h>
00090 #include <time.h>
00091 #endif
00092 #include <fcntl.h>
00093 #include <stdlib.h>
00094 #include <stdio.h>
00095 #include <string.h>
00096 #include <sys/stat.h>
00097 #include <sys/types.h>
00098 
00099 #ifndef EXPRT
00100 #define EXPRT
00101 #endif
00102 
00103 /**dox***************************************************************/
00104 #endif                          /* DOXYGEN_SHOULD_SKIP_THIS */
00105 
00106 /**dox***************************************************************/
00107 /** @addtogroup ybosdefineh
00108  *  
00109  *  @{  */
00110 
00111 /********************************************************************/
00112 /**
00113 General parameters
00114 */
00115 #ifdef YBOS_VERSION_3_3
00116 #define YBOS_PHYREC_SIZE        8190  /**< I*4 */
00117 #else
00118 #define YBOS_PHYREC_SIZE        8192  /**< I*4 */
00119 #endif
00120 #define YBOS_HEADER_LENGTH      4
00121 #define YBOS_BUFFER_SIZE        3*(YBOS_PHYREC_SIZE<<2) + MAX_EVENT_SIZE + 128  /**< in BYTES */
00122 
00123 #define YB_BANKLIST_MAX        32     /**< maximum number of banks to be found 
00124                                          by the ybk_list() or bk_list() */
00125 #define YB_STRING_BANKLIST_MAX          YB_BANKLIST_MAX * 4
00126                                        /**< to be used for xbk_list() */
00127 
00128 /**dox***************************************************************/
00129 /** @} */// end of ybosdefineh
00130 
00131 /**dox***************************************************************/
00132 /** @addtogroup yboserrorh
00133  *  
00134  *  @{  */
00135 #define YB_SUCCESS               1     /**< Ok */
00136 #define YB_EVENT_NOT_SWAPPED     2     /**< Not swapped */
00137 #define YB_DONE                  2     /**< Operation complete */
00138 #define YB_WRONG_BANK_TYPE    -100     /**< Wrong bank type (see @ref YBOS_Bank_Types) */
00139 #define YB_BANK_NOT_FOUND     -101     /**< Bank not found */
00140 #define YB_SWAP_ERROR         -102     /**< Error swapping */
00141 #define YB_NOMORE_SLOT        -103     /**< No more space for fragment */
00142 #define YB_UNKNOWN_FORMAT     -104     /**< Unknown format (see @ref YBOS_format) */
00143 
00144 /**dox***************************************************************/
00145 /** @} */// end of yboserrorh
00146 
00147 /**dox***************************************************************/
00148 /** @addtogroup ybosdefineh
00149  *  
00150  *  @{  */
00151 
00152 /**
00153 record header content */
00154 #define H_BLOCK_SIZE   0     /**< YBOS */
00155 #define H_BLOCK_NUM    1     /**< YBOS */
00156 #define H_HEAD_LEN     2     /**< YBOS */
00157 #define H_START        3     /**< YBOS */
00158 
00159 /**
00160 Display parameters */
00161 #define D_RECORD       1     /**< YBOS */
00162 #define D_HEADER       2     /**< YBOS */
00163 #define D_EVTLEN       3     /**< YBOS */
00164 
00165 /**
00166 File fragmentation */
00167 #define YB_COMPLETE       1     /**< YBOS */
00168 #define YB_INCOMPLETE     2     /**< YBOS */
00169 #define YB_NO_RECOVER    -1     /**< YBOS */
00170 #define YB_NO_RUN         0     /**< YBOS */
00171 #define YB_ADD_RUN        1     /**< YBOS */
00172 
00173 /**
00174 Display mode options */
00175 #define DSP_RAW    1  /**< Display raw data */
00176 #define DSP_BANK   2  /**<Display data in bank format */
00177 
00178 /**
00179 Display format */
00180 #define DSP_UNK    0  /**< Display format unknown */
00181 #define DSP_DEC    1  /**< Display data in decimal format*/
00182 #define DSP_HEX    2  /**< Display data in headecimal format */
00183 #define DSP_ASC    3  /**< Display data in ASCII format */
00184 
00185 /**dox***************************************************************/
00186 /** @} */// end of ybosdefineh
00187 
00188 /**dox***************************************************************/
00189 /** @addtogroup ybosmacroh
00190  *  
00191  *  @{  */
00192 
00193 /*---- Macros for YBOS ------------------------*/
00194 /**
00195 word swap (I4=I21I22 -> I4=I22I21*/
00196 #define SWAP_D2WORD(_d2w) {\
00197   WORD _tmp2;                                    \
00198   _tmp2                 = *((WORD *)(_d2w));     \
00199   *((WORD *)(_d2w))     = *(((WORD *)(_d2w))+1); \
00200   *(((WORD *)(_d2w))+1) = _tmp2;                 \
00201 }
00202 
00203 /* the s for the following macros */
00204 #ifdef CHAOS_EVID_FMT
00205 extern chaos;
00206 #endif
00207 
00208 /********************************************************************/
00209 /**
00210 As soon as the Midas header is striped out from the event, the YBOS
00211 remaining  data has lost the event synchonization unless included by the
00212 user. It is therefore necessary to have a YBOS bank duplicating
00213 this information usually done in the FE by creating a
00214 "EVID" bank filled with the Midas info and other user information.
00215 
00216 Unfortunately the format of this EVID is flexible and I couldn't
00217 force user to use a default structure. For this reason, I'm
00218 introducing a preprocessor flag for selecting such format.
00219 
00220 Omitting the declaration of the pre-processor flag the EVID_TRINAT is taken by
00221 default see @ref AppendixD.
00222 
00223 Special macros are avaialbe to retrieve this information
00224 based on the EVID content and the type of EVID structure.
00225 
00226 The Macro parameter should point to the first data of the EVID bank.
00227 \code
00228   // check if EVID is present if so display its content 
00229   if ((status = ybk_find (pybos, "EVID", &bklen, &bktyp, (void *)&pybk)) == YB_SUCCESS)
00230   {
00231     pdata = (DWORD *)((YBOS_BANK_HEADER *)pybk + 1);
00232     pevent->event_id      = YBOS_EVID_EVENT_ID(pdata);
00233     pevent->trigger_mask  = YBOS_EVID_TRIGGER_MASK(pdata);
00234     pevent->serial_number = YBOS_EVID_SERIAL(pdata);
00235     pevent->time_stamp    = YBOS_EVID_TIME(pdata);
00236     pevent->data_size     = pybk->length;
00237   }
00238 \endcode
00239 
00240 The current type of EVID bank are:
00241 - [EVID_TRINAT] Specific for Trinat experiment.
00242 \code
00243   ybk_create((DWORD *)pevent, "EVID", I4_BKTYPE, (DWORD *)(&pbkdat));
00244   *((WORD *)pbkdat) = EVENT_ID(pevent);     ((WORD *)pbkdat)++;
00245   *((WORD *)pbkdat) = TRIGGER_MASK(pevent); ((WORD *)pbkdat)++;
00246   *(pbkdat)++ = SERIAL_NUMBER(pevent);
00247   *(pbkdat)++ = TIME_STAMP(pevent);
00248   *(pbkdat)++ = gbl_run_number;                // run number 
00249 \endcode
00250 - [EVID_TWIST] Specific to Twist Experiment (Triumf).
00251 \code
00252   ybk_create((DWORD *)pevent, "EVID", I4_BKTYPE, &pbkdat);
00253   *((WORD *)pbkdat) = EVENT_ID(pevent);     ((WORD *)pbkdat)++;
00254   *((WORD *)pbkdat) = TRIGGER_MASK(pevent); ((WORD *)pbkdat)++;
00255   *(pbkdat)++ = SERIAL_NUMBER(pevent);
00256   *(pbkdat)++ = TIME_STAMP(pevent);
00257   *(pbkdat)++ = gbl_run_number;                // run number 
00258   *(pbkdat)++ = *((DWORD *)frontend_name);     // frontend name 
00259   ybk_close((DWORD *)pevent, pbkdat);
00260 \endcode
00261 */
00262 #if (!defined (EVID_TRINAT) && !defined (EVID_CHAOS) && !defined (EVID_TWIST))
00263 #define EVID_TRINAT
00264 #endif
00265 
00266 #if defined(EVID_TRINAT)
00267 #define YBOS_EVID_EVENT_ID(e)      *((WORD *)(e)+1)
00268 #define YBOS_EVID_TRIGGER_MASK(e)  *((WORD *)(e)+0)
00269 #define YBOS_EVID_SERIAL(e)        *((DWORD *)(e)+1)
00270 #define YBOS_EVID_TIME(e)          *((DWORD *)(e)+2)
00271 #define YBOS_EVID_RUN_NUMBER(e)    *((DWORD *)(e)+3)
00272 #define YBOS_EVID_EVENT_NB(e)      *((DWORD *)(e)+1)
00273 #elif defined(EVID_CHAOS)
00274 #define YBOS_EVID_EVENT_ID(e)      *((WORD *)(e)+3)
00275 #define YBOS_EVID_TRIGGER_MASK(e)  *((WORD *)(e)+2)
00276 #define YBOS_EVID_SERIAL(e)        *((DWORD *)(e)+2)
00277 #define YBOS_EVID_TIME(e)          *((DWORD *)(e)+3)
00278 #define YBOS_EVID_RUN_NUMBER(e)    *((DWORD *)(e)+4)
00279 #define YBOS_EVID_EVENT_NB(e)      *((DWORD *)(e)+0)
00280 #elif defined(EVID_TWIST)
00281 #define YBOS_EVID_EVENT_ID(e)      *((WORD *)(e)+1)
00282 #define YBOS_EVID_TRIGGER_MASK(e)  *((WORD *)(e)+0)
00283 #define YBOS_EVID_SERIAL(e)        *((DWORD *)(e)+1)
00284 #define YBOS_EVID_TIME(e)          *((DWORD *)(e)+2)
00285 #define YBOS_EVID_RUN_NUMBER(e)    *((DWORD *)(e)+3)
00286 #define YBOS_EVID_EVENT_NB(e)      *((DWORD *)(e)+1)
00287 /* frontend name ignored */
00288 #endif
00289 
00290 /********************************************************************/
00291 /**
00292 pevt Evt# id/msk serial run# */
00293 #define YBOS_EVID_BANK(__a, __b, __c,   __d,   __e) {\
00294       DWORD * pbuf;\
00295       ybk_create(__a, "EVID", I4_BKTYPE, &pbuf);\
00296       *(pbuf)++ = (DWORD)__b;\
00297       *(pbuf)++ = (DWORD)__c;\
00298       *(pbuf)++ = (DWORD)__d;\
00299       *(pbuf)++ = (DWORD)ss_millitime();\
00300       *(pbuf)++ = (DWORD)__e;\
00301       ybk_close(__a, pbuf);\
00302         }
00303 
00304 /********************************************************************/
00305 /**
00306 pevt Evt# id/msk serial run# */
00307 #define MIDAS_EVID_BANK(__a, __b, __c,   __d,   __e) {\
00308       DWORD * pbuf;\
00309       bk_create(__a, "EVID", TID_DWORD, &pbuf);\
00310       *(pbuf)++ = (DWORD)__b;\
00311       *(pbuf)++ = (DWORD)__c;\
00312       *(pbuf)++ = (DWORD)__d;\
00313       *(pbuf)++ = (DWORD)ss_millitime();\
00314       *(pbuf)++ = (DWORD)__e;\
00315       bk_close(__a, pbuf);\
00316         }
00317 
00318 /**dox***************************************************************/
00319 /** @} */// end of ybosmacroh
00320 
00321 /**dox***************************************************************/
00322 /** @addtogroup ybosdefineh
00323  *  
00324  *  @{  */
00325 
00326 /*---- data structures for YBOS file format ------------------------*/
00327 /**
00328 YBOS Bank types */
00329 #define I2_BKTYPE       1  /**< Signed Integer 2 bytes */
00330 #define A1_BKTYPE       2  /**< ASCII 1 byte */
00331 #define I4_BKTYPE       3  /**< Signed Interger 4bytes */
00332 #define F4_BKTYPE       4  /**< Float 4 bytes */
00333 #define D8_BKTYPE       5  /**< Double 8 bytes */
00334 #define I1_BKTYPE       8  /**< Signed Integer 1 byte */
00335 #define MAX_BKTYPE      I1_BKTYPE+1 /**< delimiter */
00336 
00337 /**dox***************************************************************/
00338 /** @} */// end of ybosdefineh
00339 
00340 /**dox***************************************************************/
00341 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00342 
00343 /**
00344 YBOS logger channel ALL in 4BYTES! */
00345 typedef struct {
00346   DWORD *ptop;         /**< pointer to top of YBOS buffer */
00347   DWORD *pbuf;         /**< current data pointer for writing to buffer */
00348   DWORD *pwrt;         /**< current data pointer for writing to device */
00349   DWORD *pbot;         /**< bottom of the physical record */
00350   DWORD *pend;         /**< end of the buffer */
00351   DWORD reco;          /**< offset to first logical record 4BYTES */
00352   DWORD recn;          /**< current YBOS physical record number */
00353 } YBOS_INFO;
00354 
00355 /**
00356 YBOS Physical record header */
00357 typedef struct {
00358   DWORD rec_size;           /**< LPR Length of Physical Record (exclusive) */
00359   DWORD header_length;      /**< LPH Length of Physical Header (inclusive) */
00360   DWORD rec_num;            /**< NPR Physical Record Number (start 0) */
00361   DWORD offset;             /**< LRD Offset to 1st Logical Record 
00362                                    (=LPH for 1st Logical record) */
00363 } YBOS_PHYSREC_HEADER;
00364 
00365 /**
00366 Bank header */
00367 typedef struct {
00368   DWORD name;               /**< bank name 4ASCII */
00369   DWORD number;             /**< bank number (=1) */
00370   DWORD index;              /**< index within bank (=0) */
00371   DWORD length;             /**< bank length (I*4, exclusive ) */
00372   DWORD type;               /**< bank type refer to above */
00373 } YBOS_BANK_HEADER;
00374 
00375 /**
00376 YBOS FILE parameters */
00377 #define MAX_FILE_PATH    128
00378 #define MAX_FRAG_SIZE   2000    /* max event size for fragmented file (bytes) */
00379 #define MAX_YM_FILE        8    /* max concurrent file handling */
00380 #define NLINE              8    /* number of elements for display routine */
00381 
00382 /**
00383 YBOS control file header (private structure) */
00384 typedef struct {
00385   INT file_ID;
00386   INT size;
00387   INT fragment_size;
00388   INT total_fragment;
00389   INT current_fragment;
00390   INT current_read_byte;
00391   INT run_number;
00392   INT spare;
00393 } YM_CFILE;
00394 
00395 /**
00396 YBOS path file header (private structure) */
00397 typedef struct {
00398   char path[MAX_FILE_PATH];
00399 } YM_PFILE;
00400 
00401 /**
00402 YBOS file replay handler (for multiple file entries) */
00403 typedef struct {
00404   INT fHandle;
00405   INT file_ID;
00406   INT current_fragment;
00407   INT current_read_byte;
00408   char path[MAX_FILE_PATH];
00409 } R_YM_FILE;
00410 
00411 /*---- function declarations ---------------------------------------*/
00412 
00413 /* make functions callable from a C++ program */
00414 #ifdef __cplusplus
00415 extern "C" {
00416 #endif
00417 
00418   INT EXPRT yb_file_recompose(void *pevt, INT fmt, char *svpath,
00419                               INT file_mode);
00420   INT EXPRT feodb_file_dump(EQUIPMENT * eqp, char *eqpname, char *pevent,
00421                             INT run_number, char *path);
00422 
00423   void EXPRT yb_any_bank_display(void *pmbh, void *pbk, INT fmt,
00424                                  INT dsp_mode, INT dsp_fmt);
00425   void EXPRT yb_any_event_display(void *pevt, INT data_fmt, INT dsp_mode,
00426                                   INT dsp_fmt);
00427   INT EXPRT yb_any_all_info_display(INT what);
00428   INT EXPRT yb_any_physrec_display(INT data_fmt);
00429 
00430   INT EXPRT yb_any_physrec_skip(INT data_fmt, INT bl);
00431   INT EXPRT yb_any_physrec_get(INT data_fmt, void **prec, DWORD * psize);
00432   INT EXPRT yb_any_file_rclose(INT data_fmt);
00433   INT EXPRT yb_any_file_ropen(char *infile, INT data_fmt);
00434   INT EXPRT yb_any_file_wopen(INT type, INT data_fmt, char *filename,
00435                               INT * hDev);
00436   INT EXPRT yb_any_file_wclose(INT handle, INT type, INT data_fmt);
00437   INT EXPRT yb_any_log_write(INT handle, INT data_fmt, INT type,
00438                              void *prec, DWORD nbytes);
00439   INT EXPRT yb_any_event_swap(INT data_fmt, void *pevent);
00440   INT EXPRT yb_any_event_get(INT data_fmt, void **pevent, DWORD * psize);
00441 
00442 /* Bank manipulation */
00443   void EXPRT ybk_init(DWORD * pevent);
00444   void EXPRT ybk_create(DWORD * pevent, char *bkname, DWORD btype,
00445                         void *pbkdat);
00446   INT EXPRT ybk_close(DWORD * pevent, void *pbkdat);
00447   INT EXPRT ybk_size(DWORD * pevent);
00448   INT EXPRT ybk_list(DWORD * pevent, char *bklist);
00449   INT EXPRT ybk_locate(DWORD * pevent, char *bkname, void *pdata);
00450   INT EXPRT ybk_find(DWORD * pevent, char *bkname, DWORD * bklength,
00451                      DWORD * bktype, void **pbkdata);
00452   void EXPRT ybk_create_chaos(DWORD * pevent, char *bname, DWORD btype,
00453                               void *pbkdat);
00454   INT EXPRT ybk_iterate(DWORD * pevent, YBOS_BANK_HEADER ** pybkh,
00455                         void **pdata);
00456   INT EXPRT ybk_close_chaos(DWORD * pevent, DWORD btype, void *pbkdat);
00457 
00458 #ifdef INCLUDE_LOGGING
00459   INT EXPRT ybos_log_open(LOG_CHN * log_chn, INT run_number);
00460   INT EXPRT ybos_write(LOG_CHN * log_chn, EVENT_HEADER * pevent,
00461                        INT evt_size);
00462   INT EXPRT ybos_log_close(LOG_CHN * log_chn, INT run_number);
00463 #endif
00464 
00465   INT EXPRT ybos_event_get(DWORD ** plrl, DWORD * size);
00466   INT EXPRT ybos_get_tid_size(INT tid);
00467 
00468 #ifdef __cplusplus
00469 }
00470 #endif
00471 /*------------ END --------------------------------------------------------------*//**dox***************************************************************/
00472 #endif                          /* DOXYGEN_SHOULD_SKIP_THIS */
00473 /**dox***************************************************************//** @} */// end of ybosincludecode

Midas DOC Version 1.9.3 ---- PSI Stefan Ritt ----
Contributions: Pierre-Andre Amaudruz - Suzannah Daviel - Doxygen - Peter Green - Greg Hackman - Gertjan Hofman - Paul Knowles - Rudi Meier - Glenn Moloney - Dave Morris - Konstantin Olchanski - Renee Poutissou - Andreas Suter - Piotr Adam Zolnierczuk