CICS conditions

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:

noAction
Manual condition handling
callHandleEvent
Automatic condition handling
throwException
Exception handling
abendTask
Severe error handling.

Manual condition handling (noAction)

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 }

Automatic condition handling (callHandleEvent)

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.

Exception handling (throwException)

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.

Note:
Exceptions can be thrown from the Foundation Classes for many reasons other than this example - see C++ Exceptions and the Foundation Classes for more details.

Severe error handling (abendTask)

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 ]]