|
CApplMessage class
|
Pipelines v1.6
|
A CApplMessage object provides
synchronised access to the console for output messages.
In a multi-stage, multi-pipeline
configuration; at any one time there may be more than one stage writing
messages to the console at the same time, and their output must be managed in
order to prevent output overlap. The CApplMessage class provides this
mechanism, by locking the console for output; it ensures that messages from
multiple output sources are written uninterrupted and in the correct sequence.
Multi-threaded applications are notoriously difficult to develop and especially
difficult to debug, however, by using CApplMessage for all your console output;
you can be sure that messages are delivered in the correct sequence. The
CApplMessage class provides; a common message prefix, message numbering,
current date and time stamp values and support for multi-line-message output.
The following class definition is
an edited version; it details only those members which are accessible and of
use to you. In addition; any examples that may be shown are only intended as a
demonstration of how certain functions might be used, they do not represent
best practice nor do they take into account the scope and de-allocation of
class objects.
#define _APPLMESSAGE_CASE_UPPER_ 0 // Translate output to uppercase.
#define _APPLMESSAGE_CASE_LOWER_ 1 // Translate output to lowercase.
#define _APPLMESSAGE_CASE_MIXED_ 2 // Default, no translation.
// Structure defining all CApplMessage fields. Fill in this structure and pass it
// to CApplMessage( struct SApplMsgContext ).
struct SApplMsgContext
{ bool s_bDate; // Date to be included in message prefix header (true/false).
bool s_bTime; // Time to be included in message prefix header (true/false).
DWORD s_dwCase; // Translate message. See _CAPPLMESSAGE_CASE_ definitions.
const char *s_pszPrefix; // The text that prefixes the message.
bool s_bPrefix; // Prefix should be included in the output (true/false).
bool s_bMultiline; // Message is part of a multiline block (true/false).
bool s_bNumbered; // Message number is included in the prefix header (true/false).
bool s_bConsole; // Reserved for the StageManager (must be set to: true).
bool s_Redirect; // Insist that the message goes to the console or file and..
// ..should not be redirected (true/false).
bool s_bFile; // Reserved for the StageManager (must be set to: false).
};
class CApplMessage
{ public:
CApplMessage( void );
CApplMessage( const char *a_pszPrefix );
CApplMessage( bool a_bDate,
bool a_bTime,
const char *a_pszPrefix = NULL );
CApplMessage( bool a_bDate,
bool a_bTime,
const char *a_pszPrefix,
bool a_bPrefix,
DWORD a_dwCase,
bool a_bNumbered,
bool a_bConsole,
bool a_bRedirect,
bool a_bFile = false );
CApplMessage( struct SApplMsgContext *a_pAppl );
void Prefix( const char *a_pszPrefix = NULL );
void Prefix( bool a_bPrefix = true );
void Write( const char *a_pszFormatStr, ... );
void Date( bool a_bDate = false);
void Time( bool a_bTime = false );
void Case( DWORD a_dwCase = _APPLMESSAGE_CASE_MIXED_ );
void Number( bool a_bNumber = false );
void NumberReset( void );
void Console( bool a_bConsole = true );
void Redirect( bool a_bRedirect = false );
void Reset( void )
{ Date();
Time();
Prefix( "" );
Prefix();
Case();
Number();
Console();
File();
Redirect();
}
int Displayed( void ) const;
};
None.
CApplMessage::CApplMessage( void ); CApplMessage::CApplMessage( _in_opt const char *a_pszPrefix = NULL ); CApplMessage::CApplMessage( _in bool a_bDate, _in bool a_bTime, _in_opt const char *a_pszPrefix = NULL ); CApplMessage::CApplMessage( _in bool a_bDate, _in bool a_bTime, _in bool a_bPrefix, _in DWORD a_dwCase, _in bool a_bNumber, _in bool a_bConsole, _in bool a_bRedirect, _in_opt const char *a_pszPrefix = NULL, _in_opt bool a_bFile = false ); CApplMessage::CApplMessage( _in struct SApplMsgContext *a_pAppl ); |
|
●
|
Purpose
Use CApplMessage to construct an object which you can use
to write messages to the console.
|
|
●
|
Parameters
|
|
|
|
●
|
const char *a_pszPrefix
[in,opt] The
address of a string which is to be displayed between the optional date,
time, message number and the actual message text.
|
|
●
|
bool a_bDate
[in] Set this
option to true if the current
date is to be included in the message.
|
|
●
|
bool a_bTime
[in] Set this
option to true if the current
time is to be included in the message.
|
|
●
|
bool a_bPrefix
[in] Set this
option to true if the string
pointed to by a_pszPrefix
is to be
included in the message.
|
|
●
|
DWORD a_dwCase
[in] The case of
the message; this can be UPPERCASE, lowercase or MiXeDcAsE. The following
definitions describe these types:
#define _APPLMESSAGE_CASE_UPPER_ 0 // Translate
output to UPPERCASE.
#define _APPLMESSAGE_CASE_LOWER_ 1 // Translate output to lowercase. #define _APPLMESSAGE_CASE_MIXED_ 2 // Default, no translation.
|
|
●
|
bool a_bNumber
[in] Set this option to true if the message number is to be
included in the message. The message number is a ten digit right-aligned
number with leading zeroes.
|
|
●
|
bool a_bConsole
[in] Set this option to true if the message is to be written
to the console.
|
|
●
|
bool a_bRedirect
[in] Set this option to true if a message intended for the
console can be redirected.
|
|
●
|
struct SApplMsgContext
*a_pAppl
[in] The address of an
SApplMsgContext structure which describes the attributes of the
CApplMessage object.
|
|
|
●
|
Returns
n/a
|
|
●
|
Messages
None
|
|
●
|
Usage
Use CApplMessage to write
synchronised messages to the console.
DWORD CMyStage::Go( void ) { // All my debug output messages will have the current date and time and a // prefix which details; my pipeline and stage number. #ifdef _DEBUG CString szPrefix; szPrefix.Format( "CMyStage::Go(%d,%d)", Pipeline(), Stage() ); CApplMessage cons( true, true, ( LPCTSTR )szPrefix ); #endif // _DEBUG // Access the manager. CStageManager *pManager = Manager(); // Record buffer. CString szRecord; while( true ) { // Read a record from my primary input stream. if( !pManager->PeekRecord( *this, 0, &szRecord ) ) { // This is the end-of-file on my primary input stream. break; } #ifdef _DEBUG cons.Write( “My input record is: ‘%s’, ( LPCTSTR )szRecord ); #endif // _DEBUG // // TODO: operate on the record here. // ... #ifdef _DEBUG cons.Write( “My output record is: ‘%s’, ( LPCTSTR )szRecord ); #endif // _DEBUG // Write the record to my primary output stream. if( !pManager->WriteRecord( *this, 0, &szRecord ) ) { // This is the end-of-file on my primary output stream. break; }
// Release the stage that I read
from.
pManager->ConsumeRecord(
*this, 0 );
} return( _RC_SUCCESS_ ); } |
void CApplMessage::Prefix( _in_opt const char *a_pszPrefix = NULL ); |
|
●
|
Purpose
Use Prefix()
to specify a string of text which will prefix each message.
|
|
●
|
Parameters
|
|
|
|
●
|
const char *a_pszPrefix
[in,opt] The
address of a buffer which contains the prefix string.
|
|
|
●
|
Returns
|
|
●
|
Messages
None
|
|
●
|
Usage
See this example.
|
void CApplMessage::Prefix( _in_opt bool a_bPrefix = true ); |
|
●
|
Purpose
Use Prefix()
to turn on or off the message prefixing option.
|
|
●
|
Parameters
|
|
|
|
●
|
bool a_bPrefix
[in,opt] Set
this option to true if the
message prefix is to be included in the message.
|
|
|
●
|
Returns
|
|
●
|
Messages
None
|
|
●
|
Usage
See this example.
|
|
●
|
Purpose
Use Write() to
write a message to the console. The message is formatted as per the written
to the console and lock is released
|
|
●
|
Parameters
|
|
|
|
●
|
const char *a_pszFormatStr
[in] The address of a message
format string. The Write() function formats and prints the specified
message to the console. If arguments follow the message format string, the
string must contain specifications that determine the output format for
those arguments. Use the Write() function in exactly the same way that you
would use the printf() function.
|
|
●
|
. . .
[in,opt] The
function arguments.
|
|
|
●
|
Returns
|
|
●
|
Messages
None
|
|
●
|
Usage
See this example. |
void CApplMessage::Date( _in_opt bool a_bDate = false ); |
|
●
|
Purpose
Use Date() to
turn on or off the date setting.
|
|
●
|
Parameters
|
|
|
|
●
|
bool a_bDate
[in,opt] Set
this option to true if the
current date is to be included in the message.
|
|
|
●
|
Returns
|
|
●
|
Messages
None
|
|
●
|
Usage
To define or
re-define a CApplMessage class objects’ settings:
DWORD CMyStage::Go( void ) { // All my output messages will have the current date and time and a // message prefix which details my pipeline and stage number. CString szPrefix; szPrefix.Format( "CMyStage::Go(%d,%d)", Pipeline(),Stage() ); CApplMessage cons( true, true, ( LPCTSTR )szPrefix );
...
// I don’t want the time or the date in
my messages anymore.
cons.Time( false );
cons.Date( false );
// I want my messages to appear in
uppercase..
cons.Case( _APPLMESSAGE_CASE_UPPER_ );
cons.Write( “My debug
message..” );
// The next
message will contain a message number.
cons.Number( true );
cons.Write( “This message
will comprise a message number” );
...
// The number
of messages output so far is:
int nNumberOfMessages =
cons.Displayed()
...
// I don’t want to use the message prefix
anymore.
cons.Prefix( false );
// Reset the
message number back to zero.
cons.NumberReset();
...
// Reset this console objects’ default
values.
cons.Reset();
// Allow further messages to be
re-directed.
cons.Redirect( true );
...
} |
void CApplMessage::Time( _in_opt bool a_bTime = false ); |
|
●
|
Purpose
Use Time() to
turn on or off the time setting.
|
|
●
|
Parameters
|
|
|
|
●
|
bool a_bTime
[in,opt] Set
this option to true if the
current time is to be included in the message.
|
|
|
●
|
Returns
|
|
●
|
Messages
None
|
|
●
|
Usage
See this example. |
void CApplMessage::Case( _in_opt DWORD a_dwCase = _APPLMESSAGE_CASE_MIXED_ ); |
|
●
|
Purpose
Use Case() to set the message case
setting; this can be
uppercase, lowercase or mixed case. The following definitions describe these
types:
#define _APPLMESSAGE_CASE_UPPER_ 0 // Translate output to uppercase. #define _APPLMESSAGE_CASE_LOWER_ 1 // Translate output to lowercase. #define _APPLMESSAGE_CASE_MIXED_ 2 // Default, no translation.
|
|
●
|
Parameters
|
|
|
|
●
|
char a_dwCase
[in,opt] The case of the message; this
can be UPPERCASE, lowercase or MiXeDcAsE, which is the default and is
defined by: _APPLMESSAGE_CASE_MIXED_.
|
|
|
●
|
Returns
|
|
●
|
Messages
None
|
|
●
|
Usage
See this example. |
void CApplMessage::Number( _in_opt bool a_bNumber = false ); |
|
●
|
Purpose
Use Number() to turn on or off message numbering. The message
number is a ten digit right-aligned number with leading zeroes.
|
|
●
|
Parameters
|
|
|
|
●
|
bool a_bNumber
[in,opt] Set
this option to true if the
message number is to be included in the message.
|
|
|
●
|
Returns
|
|
●
|
Messages
None
|
|
●
|
Usage
See this example. |
void CApplMessage::NumberReset( void ); |
|
●
|
Purpose
Use
NumberReset() to reset the message number count to zero.
|
|
●
|
Parameters
|
|
●
|
Returns
|
|
●
|
Messages
None
|
|
●
|
Usage
See this example. |
void CApplMessage::Console( _in_opt bool a_bConsole = true ); |
|
●
|
Purpose
The Console()
function is reserved for use by the StageManager. You should not use this
function.
|
void CApplMessage::Redirect( _in_opt bool a_bRedirect = false ); |
|
●
|
Purpose
Use Redirect()
to turn on or off message re-direction. When re-direction is on; messages are
written to STDOUT, in which case they are subject to stream redirection.
Otherwise; messages are written exclusively to the console.
|
|
●
|
Parameters
|
|
|
|
●
|
bool a_bRedirect
[in,opt] Set
this option to true if the
message can be re-directed.
|
|
|
●
|
Returns
|
|
●
|
Messages
None
|
|
●
|
Usage
See this example. |
void CApplMessage::Reset( void ); |
|
●
|
Purpose
Use Reset() to
re-initialise the objects’ default values.
|
|
●
|
Parameters
|
|
●
|
Returns
|
|
●
|
Messages
None
|
|
●
|
Usage
See this example. |
int CApplMessage::Displayed( void ) const; |
|
●
|
Purpose
Use
Displayed() to return the number of messages output by this CapplMessage()
object.
|
|
●
|
Parameters
|
|
●
|
Returns
|
|
|
|
●
|
int
[out] The
number of messages output by this CApplMessage() object.
|
|
|
●
|
Messages
None
|
|
●
|
Usage
See this example.
|