The CICS® foundation classes provide a powerful framework for handling conditions that happen when executing an application. Accessing a CICS resource can raise a number of CICS conditions as documented in Foundation Classes--reference.
A condition might represent an error or simply information being returned to the calling application; the deciding factor is often the context in which the condition is raised.
The application program can handle the CICS conditions in a number of ways. Each CICS resource object, such as a program, file, or data queue, can handle CICS conditions differently, if required.
A resource object can be configured to take one of the following actions for each condition it can encounter:
This is the default action for all CICS conditions (for any resource object). It can be explicitly activated as follows:
IccTempStore temp("TEMP1234");
temp.setActionOnCondition(IccResource::noAction,
IccCondition::QIDERR);
This setting means that when CICS raises the QIDERR condition as a result of action on the 'temp' object, no action is taken. This means that the condition must be handled manually, using the condition method. For example:
IccTempStore temp("TEMP1234");
IccBuf buf(40);
temp.setActionOnCondition(IccResource::noAction,
IccCondition::QIDERR);
buf = temp.readNextItem();
switch (temp.condition())
{
case IccCondition::QIDERR:
//do whatever here
·
·
·
default:
//do something else here
}
Activate this for any CICS condition, such as QIDERR, as follows:
IccTempStore temp("TEMP1234");
temp.setActionOnCondition(IccResource::callHandleEvent,
IccCondition::QIDERR);
When a call to any method on object 'temp' causes CICS to raise the QIDERR condition, handleEvent method is automatically called. As the handleEvent method is only a virtual method, this call is only useful if the object belongs to a subclass of IccTempStore and the handleEvent method has been overridden.
Make a subclass of IccTempStore, declare a constructor, and override the handleEvent method.
class MyTempStore : public IccTempStore
{
public:
MyTempStore(const char* storeName) : IccTempStore(storeName) {}
HandleEventReturnOpt handleEvent(IccEvent& event);
};
Now implement the handleEvent method.
IccResource::HandleEventReturnOpt MyTempStore::handleEvent(IccEvent& event)
{
switch (event.condition())
{
case ...
·
·
·
case IccCondition::QIDERR:
//Handle QIDERR condition here.
·
·
·
//
default:
return rAbendTask;
}
}
This code is called for any MyTempStore object which is configured to 'callHandleEvent' for a particular CICS condition.
Activate this for any CICS condition, such as QIDERR, as follows:
IccTempStore temp("TEMP1234");
temp.setActionOnCondition(IccResource::throwException,
IccCondition::QIDERR);
Exception handling is by means of the C++ exception handling model using try, throw, and catch. For example:
try
{
buf = temp.readNextItem();
·
·
·
}
catch (IccException& exception)
{
//Exception handling code
·
·
·
}
An exception is thrown if any of the methods inside the try block raise the QIDERR condition for object 'temp'. When an exception is thrown, C++ unwinds the stack and resumes execution at an appropriate catch block - it is not possible to resume within the try block. For a fuller example of the above, see sample ICC$EXC3.
This option allows CICS to terminate the task when certain conditions are raised. Activate this for any CICS condition, such as QIDERR, as follows:
IccTempStore temp("TEMP1234");
temp.setActionOnCondition(IccResource::abendTask,
IccCondition::QIDERR);
If CICS raises the QIDERR condition for object 'temp' the CICS task terminates with an ACL3 abend.
[[ Contents Previous Page | Next Page Index ]]