C++ Exceptions and the Foundation Classes

C++ exceptions are managed using the reserved words try , throw , and catch.

Refer to your compiler's documentation or one of the C++ books in the bibliography for more information.

Here is sample ICC$EXC1 (see C++ sample programs ): 
#include "icceh.hpp"
#include "iccmain.hpp"
class Test {
public:
void tryNumber( short num ) {
IccTerminal* term = IccTerminal::instance();
*term << "Number passed = " << num << endl <<
flush;
if ( num > 10 ) {
*term << ">>Out of Range - throwing exception" << endl
<< flush;
throw "!!Number is out of range!!";
}
}
};

The first two lines include the header files for the Foundation Classes and the standard main function that sets up the operating environment for the application program.

We then declare class Test , which has one public method, tryNumber . This method is implemented inline so that if an integer greater than ten is passed an exception is thrown. We also write out some information to the CICS® terminal. 
void IccUserControl::run()
{
IccTerminal* term = IccTerminal::instance();
term->erase();
*term << "This is program 'icc$exc1' ..." << endl;
try {
Test test;
test.tryNumber( 1 );
test.tryNumber( 7 );
test.tryNumber( 11 );
test.tryNumber( 6 );
}
catch( const char* exception ) {
term->setLine( 22 );
*term << "Exception caught: " << exception << endl
<< flush;
}
term->send( 24,1,"Program 'icc$exc1' complete: Hit PF12 to End" );
term->waitForAID( IccTerminal::PF12 );
term->erase();
return;
}

The run method of IccUserControl class contains the user code for this example.

After erasing the terminal display and writing some text, we begin our try block. A try block can scope any number of lines of C++ code.

Here we create a Test object and invoke our only method, tryNumber , with various parameters. The first two invocations (1, 7) succeed, but the third (11) causes tryNumber to throw an exception. The fourth tryNumber invocation (6) is not executed because an exception causes the program execution flow to leave the current try block.

We then leave the try block and look for a suitable catch block. A suitable catch block is one with arguments that are compatible with the type of exception being thrown (here a char* ). The catch block writes a message to the CICS terminal and then execution resumes at the line after the catch block.

The output from this CICS program is as follows: 
This is program 'icc$exc1' ...
					Number passed = 1
					Number passed = 7
					Number passed = 11
					>>Out of Range - throwing exception
					Exception caught: !!Number is out of range!!
					Program 'icc$exc1' complete: Hit PF12 to End

The CICS C++ Foundation Classes do not throw char* exceptions as in the previous sample but they do throw IccException objects instead.

There are several types of IccException . The type method returns an enumeration that indicates the type. Here is a description of each type in turn.
objectCreationError
An attempt to create an object was invalid. This happens, for example, if an attempt is made to create a second instance of a singleton class, such as IccTask.
invalidArgument
A method was called with an invalid argument. This happens, for example, if an IccBuf object with too much data is passed to the writeItem method of the IccTempStore class by the application program.

It also happens when attempting to create a subclass of IccResourceId , such as IccTermId , with a string that is too long.

The following sample can be found in C++ sample programs , as file ICC$EXC2 . The sample is presented here without many of the terminal IO requests. 
#include "icceh.hpp"
#include "iccmain.hpp"
void IccUserControl::run()
{
try
{
IccTermId id1( "1234" );
IccTermId id2( "12345");
}
catch( IccException& exception )
{
terminal()->send( 21, 1, exception.summary() );
}
return;
}

In the previous example the first IccTermId object is successfully created, but the second caused an IccException to be thrown, because the string "12345" is 5 bytes where only 4 are allowed. See C++ sample programs for the expected output from this sample program.

invalidMethodCall
A method cannot be called. A typical reason is that the object cannot honor the call in its current state. For example, a readRecord call on an IccFile object is only honored if an IccRecordIndex object, to specify which record is to be read, has already been associated with the file.
CICSCondition
A CICS condition, listed in the IccCondition structure, has occurred in the object and the object was configured to throw an exception.
familyConformanceError
Family subset enforcement is on for this program and an operation that is not valid on all supported platforms has been attempted.
internalError
The CICS foundation classes have detected an internal error. Please call service.