Creating an Adapter Transaction

After you create a connection to CICS, you can add adapter transactions using iWay Explorer (Java Servlet). A single CICS connection may be associated with multiple transactions. Each transaction represents one service offered by CICS and consists of a program and its metadata.

A generic transaction is automatically added and represents CICS services whose data will not be mapped to XML. You can use a generic transaction for programs that accept no input and for programs that return no output or when it is acceptable to return a non-formatted answer set.

For example, the supplied program IWAYIVP connects to CICS and returns "Congratulations" on successful adapter installation and configuration. Because IWAYIVP requires no input or output, you do not require COBOL descriptions for the input or output. One request and response schema is applicable for this program. The request schema for the generic transaction is in Sample Requests, Schemas, and COBOL File Descriptions.

Using the generic transaction, the XML request document that is received must include the name of the program to be called in the <Transaction> element. The payload to be sent as the COMMAREA must be in the <CommArea> tag, which can be a maximum of 32,500 bytes.

The generic response schema is constructed from the data received from CICS. If the <CommArea> element has more than 80 bytes, the received COMMAREA is split into 80-byte messages. Illegal XML characters ('<', '/', and '&') are converted to XML entities.

For programs that require input and output and a formatted response, which is usually the case, (IWAYIVP is an exception), you must add your own adapter transactions, as described in How to Create an Adapter Transaction. XML request messages must specify the transaction to use in the location attribute of the <Transaction> tag. For example, if you create a CICS transaction called IWAYSRV0, the location is "CICS/Transactions/IWAYSRV0".

To view a sample generic request or response schema or for information about specifying a transaction to use in the location attribute of the <Transaction> tag, see Sample Requests, Schemas, and COBOL File Descriptions.

Sample Program IWAYSRV0

iWay Software supplies the IWAYSRV0 and IWAYIVP programs with the adapter. This document uses the IWAYSRV0 program for illustration purposes and as a reference for the adapter. IWAYSRV0 is an example of a program that returns one of two possible record layouts depending on what is passed in the request.

If the value for the field COMMAND is 'SHORT', the program returns 40 bytes of data.
If the value for the field COMMAND is 'LONG', the program returns 60 bytes of data.

Sample request documents are in Sample Requests, Schemas, and COBOL File Descriptions, with a sample response schema for the IWAYSRV0 program. You specify the output as explained in Creating an Adapter Transaction. You must know the field in the COBOL description that can be used as a record type and the value of that field. You specify the value of the field to create the appropriate response schema. This is also true for events to determine what layout is returned from CICS when you configure a CICS event. For more information, see Event Processing With the CICS Adapter.

Procedure: How to Create an Adapter Transaction

Perform the following steps to create an adapter transaction.

Note: For demonstration purposes only, this procedure uses the version of iWay Explorer that is embedded within iWay Designer. For more information about configuring and using this version of iWay Explorer, see the iWay Designer User’s Guide.

Expand the Services node.
Expand the CICS adapter node and connect to an available CICS target (for example, CICSTarget).

The Transaction node appears under the connected target, as shown in the following image.
Right-click the Transactions node and select Add Service from the context menu.

The Add Service dialog box opens and displays two tabs (General and Output COBOL Data Description). The following image shows the parameters in the General tab that will enable you to map the COBOL descriptions for the CICS transaction.

To map the COBOL descriptions for the CICS transaction, type values for the parameters, type values for the parameters in the General tab, as defined in the following table.

Field

Description

Node Name

Name of the adapter transaction you are creating, for example, IWAYSRV0. Use this name in the <Transaction location="..."> attribute.

Program Name

Name of the program to be called in CICS, for example, IWAYSRV0. The IWAYSRV0 program appears in Sample Programs.

Input COBOL Data Description

Location of the COBOL description that describes the COMMAREA of the CICS program to execute.

It is converted by the adapter to an XML schema that the adapter uses to map from XML to the format required by CICS at run time.

Size of COMMAREA

Size of the COMMAREA (in bytes) for programs that expect a specific size. By default, the adapter passes 32,500 to the program. For best performance, specify a number that can accommodate the larger of the input COMMAREA or output COMMAREA. For example, to run IWAYSRV0, specify 60.

Natural Library

Run-time location of the Natural program to execute.

Specify a value for this field only if the adapter is expected to execute Adabas/Natural programs.

Use data structure information from COBOL

When this parameter is selected, the adapter creates request and response schemas that reflect COBOL group levels (for example, 05, 10, 20, and so on). The COBOL grouping is reflected in the XML request and response schemas.

You must select this parameter when COBOL input or output descriptions contain the COBOL OCCURS or REDEFINES statement.

Note: When this parameter is selected and there is an OCCURS COBOL statement, you cannot test run an adapter transaction. iWay Explorer returns an "OCCURS in COBOL Data Description" error message.

Accept multiple records in COMMAREA

When this parameter is selected, multiple COMMAREA records are read by the PreParser. Otherwise, any data in excess of the COBOL definition is truncated.

Field	Description
Node Name	Name of the adapter transaction you are creating, for example, IWAYSRV0. Use this name in the <Transaction location="..."> attribute.
Program Name	Name of the program to be called in CICS, for example, IWAYSRV0. The IWAYSRV0 program appears in Sample Programs.
Input COBOL Data Description	Location of the COBOL description that describes the COMMAREA of the CICS program to execute. It is converted by the adapter to an XML schema that the adapter uses to map from XML to the format required by CICS at run time.
Size of COMMAREA	Size of the COMMAREA (in bytes) for programs that expect a specific size. By default, the adapter passes 32,500 to the program. For best performance, specify a number that can accommodate the larger of the input COMMAREA or output COMMAREA. For example, to run IWAYSRV0, specify 60.
Natural Library	Run-time location of the Natural program to execute. Specify a value for this field only if the adapter is expected to execute Adabas/Natural programs.
Use data structure information from COBOL	When this parameter is selected, the adapter creates request and response schemas that reflect COBOL group levels (for example, 05, 10, 20, and so on). The COBOL grouping is reflected in the XML request and response schemas. You must select this parameter when COBOL input or output descriptions contain the COBOL OCCURS or REDEFINES statement. Note: When this parameter is selected and there is an OCCURS COBOL statement, you cannot test run an adapter transaction. iWay Explorer returns an "OCCURS in COBOL Data Description" error message.
Accept multiple records in COMMAREA	When this parameter is selected, multiple COMMAREA records are read by the PreParser. Otherwise, any data in excess of the COBOL definition is truncated.

Important: When connecting to a remote server, the location path of the COBOL description must match the operating system path of the machine on which the CICS adapter has been installed. For example, d:\iWay61\Cobol\ is a Windows path, whereas /iWay61/Cobol/ is a UNIX path.

Click the Output COBOL Data Description tab, as shown in the following image.

The Output COBOL Data Description tab allows you to specify the path that corresponds to the message you want returned from the CICS program. This tab contains the following columns:
- COBOL Data Description
- DD Field
- Value
- Side File
For more information on side files, see Side File Support.

If the program can return multiple types of messages, for each output COBOL description, enter the COBOL description field and value to determine the schema to use for a particular message.

iWay Explorer creates the schema to use for a particular message based on the contents of a field that is returned. For example, a program called IWAYSRV0_IN.CBL populates the COMMAREA field called COMMAND. Depending on program logic, iWay Explorer creates the correct response schema.
- Inbound COBOL - IWAYSRV0_IN.CBL
- Outbound COBOL (1) - IWAYSRV0_OUT_L.CBL
  - Field: RECORDTYPE
  - Value: L
- Outbound COBOL (2) - IWAYSRV0_OUT_S.CBL
  - Field: RECORDTYPE
  - Value: S
The IWAYSRV0_OUT_L and IWAYSRV0_OUT_S COBOL descriptions appear in Sample Requests, Schemas, and COBOL File Descriptions.
Click Update when you have finished configuring all the parameters.
The new CICS transaction, for example, IWAYSRV0, is added under the Transactions node for the current target.

Side File Support

A side file is an XML file that contains data handling options for COBOL copybook fields. The format of the side file is described in the iWay Service Manager Component Reference Guide. Refer to the Legacy Record to XML Converter Service (com.ibi.agents.XDLegacyRecordToXMLAgent) section in that guide.

The following image shows the Output COBOL Data Description tab in the Add Service dialog for the iWay Transaction Adapter for CICS. A side file is specified in the Side File column.

You can specify a side file by:

Explicit specification. One side file may be specified for each output COBOL copybook. If specified, the contents of the side file are persisted along with the rest of the transaction information.
Implicit specification. If the directory containing the COBOL copybook also contains a file with the same name as the copybook, and _option is appended, then that file is used as the side file and persisted. For example, if the COBOL copybook is x.cob, and the directory also contains a file x.cob_option, then x.cob_option is assumed to be the side file for the x.cob copybook, and will be persisted.
No specification. If a side file is not specified either explicitly or implicitly, then no side file is used.

COBOL Descriptions for Input and Output Communications

The following are considerationiBSPs for COBOL descriptions for input and output communications. You must use the following syntax for binary, packed, and float fields for the COBOL descriptions for the adapter transaction input and output formats.

For a binary field:

05  BINARY-FIELD         PIC S9(n) COMP.

For a packed-decimal field:

05  PACKED-FIELD         PIC S9(n) COMP-3.

Note: Underscores are not supported in COBOL descriptions.

Modifying COBOL DD Field Definitions

Using iWay Explorer, you can indicate that alpha type fields derived from COBOL DD input will be represented in XML by hex character strings. Specifically, this feature allows you to change the mapping for PIC X fields from XML type “string” to type “hexBinary”. As a result, arbitrary binary data can be transmitted in an XML supported format to CICS applications. This feature is useful when sending flag bits.

The following is an input example:

FLAG1 PIC X

<FLAG>02</FLAG> to transmit byte X’02’

The following is an output example:

CHARS PIC X 4

AAAA is returned as <CHARS>C1C1C1C1</CHARS>

Top of page

Procedure: How to Modify COBOL DD Field Definitions

To modify COBOL DD field definitions:

Open iWay Explorer and connect to your CICS target.
Expand the Transactions node and select a defined transaction.
Right-click the transaction and select Modify DD from the menu.
A sequence of Modify DD dialog boxes open representing the input and output record layouts for the transaction. Each layout includes the Use as Binary column, which allows you to modify an Alpha field.
Select the Alpha field in the table that you want to use as Binary.
Click the Use as Binary column and select yes or no from the drop-down list.
Click Next to browse through the remaining input and output record layouts for the transaction.
Click Done when you are finished to save the Alpha field modifications you made.

HexBinary support is available for input and output transaction records. In particular, input RecType fields can also be defined with binary ‘Value’ arguments. In this case, the 'Value' data must be specified as the hexadecimal representation of the expected field.
Right-click the transaction in the left pane and select Edit from the menu.
The Edit dialog box opens.

Note: Hexadecimal values must be specified before any modifications to Alpha fields are performed. This is required because the Edit dialog box only saves dialog input when you click Update. As a result, the internal COBOL DD representation to be recreated and any prior Alpha field modifications would be lost.