MSG_pubdefs.h File Reference

Public include file defining the interface to the MSG facility. More...

#include <PBS/TASK.h>
#include <PBS/WCT.h>
#include <MDB/MDB_pubdefs.h>
#include <MSG/MSG_macdefs.h>

Classes
struct	_MSG_InitPrm
	Structure to hold parameters needed by MSG initialization routine. More...
struct	_MSG_Message
	Structure to hold an instance of a message. More...
struct	_MSG_Counts
	Structure for instrumentation counts. More...
Defines
#define	MSG_K_FMTBITS   ( 2 )
	N-bits needed to type a substitution.
#define	MSG_M_FMTBITS   ( ( 1 << MSG_K_FMTBITS ) - 1 )
	Mask for above.
#define	MSG_L_FMTMAX   ( 32 / MSG_K_FMTBITS )
	Maximum number of substitutions.
#define	MSG_K_FMTSTRING   ( 0 )
	Conversion type pointer to string.
#define	MSG_K_FMT4BINT   ( 1 )
	Conversion type 4-byte integer.
#define	MSG_K_FMT8BINT   ( 2 )
	Conversion type 8-byte integer.
#define	MSG_K_FMTDOUBLE   ( 3 )
	Conversion type double (any float).
#define	MSG_L_FMTLENGTH   ( 256 )
	Maximum length of a formatting string.
Typedefs
typedef struct _MSG_OutputRtn	MSG_OutputRtn
	Typedef for struct _MSG_OutputRtn.
typedef enum _MSG_Level	MSG_Level
	Typedef for enum _MSG_Level.
typedef enum _MSG_OutputModes	MSG_OutputModes
	Typedef for enum _MSG_OutputModes.
typedef struct _MSG_InitPrm	MSG_InitPrm
	Typedef for struct _MSG_InitPrm.
typedef struct _MSG_Message	MSG_Message
	Typedef for struct _MSG_Message.
typedef struct _MSG_Counts	MSG_Counts
	Typedef for struct _MSG_Counts.
typedef void	MSG_cb_OutputRtn (MSG_OutputModes mode, void *prm, const MSG_Message *msg)
	Signature for a MSG processing callback routine.
Enumerations
enum	_MSG_Level {   MSG_LVL_SUCCESS = 0,   MSG_LVL_INFORMATION = 1,   MSG_LVL_WARNING = 2,   MSG_LVL_ERROR = 3 }
	Enumerate message severity levels. More...
enum	_MSG_OutputModes {   MSG_OUT_INIT = 0,   MSG_OUT_NORMAL = 1,   MSG_OUT_EXIT = 2 }
	Enumeration of modes in which output processors can be called. More...
Functions
unsigned int	MSG_attachOutputRtn (MSG_OutputRtn **handle, MSG_cb_OutputRtn *rtn, void *prm)
	Attach a message output callback routine.
unsigned int	MSG_configure (void)
	Configure and start the MSG task.
unsigned int	MSG_countsSinceReset (MSG_Counts *cnt, unsigned int rst)
	Return instrumentation counts since last reset.
unsigned int	MSG_countsSinceStart (MSG_Counts *cnt)
	Return instrumentation counts since message task started.
unsigned int	MSG_detachOutputRtn (MSG_OutputRtn *handle)
	Detach a message callback routine.
unsigned int	MSG_initialize (const MSG_InitPrm *prm)
	Take message system from state MSG_S_UNINITIALIZED to state MSG_S_INITIALIZED.
MSG_Level	MSG_getLevel (void)
	Get the current reporting level.
MSG_Level	MSG_getLevel4Task (void **tbd)
	No meaning in the single-threaded context ... call is ignored.
const char *	MSG_getTask (void)
	Return pointer to task name.
unsigned short	MSG_getTrace (void)
	Get the current trace buffer number.
void	MSG_setCPU (unsigned int cpu)
	Set the CPU identifier word.
MSG_Level	MSG_setLevel (MSG_Level level)
	Set the current reporting level.
MSG_Level	MSG_setLevel4Task (void **tbd, MSG_Level level)
	No meaning in the single-threaded context ... call is ignored.
unsigned int	MSG_setTask (const char *task)
	Set the task name.
unsigned short	MSG_setTrace (unsigned short trace)
	Set the current trace buffer number.
unsigned int	MSG_shutdown (void)
	Take message system from state MSG_S_INITIALIZED to state MSG_S_UNINITIALIZED.
unsigned int	MSG_startTask (const TASK_attr *attr)
	Take message system from state MSG_S_INITIALIZED to state MSG_S_STARTED.
unsigned int	MSG_stopTask (void)
	Take message system from state MSG_S_STARTED to state MSG_S_INITIALIZED.

---

Detailed Description

Public include file defining the interface to the MSG facility.

CVS $Id: MSG_pubdefs.h,v 1.17 2011/03/25 01:05:52 apw Exp $

Author:

A.P.Waite

---

Enumeration Type Documentation

enum _MSG_Level

Enumerate message severity levels.

Messages can have one of four severity levels defined by the creator of the message. The names are (I hope) self explanatory.

Enumerator:

MSG_LVL_SUCCESS	Success
MSG_LVL_INFORMATION	Information
MSG_LVL_WARNING	Warning
MSG_LVL_ERROR	Error

enum _MSG_OutputModes

Enumeration of modes in which output processors can be called.

Output processors can be called in one of three modes. Note that the pointer to the message structure is only valid during a call in mode MSG_OUT_NORMAL.

Enumerator:

MSG_OUT_INIT	Initialization call
MSG_OUT_NORMAL	Regular output call
MSG_OUT_EXIT	Exit call

---

Function Documentation

unsigned int MSG_attachOutputRtn	(	MSG_OutputRtn **	handle,
		MSG_cb_OutputRtn *	rtn,
		void *	prm
	)

Attach a message output callback routine.

Parameters:

	handle	(out) Handle for identifying the callback (used to detach)
	rtn	(in) Routine entry point
	prm	(in) Routine parameter

Return values:

	MSG_SUCCESS	Success
	MSG_BADSTATE	Cannot attach output processors in the current MSG state
	MSG_ALOCFAIL	Cannot allocate memory for the output routine description

MSG_attachOutputRtn() attaches a message output processing routine. Each routine attached is called once when the message system is starting, once per call to MSG_report(), and once when the message system is stopping.

In the single-threaded version of MSG, the attached routines are called directly by the MSG_report() routine. In the multi-threaded version of MSG the routines are called by the message processing task.

Output processing routines may only be attached/detached when the MSG system is in state MSG_S_INITIALIZED. This is true:

• After a (successful) call to MSG_initialize() but before a call to MSG_startTask()
• After a (successful) run-down of the MSG system initiated by a call to MSG_stopTask() but before the next call to either MSG_startTask() or MSG_shutdown().

References MSG_mcb, MSG_MX_LOCK, MSG_MX_UNLOCK, MSG_S_INITIALIZED, _MSG_Control::mtx, _MSG_Control::out, and _MSG_Control::state.

unsigned int MSG_configure

(

void

)

Configure and start the MSG task.

Return values:

	MSG_ALOCFAIL	Fixed packet allocator (FPA) buffer allocation failed
	MSG_BADSTATE	Cannot initialize in the current MSG state
	MSG_CFGNTFND	Configuration database not found
	MSG_FINDFAIL	Cannot look up up alternate messages in database
	MSG_FORKFAIL	FORK initialization failed
	MSG_FPAGFAIL	Fixed packet allocator get failed during task start
	MSG_FPAIFAIL	Fixed packet allocator (FPA) initialization failed
	MSG_MUALOCFL	Cannot allocate a mutex
	MSG_PKT2FEW	Packet count parameter too small
	MSG_PKT2SMAL	Packet length parameter too small
	MSG_SUCCESS	Success

MSG_configure() configures MSG. It reads configuration database files to perform the MSG_initialize(), MSG_attachOutputRtn() and MSG_startTask() functions. If the configuration databases can't be found, MSG will still do its best to start up a message task based on an internal default configuration.

References MSG_initialize(), MSG_setCPU(), MSG_startTask(), _MSG_InitPrm::pkt_cnt, and _MSG_InitPrm::pkt_len.

unsigned int MSG_countsSinceReset	(	MSG_Counts *	cnt,
		unsigned int	rst
	)

Return instrumentation counts since last reset.

Parameters:

	cnt	MSG_Counts block into which to put the results
	rst	Reset flag (0 => don't reset, otherwise reset)

Return values:

	MSG_BADSTATE	Message system not initialized
	MSG_SUCCESS	Success

MSG_countsSinceReset() returns an instrumentation block giving (bread and butter case), message counts and high and low water marks for packet usage since the last reset. This makes sense while the message task is running. The following table gives details of what's returned when the message task is not running.

MSG state	MSG task has run at least once	Return code	Contents of instrumentation block
MSG_S_UNINITIALIZED	n/a	MSG_BADSTATE	All zero
MSG_S_INITIALIZED	no	MSG_SUCCESS	Fake statistics for a zero length run of the MSG task
MSG_S_INITIALIZED	yes	MSG_SUCCESS	Statistics from most recent reset to time MSG task stopped

References countsSince().

unsigned int MSG_countsSinceStart

(

MSG_Counts *

cnt

)

Return instrumentation counts since message task started.

Parameters:

cnt

MSG_Counts block into which to put the results

Return values:

	MSG_BADSTATE	Message system not initialized
	MSG_SUCCESS	Success

MSG_countsSinceStart() returns an instrumentation block giving (bread and butter case), message counts and high and low water marks for packet usage since the message task was started. This makes sense while the message task is running. The following table gives details of what's returned when the message task is not running.

MSG state	MSG task has run at least once	Return code	Contents of instrumentation block
MSG_S_UNINITIALIZED	n/a	MSG_BADSTATE	All zero
MSG_S_INITIALIZED	no	MSG_SUCCESS	Fake statistics for a zero length run of the MSG task
MSG_S_INITIALIZED	yes	MSG_SUCCESS	Statistics for the most recent run of the MSG task

References countsSince().

unsigned int MSG_detachOutputRtn

(

MSG_OutputRtn *

handle

)

Detach a message callback routine.

Parameters:

handle

(in) Handle for identifying the callback (from attach call)

Return values:

	MSG_SUCCESS	Success
	MSG_BADSTATE	Cannot detach output processors in the current MSG state
	MSG_OUTNTFND	Cannot find this output processor on the list

MSG_detachOutputRtn() detaches an message output processing routine.

Output processing routines may only be attached/detached when the MSG system is in state MSG_S_INITIALIZED. This is true

• After a (successful) call to MSG_initialize() but before a call to MSG_startTask()
• After a (successful) run-down of the MSG system initiated by a call to MSG_stopTask() but before the next call to either MSG_startTask() or MSG_shutdown().

References MSG_mcb, MSG_MX_LOCK, MSG_MX_UNLOCK, MSG_S_INITIALIZED, _MSG_Control::mtx, _MSG_OutputRtn::next, _MSG_Control::out, and _MSG_Control::state.

MSG_Level MSG_getLevel

(

void

)

Get the current reporting level.

Returns:

The severity level for reporting

MSG_getLevel() returns the level at which messages are reported. Messages whose severity is greater than or equal to the level set are reported.

References _MSG_TaskOption::level.

Referenced by MSG_reportInternal().

MSG_Level MSG_getLevel4Task

(

void **

tbd

)

No meaning in the single-threaded context ... call is ignored.

Parameters:

tbd

(in) Pointer to arbitrary task's TBD block

Returns:

The reporting level for the only existing task/thread

MSG_getLevel4Task() is meaningless in the single-threaded context and is only provided to provide compatibility between the single-threaded and multi-threaded modules.

References _MSG_TaskOption::level.

const char * MSG_getTask

(

void

)

Return pointer to task name.

Returns:

Pointer to the string containing the task name

MSG_getTask() returns a pointer to the task name. This is the host side version where the task name is an arbitrary string under user control.

Referenced by MSG_outputScan(), and MSG_reportInternal().

unsigned short MSG_getTrace

(

void

)

Get the current trace buffer number.

Returns:

The trace buffer number for reporting

MSG_getTrace() returns the trace buffer number currently in effect. This is a 16-bit number associated with a message. All messages record the current value of the trace buffer number. This is a simple mechanism to group messages.

References _MSG_TaskOption::trace.

Referenced by MSG_outputScan(), and MSG_reportInternal().

unsigned int MSG_initialize

(

const MSG_InitPrm *

prm

)

Take message system from state MSG_S_UNINITIALIZED to state MSG_S_INITIALIZED.

Parameters:

prm

(in) Parameter block contining initialization information (note 1)

Note:

1. If prm is NULL, MSG_initialize() will provide a default (currently 32 message packets of 256 bytes each). If prm is not NULL, the caller need not make the storage for the MSG_InitPrm structure persistent.

Return values:

	MSG_ALOCFAIL	Fixed packet allocator (FPA) buffer allocation failed
	MSG_BADSTATE	Cannot initialize in the current MSG state
	MSG_FINDFAIL	Cannot look up up alternate messages in database
	MSG_FPAIFAIL	Fixed packet allocator (FPA) initialization failed
	MSG_MUALOCFL	Cannot allocate a mutex
	MSG_PKT2FEW	Packet count parameter too small
	MSG_PKT2SMAL	Packet length parameter too small
	MSG_SUCCESS	Success

MSG_initialize() initializes the message system according to the parameters provided in the parameterization block.

References _MSG_Control::acb, _MSG_Counts::beg, _MSG_Control::beg, _MSG_AltMessage::code, _MSG_Control::cpu, _MSG_Counts::drop, _MSG_Control::drp, _MSG_Counts::end, _MSG_Control::end, _MSG_Control::fcb, _MSG_AltMessage::fdb, _MSG_Control::fqi, _MSG_Counts::hwm, _MSG_Counts::lwm, _MSG_Counts::max, _MSG_AltMessage::mdb, _MSG_Control::mem, MSG_alt, MSG_L_ALTERNATE, MSG_MX_LOCK, MSG_MX_UNLOCK, MSG_P_RESERVED, MSG_reportInternal(), MSG_RW_DECLARE, MSG_S_INITIALIZED, MSG_S_UNINITIALIZED, _MSG_Control::mtx, _MSG_Control::now, _MSG_Control::out, _MSG_Control::pad, _MSG_Control::pkt_cnt, _MSG_InitPrm::pkt_cnt, _MSG_Control::pkt_len, _MSG_InitPrm::pkt_len, _MSG_Control::reset, _MSG_Counts::run, _MSG_Control::rwi, _MSG_Control::save, _MSG_Counts::sent, _MSG_Control::start, and _MSG_Control::state.

Referenced by MSG_configure().

void MSG_setCPU

(

unsigned int

cpu

)

Set the CPU identifier word.

Parameters:

cpu

(in) CPU identifier

MSG can report messages complete with task and routine name information. The one piece of information that MSG cannot autogenerate is some kind of "CPU identity". Instead, MSG provides one four byte unsigned int location under user control. It's up to the user to devise a method of CPU identification, then tell MSG what that identity is via a call to this routine. MSG never uses this information, simply transmits it through to the message output routine(s).

References _MSG_Control::cpu.

Referenced by MSG_configure().

MSG_Level MSG_setLevel

(

MSG_Level

newval

)

Set the current reporting level.

Parameters:

newval

(in) Reporting level to be set

Returns:

Reporting level prior to the call

MSG_setLevel() sets the level at which messages are reported. A message whose severity is greater than or equal to the level set is reported. The routine returns the reporting level prior to the call (to allow simple reversion).

References _MSG_TaskOption::level, MSG_LVL_ERROR, and MSG_LVL_SUCCESS.

MSG_Level MSG_setLevel4Task	(	void **	tbd,
		MSG_Level	newval
	)

No meaning in the single-threaded context ... call is ignored.

Parameters:

	tbd	(in) Pointer to arbitrary task's TBD block
	newval	(in) Reporting level to be set

Returns:

The reporting level for the only existing task/thread

MSG_setLevel4Task() is meaningless in the single-threaded context and is only provided to provide compatibility between the single-threaded and multi-threaded modules.

References _MSG_TaskOption::level.

unsigned int MSG_setTask

(

const char *

task

)

Set the task name.

Parameters:

task

(in) Pointer to task name

Return values:

	MSG_ALOCFAIL	Could not allocate storage for task name string
	MSG_TNM2LONG	Task name too long
	MSG_SUCCESS	Success

MSG_setTask() sets a task name. This is only valid in the single-threaded environment where the task name is an arbitrary string under user control.

References MSG_L_TSKNAME.

unsigned short MSG_setTrace

(

unsigned short

newval

)

Set the current trace buffer number.

Parameters:

newval

(in) Trace buffer number to set

Returns:

The trace buffer prior to the change

MSG_setTrace() sets the trace buffer number currently in effect. This is a 16-bit number associated with a message. All messages record the current value of the trace buffer number. This is a simple mechanism to group messages. The routine returns the trace buffer in effect prior to the call to make reversion simple.

References _MSG_TaskOption::trace.

unsigned int MSG_shutdown

(

void

)

Take message system from state MSG_S_INITIALIZED to state MSG_S_UNINITIALIZED.

Return values:

	MSG_BADSTATE	Cannot shut down in the current MSG state
	MSG_SUCCESS	Success

MSG_shutdown() detaches all attached output processors and frees all resources associated with the message system.

References _MSG_Control::acb, _MSG_Control::fcb, _MSG_Control::mem, MSG_MX_LOCK, MSG_MX_UNLOCK, MSG_S_INITIALIZED, MSG_S_UNINITIALIZED, _MSG_Control::mtx, _MSG_OutputRtn::next, _MSG_Control::out, _MSG_Control::save, and _MSG_Control::state.

unsigned int MSG_startTask

(

const TASK_attr *

attr

)

Take message system from state MSG_S_INITIALIZED to state MSG_S_STARTED.

Parameters:

attr

(in) Task attributes block containing task start-up information (note 1)

Note:

1. If attr is NULL, MSG_startTask() will provide a default. If attr is not NULL, the caller need not make the storage for the TASK_attr structure persistent.

Return values:

	MSG_BADSTATE	Cannot start in the current MSG state
	MSG_FORKFAIL	FORK initialization failed
	MSG_FPAGFAIL	Fixed packet allocator get failed during task start
	MSG_SUCCESS	Success

In multi-threaded mode, MSG_startTask() forks a task (with the attributes defined in the task attributes block passed into this routine) to receive and process messages.

In single-threaded mode, MSG_startTask() does not fork a task, and all message processing is done inline with the MSG_report() call. The task attributes block is ignored.

In both modes (and before the task fork in multi-threaded mode), MSG_startTask() calls each of the output processing routines in turn with a flag to indicate an inialization call.

References _MSG_Control::acb, _MSG_Control::beg, _MSG_Control::end, _MSG_Control::fcb, MSG_MX_LOCK, MSG_MX_UNLOCK, MSG_OUT_EXIT, MSG_OUT_INIT, MSG_outputScan(), MSG_P_RESERVED, MSG_S_INITIALIZED, MSG_S_STARTED, _MSG_Control::mtx, _MSG_OutputRtn::next, _MSG_Control::out, _MSG_OutputRtn::prm, _MSG_OutputRtn::rtn, _MSG_Control::save, and _MSG_Control::state.

Referenced by MSG_configure().

unsigned int MSG_stopTask

(

void

)

Take message system from state MSG_S_STARTED to state MSG_S_INITIALIZED.

Return values:

	MSG_BADSTATE	Cannot stop in the current MSG state
	MSG_SUCCESS	Success

In multi-threaded mode, MSG_stopTask() runs down the task forked in MSG_startTask() and releases the resources associated with it.

In single-threaded mode, there is no forked task to run down.

In both modes (and after the forked task has run down in multi-threaded mode), MSG_stopTask() calls each of the output processing routines in turn with a flag to indicate a cleanup call.

References _MSG_Control::acb, _MSG_Control::beg, _MSG_Counts::end, _MSG_Control::end, _MSG_Control::fcb, _MSG_Control::fqi, MSG_MX_LOCK, MSG_MX_UNLOCK, MSG_OUT_EXIT, MSG_S_INITIALIZED, MSG_S_STARTED, MSG_S_STOPPING, _MSG_Control::mtx, _MSG_OutputRtn::next, _MSG_Control::now, _MSG_Control::out, _MSG_Control::pkt_cnt, _MSG_OutputRtn::prm, _MSG_Control::reset, _MSG_OutputRtn::rtn, _MSG_Counts::run, _MSG_Control::save, _MSG_Control::start, and _MSG_Control::state.