The CICSRequest node
can return different response messages that indicate the success or
failure of the request sent to CICS®
Transaction Server for z/OS®.
About this task
The CICSRequest node
has four output terminals:
- Out: The output terminal from which the message tree is propagated,
including the data returned from CICS.
- Failure: The output terminal to which a message is routed if a CICSRequest node exception
is detected, or a CICSRequest node
to CICS connection failure
occurs.
- Error: The output terminal to which a message is propagated if
a CICS error (abend) occurs.
- Timeout: The output terminal to which the message is propagated
if a per-request timeout occurs when an individual request is sent
to CICS, but the request
takes too long.
You can select the location to which to send the response by
configuring the Output data location Result
property on the CICSRequest node.
This property specifies the location in the message tree to which
the CICSRequest node places
the output.
Procedure
- Processing successful calls
When a CICSRequest node successfully
calls a CICS application,
the resulting message is propagated to the Out terminal.
- Processing CICS abends
An abend in CICS causes
a message to be propagated from the Error terminal. The input message
is propagated with a CICS\AbendCode
field in the LocalEnvironment. If the Error terminal is not connected,
the abend is lost.
If an abend occurs and the CICSRequest node is configured
to participate in the integration node transaction, all work carried
out as part of the CICS task
is immediately rolled back. If multiple CICS nodes
are involved in the unit of work, the CICS activity
of each of the nodes is rolled back, whether or not the abend is handled
through an error or failure terminal. Any further work carried out
by CICS as part of processing
the message is carried out under a new unit of work.
A
unit of work is the work that is carried out by nodes in a flow that
share the same resource; in this case, a unit of work is all the work
that is carried out by CICSRequest nodes
in a flow that are connected to the same CICS server (through a URL or configurable service
defined in the CICS server property). For example,
if a message flow contains five CICS nodes,
three of which are connected to CICS server
A and two of which are connected to CICS server
B, all the work that is carried out by nodes connected to server A
forms one unit of work, and all the work that is carried out by nodes
connected to server B forms a separate unit of work. If an abend occurs
in one of the CICS nodes that
are connected to CICS server
A, the work carried out by all the CICS nodes
in the flow that are connected to server A is rolled back, because
it forms a single unit of work. Any subsequent work that is carried
out by a CICSRequest node
connected to server A will start a new unit of work, and the unit
of work for server B is unaffected by the rollback of the unit of
work for server A.
- Processing request timeouts
If a CICSRequest node is configured
with a Request timeout Basic
property, and a particular message takes longer than the specified
time in seconds to be processed, the request fails and the message
is propagated from the Timeout terminal. The output message contains
the input message body and a timeout exception in the ExceptionList.
If the Timeout terminal is not connected and a timeout occurs, the
request timeout exception is routed to the Failure terminal. If the
Failure terminal is not connected, the integration node throws an
exception and returns control to the closest upstream node that can
process it. The default behavior is that the message is returned to
the input node.
- Handling failures in the CICS node
Any
other failures are propagated to the Failure terminal. Possible failures
include:
- An inability to communicate with the target CICS region.
- An internal CICSRequest node
exception is detected.
- An invalid message body. For example, a parsing error or input
message is creating a structure that is larger than the Commarea length Basic property that
is configured in the CICSRequest node.
A similar situation for the returning COMMAREA cannot be detected.
For example, if the returning data is larger than the value
that is defined in the Commarea
length property, a memory leak occurs in CICS. Therefore the Commarea length Basic property must
be correctly configured.