Member variables, Member functions

Home

     ●

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

     ●

Returns

     ●

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, dwIndex, &szRecord ) )

            ...

        }

    }

    ...

    return( _RC_SUCCESS_ )

}

     ●

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

     ●

Returns

     ●

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

}

     ●

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

     ●

Returns

     ●

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

}

     ●

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

     ●

Returns

     ●

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_ )

}

     ●

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

     ●

Returns

     ●

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

}

     ●

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

     ●

Returns

     ●

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

}

     ●

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

     ●

Returns

     ●

Messages

None

     ●

Usage

To access a specific input stream 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 );

}

     ●

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

     ●

Returns

     ●

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

}

     ●

Purpose

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

     ●

Parameters

     ●

Returns

     ●

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

}

     ●

Purpose

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

     ●

Parameters

     ●

Returns

     ●

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

}

     ●

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

     ●

Returns

     ●

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

}

     ●

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

     ●

Returns

     ●

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

}

     ●

Purpose

Use Argument() to access your stage command argument.

     ●

Parameters

     ●

Returns

     ●

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

}

     ●

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

     ●

Returns

     ●

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

}