GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > MDB / V0-0-1

Constituent: mdb     Tag: mv2304


Interface   Data Structures   File List   Data Fields   Globals  

MDB_database.c File Reference

Provides the facilities to maintain and search the message "database". More...

#include <stdio.h>
#include <stdarg.h>
#include "PBS/WCT.h"
#include "MDB/MDB_pubdefs.h"

Include dependency graph for MDB_database.c:


Functions

unsigned int MSG_find (unsigned int code, const MSG_FacList **fdb, const MSG_MsgList **mdb)
 Return facility and message database entries corresponding to code.
void MSG_insertFacility (const MSG_FacList *fac)
 Insert a new facility into the store.
void MSG_removeFacility (const MSG_FacList *fac)
 Remove an existing facility from the store.
unsigned int MSG_report (unsigned int code, WCT_time hack, const char *rtn, unsigned int nprm,...)
 Process a message reporting request.
void MSG_setReportRtn (MSG_cb_ReportRtn *rtn)
 Set a new MSG_report() callback routine.

Variables

static MSG_cb_ReportRtnreportRtn
 Real routine used to report messages.
static const struct _MSG_FacListfacTable [1<< MSG_K_FACILITY]
 Table of pointers to facilities.

Detailed Description

Provides the facilities to maintain and search the message "database".

CVS $Id: MDB_database.c,v 1.2 2007/04/06 21:58:23 apw Exp $
Author:
A.P.Waite
MDB_database.c provides all the entry points to maintain and search an in-memory database of message definitions. This includes inserting facilities into the database, removing facilities from the database and finding message definitions in the database.

MDB_database.c also provides the dummy entry point MSG_report(). The name is to maintain backward compatibility with the previous implementation of this routine which used to appear in the MSG package proper. This version simply branches to a callback routine. When first initialized, it branches to a default, no-op routine (which simply returns the message code as is). When the MSG system is initialized, it overwrites the callback routine address so that the MSG_report() here branches to the proper message handling routine provided by MSG.


Function Documentation

unsigned int MSG_find unsigned int  code,
const MSG_FacList **  fdb,
const MSG_MsgList **  mdb
 

Return facility and message database entries corresponding to code.

Parameters:
code (in ) Message code
fdb (out) Facility descriptor
mdb (out) Message descriptor
Return values:
0 Database entry found
1 Database entry not found
MSG_find() searches for the facility descriptor and message descriptor corresponding to the message code provided as the first argument. If the code cannot be found, both descriptors are returned as NULL pointers (in addition to the return code indicating failure).

void MSG_insertFacility const MSG_FacList fac  ) 
 

Insert a new facility into the store.

Parameters:
fac (in) Pointer to the facility.
Warning:
This routine appears in the constituent interface only to support other packages that wish to automatically insert a message facility into the message facility list. This routine should never be called by application code.
MSG_insertFacility() inserts a facility into the facility search list. This is all very "clever". Message facilities take advantage of the fact that a routine can be declared __attribute__((constructor)) which results in it being run either before the main routine starts up (typical for single-threaded host applications) or immediately after a module is loaded (typical for the multi-threaded VxWorks environment). This technique is really provided for C++ static constructors, but there's no reason not to take advantage of it.

Thus every message facility source file contains a little stub routine declared constructor whose sole function is to call this routine with the address of the facility block.

void MSG_removeFacility const MSG_FacList fac  ) 
 

Remove an existing facility from the store.

Parameters:
fac (in) Pointer to the facility.
Warning:
This routine appears in the constituent interface only to support other packages that wish to automatically remove a message facility from the message facility list. This routine should never be called by application code.
MSG_removeFacility() removes a facility from the facility search list. This is all very "clever". Message facilities take advantage of the fact that a routine can be declared __attribute__((destructor)) which results in it being run either after the main routine completes (typical for single-threaded host applications) or a immediately before a module is unloaded (typical for the multi-threaded VxWorks environment). This technique is really provided for C++ static destructors, but there's no reason not to take advantage of it.

Thus every message facility source file contains a little stub routine declared destructor whose sole function is to call this routine with the address of the facility block.

unsigned int MSG_report unsigned int  code,
WCT_time  hack,
const char *  rtn,
unsigned int  nprm,
  ...
 

Process a message reporting request.

Parameters:
code (in) Message code to be reported
hack (in) Wall clock time to be recorded with the meessage (note 1)
rtn (in) Name of calling routine (note 2)
nprm (in) Number of parameters that follow
Note:
  1. If hack is zero, MSG_report() will supply the current wall clock time.
  2. String must be persistent. Recommended method for the caller to provide this argument: don't call MSG_report() directly, but use the _msg_report() macro, which will provide this argument automatically. If there is some necessity to call MSG_report() directly, please use the compiler provided __func__ macro to fill in the routine name.
Warning:
Under normal circumstances, no-one should be calling this routine directly. It's far more convenient (and usually more accurate) to use the _msg_report() macro provided by the MSG package. See note 2 above for the reason.
Return values:
code Reflection of the first input argument, probably with "reported" bit set
MSG_report() reports a message. This routine allocates a message packet and populates it with a block of standard information (timestamp, CPU, task name, etc.) and the variable information in the variadic arguments following nprm.

The packet is sent to an message task (in the multi-threaded case) where the message is formatted using the formatting string associated with the message code. The message task then calls all output processors in turn to do whatever it is they want to do with the information.

In the single-threaded case, the message processing occurs inline with the MSG_report() call.

void MSG_setReportRtn MSG_cb_ReportRtn rtn  ) 
 

Set a new MSG_report() callback routine.

Parameters:
rtn (in) Pointer to the message reporting routine


Variable Documentation

static struct _MSG_FacList * facTable[1<< MSG_K_FACILITY] [static]
 

Table of pointers to facilities.

Used in the first stage (facility) lookup of an error code. The facility number is used as an index into this table to find the facility description (a MSG_FacList structure), and the associated messages description (MSG_MsgList structures accessed from a root pointer in MSG_FacList).

static MSG_cb_ReportRtn * reportRtn [static]
 

Real routine used to report messages.

Pointer to a message reporting routine. When MDB is loaded, this is NULL, but MSG_report() can still be called "naturally" (the message code is simply returned). Once MSG is initialized, this static points to the real message reporting routine.


Generated on Sat Apr 7 05:03:59 2007 by  doxygen 1.4.4