About the CICS Transaction Server for z/OS Connectivity sample

The CICS Transaction Server for z/OS Connectivity sample is based on a scenario where the objective is to retrieve a record from a file resource that is defined to CICS.

The following diagram shows the architecture of using CICS connectivity in a message flow.

An illustration of CICS Transaction Server for z/OS connectivity architecture.

The CICS Transaction Server for z/OS Connectivity sample demonstrates the following tasks:

Incorporating the CICSRequest node into a message flow for connecting to CICS to run a program on the target region
Incorporating data from the input message to form part of the COMMAREA that is being sent to and received from CICS
Interpreting the return codes from CICS
Handling abends from CICS

The CICS DFH$AXCS program receives a COMMAREA to open, browse, and close a file. DFH$AXCS is a program that uses the FILEA sample data that is provided with CICS. FILEA is a Key Sequenced Dataset (KSDS) file that contains sample account information and is indexed by a six character record number. DFH$AXCS accesses this file and takes the input arguments of a command, a file resource name, and a record identifier. The command tells the sample whether to open, browse, update, or close the file. The file resource refers to an installed file resource definition that maps to the real KSDS data. The record number is used as the key when reading or updating the file. The sample makes three calls to CICS to open, browse a record, and close the file.

Input messages

Three input messages are supplied for running the CICS Transaction Server for z/OS Connectivity sample:

An XML message to retrieve record 111111 from FILEA.

<?xml version="1.0"?>
<data>
 <file>FILEA</file>
 <record>111111</record>
</data>

An XML message to retrieve record 222222 from FILEA.

<?xml version="1.0"?>
<data>
 <file>FILEA</file>
 <record>222222</record>
</data>

An XML message to attempt to open a non-existent file.

<?xml version="1.0"?>
<data>
 <file>FILEB</file>
 <record></record>
</data>

Output messages

Four output messages can be received when running the CICS Transaction Server for z/OS Connectivity sample:

The 111111 record that is retrieved from FILEA is transformed to XML:

<?xml version="1.0" encoding="UTF-8"?>
<record>
  <stat></stat>
  <recid>111111</recid>
  <name>C. BAKER</name>
  <address>OTTAWA, ONTARIO</address>
  <phone>51212003</phone>
  <date>26 11 81</date>
  <amount>$0011.00</amount>
  <comment>*********</comment>
</record>

The 222222 record that is retrieved from FILEA is transformed to XML:

<?xml version="1.0" encoding="UTF-8"?>
<record>
  <stat></stat>
  <recid>222222</recid>
  <name>DR E. GRIFFITHS</name>
  <address>FRANKFURT, GERMANY</address>
  <phone>20034151</phone>
  <date>26 11 81</date>
  <amount>$0022.00</amount>
  <comment>*********</comment>
</record>

The XML that is received when an attempt is made to open a non-existent file:

<?xml version="1.0" encoding="UTF-8"?>
<record>
  <stat>File could not be found</stat>
</record>

If any of the CICSRequest nodes in the message flow or subflow experience an abend, an abend code is sent from the Error terminal of the CICSRequest node, and is propagated to the "Convert abend code to XML" Compute node. The Compute node then creates an XML message that contains the CICS abend code, where 1234 is the CICS abend code:
```
<?xml version="1.0" encoding="UTF-8"?>
<error>
  <abendcode1234/abendcode>
</error>
```

Message flows

The following diagram shows the main CICS Transaction Server for z/OS Connectivity sample message flow.

A screen capture of the main message flow.

Node type	Node name
MQInput	CICS_IN
Compute	Set Open Command, Convert FILE not found to XML, Convert FILEA record to XML, Convert abend code to XML
CICSRequest	Open FILEA
Filter	Check FILEA opened
Subflow	CICSConnectivityProcessFILEA
MQOutput	CICS_OUT, CICS_ERROR

The following diagram shows the CICS Transaction Server for z/OS Connectivity sample message subflow, CICSConnectivityProcessFILEA.

A screen capture of the subflow.

Node type	Node name
Input	Input
Compute	Set Browse Command, Set Close Command
CICSRequest	Browse FILEA, Close FILEA
Output	Output, Error

To find out more information about the nodes that are used in the CICS Transaction Server for z/OS Connectivity sample, see Built-in nodes in the IBM Integration Bus documentation.

Route taken by the FILEA messages

When you put one of the FILEA messages on to the input queue, the message passes through the nodes. If any of the queues have been disabled, the message cannot follow this path.

The following section describes the route taken by the FILEA messages, and the function of the nodes in the main CICS Transaction Server for z/OS Connectivity sample message flow and in the CICSConnectivityProcessFILEA message subflow:

CICS_IN: The "CICS_IN" MQInput node gets the input message from the input queue.
Set Open Command: The "Set Open Command" Compute node sets the message set, type, and format from which to create the COMMAREA for sending to CICS. The structure of the COMMAREA is as defined in the dfh$axcs_cpybooks.cpy copybook file. The node sets the open parameter that is required by the CICS DFH$AXCS program, that is: AXCS_COMMAND = 1. The node also sets the AXCS_FILE parameter to the data.file value that is specified in the XML input message. Finally, the node stores the data.record value from the XML input message to the local environment for use in the subsequent "Browse FILEA" CICSRequest node invocation.
Open FILEA: The "Open FILEA" CICSRequest node connects to CICS and opens the FILEA resource. The CICS server property of the CICSRequest node is set to use the CICSConnection configurable service, as described in Setting up the CICS Transaction Server for z/OS Connectivity sample. The Program name and Commarea length properties are set, and the COMMAREA that is created in the "Set Open Command" Compute node is sent to CICS. CICS runs the DFH$AXCS program and FILEA is opened. The structure of the COMMAREA that is returned to IBM Integration Bus from CICS is the same as the outbound COMMAREA, that is: dfh$axcs_cpybooks.cpy
Check FILEA opened: The "Check FILEA opened" Filter node performs a check of the CICS return code to ensure that the file opened successfully on the host system. If FILEA opened successfully, the message is propagated to the CICSConnectivityProcessFILEA subflow.
CICSConnectivityProcessFILEA subflow:
1. Set Browse Command: The "Set Browse Command" Compute node sets the browse parameter that is required by the CICS DFH$AXCS program, that is: AXCS_COMMAND = 2. The "Set Browse Command" Compute node also retrieves the data.record value from the local environment and sets the AXCS_RIFLD parameter to inform the DFH$AXCS program which record to retrieve from FILEA.
2. Browse FILEA: "Browse FILEA" is a CICSRequest node that instructs CICS to browse FILEA and retrieve the record.
3. Set Close Command: The "Set Close Command" Compute node sets the close parameter, that is: AXCS_COMMAND = 3.
4. Close FILEA: The final CICSRequest node, "Close FILEA", sends the COMMAREA to CICS, and FILEA is closed.
Convert FILEA record to XML: Throughout this message flow, the main message that is being propagated through the nodes is the COMMAREA that is created by the "Set Open Command" Compute node, which is being passed to and from CICS. The main item of interest now is the data that is retrieved from the "Browse FILEA" CICSRequest node. The "Convert FILEA record to XML" Compute node creates an XML message containing the transformed byte stream of the FILEA record and converts the message to an XML format, as shown in the Output messages section.
CICS_OUT: The "CICS_OUT" MQOutput node puts the message on the CICS_OUT output queue.
Convert abend code to XML: The "Convert abend code to XML" Compute node handles error situations. Each of the CICSRequest nodes in the message flow and subflow have their Error terminals connected to this Compute node. The Compute node creates an XML message containing the CICS abend code, as shown in the Output messages section.
CICS_ERROR: The "CICS_ERROR" MQOutput node puts the message on the CICS_ERROR output queue.

Route taken by the FILEB message

The route taken by the FILEB message is like the route taken by the FILEA messages, but with the following differences:

Open FILEA: The "Open FILEA" CICSRequest node attempts to open FILEB, which is a non-existent file on the host CICS region.
Check FILEA opened: The "Check FILEA opened" Filter node determines a return code of 12 and the message is propagated directly to the "Convert FILE not found to XML" Compute node.
Convert FILE not found to XML: Because no retrieved record exists for the "Convert FILE not found to XML" Compute node to transform, the "Convert FILE not found to XML" Compute node creates an informative message.

This sample demonstrates how to read an input message, to connect to CICS, and to retrieve a record from FILEA. The record data is transformed to XML and is output to a queue. If the file cannot be found, an informative message is created.

For more information, see Working with CICS Transaction Server for z/OS in the IBM Integration Bus documentation.

You can now complete the setup steps described in Setting up the CICS Transaction Server for z/OS Connectivity sample before running the sample.

Back to sample home