CStage class

Pipelines v2.0

Member variables, Member functions

Home

Description

The CStage class object provides the interface through which you access your stage command argument, determine your position in the pipeline and test and set your input and output stream connections.

Definition

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.

class CStage
{
 public:
 
 DWORD MaxInStream( void ) const;
 void MaxInStreamsAllowed( DWORD a_dwMaxInStream );
 void MinInStreamsRequired( DWORD a_dwMinInStream );
 
 DWORD MaxOutStream( void ) const;
  void MaxOutStreamsAllowed( DWORD a_dwMaxOutStream );
 void MinOutStreamsRequired( DWORD a_dwMinOutStream );
 
 CInStream *GetInStream( DWORD a_dwInStream );
 COutStream *GetOutStream( DWORD a_dwOutStream );
 
 DWORD InStreamsConnected( void ) const;
 DWORD OutStreamsConnected( void ) const;
 
 DWORD Pipeline( void ) const;
 DWORD Number( void ) const;
 const char *Argument( void ) const;
 bool Casei( void ) const;
 bool Trace( void ) const;
};
 

Member variables

 
None.
 

Member functions

 
DWORD CStage::MaxInStream( void ) const;
 

●

Purpose

Use MaxInStream() to determine the maximum number of input streams that can be connected to your stage.

By default; your stage is assigned a single input stream; the primary input stream. However, if your stage requires, or can support, more than one input stream; you must set this limit to equal the maximum number of input streams that your stage will read from, by calling the MaxInStreamsAllowed() function. When the StageManager parses the pipeline and builds your input stream connections; it will verify that no more than this maximum number are connected to your stage.

●

Parameters

●

void

●

Returns

●	DWORD The maximum number of input streams that can be connected to your stage.

●

Messages

None

●

Usage

To loop through all your input streams, you might use the following construction:

DWORD CMyStage::Go( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
  ...
 
 // Loop through my input streams and read a record from each
 // connected stream.
 
 CString szRecord;
 DWORD dwMaxInStream = pStage->MaxInStream();
 
 for( DWORD dwInStream = 0; dwInStream < dwMaxInStream; ++dwInStream )
 {
  CInStream *pInStream = pStage->GetInStream( dwInStream );
 if( pInStream->IsConnected() )
 {
  // Read a record from the input stream.
 pManager->ReadRecord( *this, dwInStream, &szRecord ) )
 
 ...
 }
 }
 
 ...
 
 return( _RC_SUCCESS_ )
}

 
void CStage::MaxInStreamsAllowed(
 _in DWORD a_dwMaxInStream );
 

●

Purpose

Use MaxInStreamsAllowed() to set the maximum number of input streams that your stage will read from.

By default; your stage is assigned a single input stream; the primary input stream. However, if your stage requires, or can support, more than one input stream; you must set a_dwMaxInStream to equal the maximum number of input streams that your stage will read from. When the StageManager parses the pipeline and builds your input stream connections; it will verify that no more than a_dwMaxInStream input streams are connected to your stage.

●

Parameters

●	DWORD a_dwMaxInStream [in] Specifies the maximum number of input streams that can be connected to your stage.

●

Returns

●

void

●

Messages

None

●

Usage

To specify that your stage allows a maximum of two input streams:

bool CMyStage::Initialise( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
 pStage->MinInStreamsRequired( 1 );
 pStage->MaxInStreamsAllowed( 2 );
 pStage->MinOutStreamsRequired( 1 );
 pStage->MaxOutStreamsAllowed( 1 );
 
 // Point to my command argument.
 const char *pszArgument = pStage->Argument();
 
 // My stage does not require a command argument; if there is one,
 // then it is unexpected.
 
 if( *pszArgument )
 {
 // Tell the user the type of argument that I expect.
 pManager->StageMessage( *this, 33, _ERROR_, pszArgument );
 return( false );
 }
 
 return( true );

}

 
void CStage::MinInStreamsRequired(
 _in DWORD a_dwMinInStream );
 

●

Purpose

Use MinInStreamsRequired() to set the minimum number of input streams that must be connected to your stage.

By default; your stage is assigned a single input stream; the primary input stream. However, if your stage requires, or can support, more than one input stream; you must set a_dwMinInStream to equal the minimum number of input streams that your stage will read from. When the StageManager parses the pipeline and builds your input stream connections; it will verify that at least a_dwMinInStream input streams are connected to your stage.

●

Parameters

●	DWORD a_dwMinInStream [in] Specifies the minimum number of input streams that must be connected to your stage.

●

Returns

●

void

●

Messages

None

●

Usage

To specify that your stage requires a minimum of one input stream:

bool CMyStage::Initialise( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
  pStage->MinInStreamsRequired( 1 );
 pStage->MaxInStreamsAllowed( 2 );
 pStage->MinOutStreamsRequired( 1 );
 pStage->MaxOutStreamsAllowed( 1 );
 
 // Point to my command argument.
 const char *pszArgument = pStage->Argument();
 
 // My stage requires a delimited string as its command argument.
 
 CString szString;
 CCharacterString *pCharString = new CCharacterString( *this );

pCharString->m_bRequired = true;

pCharString->m_pszSource = &pszArgument;

pCharString->m_pszTarget = &szString;

pCharString->m_bNull = false;

// Extract the string.

if( !pManager->ParseForCharacterString( pCharString ) )

return( false );

 
 return( true );

}

 
DWORD CStage::MaxOutStream( void ) const;
 

●

Purpose

Use MaxOutStream() to determine the maximum number of output streams that can be connected from your stage.

By default; your stage is assigned a single output stream; the primary output stream. However, if your stage requires, or can support, more than one output stream; you must set this limit to equal the maximum number of output streams that your stage will write to, by calling the MaxOutStreamsAllowed() function. When the StageManager parses the pipeline and builds your output stream connections; it will verify that no more than this maximum number are connected from your stage.

●

Parameters

●

void

●

Returns

●	DWORD The maximum number of output streams that can be connected from your stage.

●

Messages

None

●

Usage

To loop through all your output streams, you might use the following construction:

DWORD CMyStage::Go( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
 CString szRecord;
 
 ...
 
 // Loop through my output streams and write a record to each
 // connected stream.
 
 DWORD dwMaxOutStream = pStage->MaxOutStream();
 
 for( DWORD dwOutStream = 0; dwOutStream < dwMaxOutStream; ++dwOutStream )
 {
 COutStream *pOutStream = pStage->GetOutStream( dwOutStream );
 if( pOutStream->IsConnected() )
 {
  // Write a record to the output stream.
 pManager->WriteRecord( *this, dwOutStream, &szRecord ) )
 }
 }
 
 ...
 
 return( _RC_SUCCESS_ )
}

 
void CStage::MaxOutStreamsAllowed(
 _in  DWORD a_dwMaxOutStream );
 

●

Purpose

Use MaxOutStreamsAllowed() to set the maximum number of output streams that your stage will write to.

By default; your stage is assigned a single output stream; the primary output stream. However, if your stage requires, or can support, more than one output stream; you must set a_dwMaxOutStream to equal the maximum number of output streams that your stage will write to. When the StageManager parses the pipeline and builds your output stream connections; it will verify that no more than a_dwMaxOutStream output streams are connected from your stage.

●

Parameters

●	DWORD a_dwMaxOutStream [in] Specifies the maximum number of output streams that can be connected from your stage.

●

Returns

●

void

●

Messages

None

●

Usage

To specify that your stage allows a maximum of one output stream:

bool CMyStage::Initialise( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
  pStage->MinInStreamsRequired( 1 );
 pStage->MaxInStreamsAllowed( 2 );
 pStage->MinOutStreamsRequired( 1 );
 pStage->MaxOutStreamsAllowed( 1 );
 
 // Point to my command argument.
 const char *pszArgument = pStage->Argument();
 
 // My stage requires an unsigned integer in the range 1 to 1000,
 // as its command argument.
 
 CString szString;
 CIntegerString *pIntString = new CIntegerString( *this );
 

pIntString->m_bRequired = true;

pIntString->m_pszSource = &pszArgument;

pIntString->m_pszTarget = &szString;

pIntString->m_lMinUnsignedValue = 1;

pIntString->m_lMaxUnsignedValue = 1000;

// Extract the string.

if( !pManager->ParseForIntegerString( pIntString ) )

return( false );

// Convert the string to an integer ( long ) value.

if( !pManager->ConvertToInteger( pIntString ) )

return( false );

 
 return( true );

}

 
void CStage::MinOutStreamsRequired(
 _in DWORD a_dwMinOutStream );
 

●

Purpose

Use MinOutStreamsRequired() to set the minimum number of output streams that must be connected from your stage.

By default; your stage is assigned a single output stream; the primary output stream. However, if your stage requires, or can support, more than one output stream; you must set a_dwMinOutStream to equal the minimum number of output streams that your stage will write to. When the StageManager parses the pipeline and builds your output stream connections; it will verify that at least a_dwMinOutStream output streams are connected from your stage.

●

Parameters

●	DWORD a_dwMinOutStream [in] Specifies the minimum number of output streams that must be connected from your stage.

●

Returns

●

void

●

Messages

None

●

Usage

To specify that your stage requires a minimum of one output stream:

bool CMyStage::Initialise( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
  pStage->MinInStreamsRequired( 1 );
 pStage->MaxInStreamsAllowed( 2 );
 pStage->MinOutStreamsRequired( 1 );
 pStage->MaxOutStreamsAllowed( 1 );
 
 // Point to my command argument.
 const char *pszArgument = pStage->Argument();
 
 // My stage requires a signed from-to number range as its
 // command argument.
 
 CIntegerRange *pIntRange = new CIntegerRange( *this );

pIntRange->m_pszSource = &pszArgument;

pIntRange->m_bFromSigned = true;

pIntRange->m_bToSigned = true;

pIntRange->m_bRequired = true;

pIntRange->m_nType = eInput;

// Extract the range.

if( !m_pManager->ParseForIntegerRange( m_pIntRange ) )

 return( false );
 

long lFrom = pIntRange->m_lFrom;

 long lTo = pIntRange->m_lTo;
 
 return( true );

}

 
CInStream *CStage::GetInStream(
 _in DWORD a_dwInStream );
 

●

Purpose

Use GetInStream() to get a pointer to the specified input stream.

With this pointer; you can test and set an input streams’ connection status. The number of input streams connected to your stage is limited by a combination of the calls to the MaxInStreamsAllowed() and MinInStreamsRequired() functions. However, these only define the upper and lower stream connection limits; to test if a specific input stream is connected, you need a pointer to that stream.

The input streams connected to your stage are numbered as; a primary input stream; stream 0, a secondary input stream; stream 1, a tertiary input stream; stream 2, and so on.

●

Parameters

●	DWORD a_dwInStream [in] Specifies the input stream number.

●

Returns

●	CInStream * An input stream pointer.

●

Messages

None

●

Usage

To access a specific input stream:
 
bool CMyStage::Initialise( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
 pStage->MinInStreamsRequired( 1 );
 pStage->MaxInStreamsAllowed( 2 );
 pStage->MinOutStreamsRequired( 1 );
 pStage->MaxOutStreamsAllowed( 1 );
 
 // Point to my command argument.
 const char *pszArgument = pStage->Argument();
 
 // Check if my secondary input stream is defined and connected.
 
 CInStream *pInStream = pStage->GetInStream( 1 );
 if( pInStream && pInStream->IsConnected() )
 {
 // My secondary input stream is connected!
 
 ...
 }
 
 ...
 
 return( true );

}

 
COutStream *CStage::GetOutStream(
 _in DWORD a_dwOutStream );
 

●

Purpose

Use GetOutStream() to get a pointer to the specified output stream.

With this pointer; you can test and set an output streams’ connection status. The number of output streams connected from your stage is limited by a combination of the calls to the MaxOutStreamsAllowed() and MinOutStreamsRequired() functions. However, these only define the upper and lower stream connection limits; to test if a specific output stream is connected, you need a pointer to that stream.

The output streams connected from your stage are numbered as; a primary output stream; stream 0, a secondary output stream; stream 1, a tertiary output stream; stream 2, and so on.

●

Parameters

●	DWORD a_dwOutStream [in] Specifies the output stream number.

●

Returns

●	COutStream * An output stream pointer.

●

Messages

None

●

Usage

To access a specific output stream:

bool CMyStage::Initialise( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
 pStage->MinInStreamsRequired( 1 );
 pStage->MaxInStreamsAllowed( 1 );
 pStage->MinOutStreamsRequired( 1 );
 pStage->MaxOutStreamsAllowed( 2 );
 
 // Point to my command argument.
 const char *pszArgument = pStage->Argument();
 
 // Check if my secondary output stream is defined and connected.
 
 COutStream *pOutStream = pStage->GetOutStream( 1 );
 if( pOutStream && pOutStream->IsConnected() )
 {
 // My secondary output stream is connected!
 
 ...
 }
 
 ...
 
 return( true );

}

 
DWORD CStage::InStreamsConnected( void ) const;
 

●

Purpose

Use InStreamsConnected() to determine the number of input streams that are currently connected to your stage.

●

Parameters

●

void

●

Returns

●	DWORD The number of input streams that are currently connected to your stage.

●

Messages

None

●

Usage

To determine the number of input streams that are currently connected:

bool CMyStage::Initialise( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
 pStage->MinInStreamsRequired( 1 );
 pStage->MaxInStreamsAllowed( 2 );
 pStage->MinOutStreamsRequired( 1 );
 pStage->MaxOutStreamsAllowed( 2 );
 
 // Point to my command argument.
 const char *pszArgument = pStage->Argument();
 
 // Check if both my primary and secondary input streams are connected.
 
 if( pStage->InStreamsConnected() == 2 )
 {
 // Both input streams are connected!
 
 ...
 }
 
 ...
 
 return( true );

}

 
DWORD CStage::OutStreamsConnected( void ) const;
 

●

Purpose

Use OutStreamsConnected() to determine the number of output streams that are connected from your stage.

●

Parameters

●

void

●

Returns

●	DWORD The number of output streams that are currently connected to your stage.

●

Messages

None

●

Usage

To determine the number of output streams that are currently connected:

bool CMyStage::Initialise( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
  pStage->MinInStreamsRequired( 1 );
 pStage->MaxInStreamsAllowed( 1 );
 pStage->MinOutStreamsRequired( 1 );
 pStage->MaxOutStreamsAllowed( 2 );
 
 // Point to my command argument.
 const char *pszArgument = pStage->Argument();
 
 // Check if both my primary and secondary output streams are connected.
 
 if( pStage->OutStreamsConnected() == 2 )
 {
 // Both output streams are connected!
 
 ...
 }
 
 ...
 
 return( true );

}

 
DWORD CStage::Pipeline( void ) const;
 

●

Purpose

Use Pipeline() to get the number of your pipeline.

The number of the pipeline to which your stage belongs is important; when you consider that a stage command argument which you may or may not require; depends on where your stage is positioned in the pipeline. Your stage might require a command argument only when it is positioned as the first stage in the first pipeline; otherwise, when specified in any other position; a command argument is not required. Pipeline() when used in combination with Number() allows you to determine exactly where your stage is positioned. For example; it would not make any sense to allow a command argument which specifies how to handle input stream records; when your stage is positioned as the first stage, in the first pipeline, the argument might have no effect on how your stage performs its function, and in this case; allowing the specification of a stage command argument would be misleading and confusing for the user.

Pipeline() identifies the number of the pipeline to which your stage belongs; starting with pipeline number 0, followed by pipeline 1, then 2, and so on.

●

Parameters

●

void

●

Returns

●	DWORD The number of your pipeline.

●

Messages

None

●

Usage

To determine the number of your pipeline:

bool CMyStage::Initialise( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
 ...
 
 // Point to my command argument.
 const char *pszArgument = pStage->Argument();
 
 // If I am the first stage in the first pipeline, then I must have
 // a delimited string command argument.
 
  if( pStage->Pipeline() == 0 && pStage->Number() == 0 && !( *pszArgument ) )
 {
 // Tell the user the type of argument that I expect.
 pManager->StageMessage( *this, 19, _ERROR_, pszArgument );
 return( false );
 }
 
 ...
 
 return( true );
}

 
DWORD CStage::Number( void ) const;
 

●

Purpose

Use Number() to get the number of your stage.

The number of your stage in the pipeline is important; when you consider that a stage command argument which, you may or may not require; depends on where your stage is positioned in the pipeline. Your stage might require a command argument only when it is positioned as the first stage in the pipeline; otherwise, when specified in any other position; a command argument is not required. Number() when used in combination with Pipeline() allows you to determine exactly where your stage is positioned. For example; it would not make any sense to allow a command argument which specifies how to handle input stream records; when your stage is positioned as the first stage in the pipeline, the argument might have no effect on how your stage performs its function, and in this case; allowing the specification of a stage command argument would be misleading and confusing for the user.

Number() identifies your stage position in the pipeline; starting with stage number 0, followed by stage 1, then 2, and so on.

●

Parameters

●

void

●

Returns

●	DWORD The number of your stage.

●

Messages

None

●

Usage

To determine the number of your stage:

bool CMyStage::Initialise( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
 ...
 
 // Point to my command argument.
 const char *pszArgument = pStage->Argument();

 // If I am not the first stage in the pipeline, then I do not need
 // a command argument.
 

if( pStage->Number() && *pszArgument )

 {
 // Tell the user the type of argument that I expect.
 pManager->StageMessage( *this, 33, _ERROR_, pszArgument );
 return( false );
 }
 
 return( true );

}

 
const char *CStage::Argument( void ) const;
 

●

Purpose

Use Argument() to access your stage command argument.

●

Parameters

●

void

●

Returns

●	const char * A pointer to your stage command argument.

●

Messages

None

●

Usage

To access your stage command argument:
 
bool CMyStage::Initialise( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
 ...
 
 // Point to my command argument.
 const char *pszArgument = pStage->Argument();

 // My stage requires a character range as its command argument.
 
 CString szString;
 CCharacterRange *pCharRange = new CCharacterRange( *this );

pCharRange->m_pszSource = &pszArgument;

pCharRange->m_bRequired = true;

pCharRange->m_bExpand = true;

pCharRange->m_pszExpandedRange = &szString;

// Extract the range.

if( !pManager->ParseForCharacterRange( pCharRange ) )

 return( false );
 
 ...
 
 return( true );

}

 
bool CStage::Casei( void );
 

●

Purpose

Use Casei() to determine if CASEI pre-processing is enabled for your stage.

If you have enabled pre-processing through a call to PreProcess() in your stage Initialise() function; Casei() returns a value of true when the user specifies a stage command argument which uses the CASEI() pre-process function or the CASEI operand on the ZONE() pre-process function, otherwise Casei() returns false.

There are a number of builtin Pipelines stages’ which operate as simple selection filters; writing records to their primary and secondary output streams, depending on the content of an input record; consider the FROMLABEL stage, for example. By default, all of these filter type stages’ check for the existence/or not of the specified text starting in the first column of an input record. However, the PreProcess() function extends this basic selection capability; instructing the manager to extract a substring of the record, determined by the column, word or field range, and optionally; to translate both the stage operands and the content of the input records to uppercase, and present this altered record to the stage when a read-record is requested. The function does not alter the way in which a stage processes its input and output records, it only alters the format of the record which is presented to the stage. When the stage performs a subsequent write-record request, the manager writes the original unmodified input record to the specified output stream.

PreProcess() ensures that the stage command argument syntax for a position or range on which to operate, is identical for all filter type stages.

●

Parameters

●

void

●

Returns

●	bool true if CASEI is enabled, otherwise; false.

●

Messages

None

●

Usage

To determine if pre-processing is enabled:

bool CMyStage::Initialise( void )
{
 // Access the manager.
 CStageManager *pManager = Manager();
 // Access my stage.
 CStage *pStage = pManager->GetStage( *this );
 
 ...
 
 // Point to my command argument.
 const char *pszArgument = pStage->Argument();
 
 // Perform any preprocessing required.
 if( !pManager->PreProcess( *this, &pszArgument ) )
 return( false );
 
 // My stage requires a delimted string which is to be interpreted as
 // a regular expression as its command argument.
 
 CString szString;
 CCharacterString *pCharString = new CCharacterString( *this );

pCharString->m_bRequired = true;

pCharString->m_pszSource = &pszArgument;

pCharString->m_pszTarget = &szString;

// Extract the string.

if( !pManager->ParseForCharacterString( pCharString ) )

return( false );

 
 // Parse and load the regular expression.
 CRegExpression *pRegExp = new CRegExpression;

pRegExp->m_RegExp.Expression = szString;

if( !pManager->ParseForRegExp( *this, pRegExp, pStage->Casei() ) )

return( false );

...

 return( true );

}

 
bool CStage::Trace( void );
 

●

Purpose

Use Tracei() to determine if tracing is enabled for your stage.

When TRACE is enabled for your stage; you may want to display console information in a way that might help the user to best understand how your stage reads and writes its input and output records and the data that they contain. (Note, however; you should not assume that this implies that Pipelines is operating in any kind of test-mode – tracing a pipeline only involves the intercept and display of input read and output write requests. What your stage writes to an output stream, is written without any regard to the TRACE mode). For example, when the CONSOLE stage command determines that TRACE is enabled, CONSOLE formats its console output in a way that highlights the data so that the user can easily see what would ordinarily be written to the console – primary output stream records are written unchanged.

●

Parameters

●

void

●

Returns

●	bool true if TRACE is enabled, otherwise; false.

●

Messages

None

●

Usage

To determine if TRACE is enabled for your stage:

DWORD CMyStage::Go( void )

{

// Access the manager.

CStageManager *pManager = Manager();

// Access my stage.

CStage *pStage = m_pManager->GetStage( *this );

// Record buffer.

CString szRecord;

while( true )

{

 // Read a record from my primary input stream.

if( !pManager->ReadRecord( *this, 0, &szRecord ) )

{

// This is the end-of-file on my primary input stream.

break;

}

if( pStage->Trace() )

{

// What ever you want to do ..

...

}

//

// TODO: operate on the record here.

//

...

// 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;

}

}

return( _RC_SUCCESS_ );

}