HOW TO: Cobol 3GL under CICS calling Adapter on the PC

[Costi Zaboura]

<p><strong>DESCRIPTION</strong></p>
<p>The sample shows how to call the 3GL APIs from a Cobol programon the OS/390. The Cobol program is deployed under CICS, and using theACX3GL library of Attunity Connect.</p><br />

<p><strong>PERQUISITES</strong></p>
<ul>
<li>Setup the environment on the Mainframe to work with the ACX3GL library of Attunity Connect.
<li>On the PC side, setup the DotNetTrig sample, or the standard TRIG sample (samples/adapters/com).
<li>Download the sample, which contains the following files:
<p>
<table cellSpacing=2 cellPadding=1 width=677 border=1 height="50">
<tbody>
<tr>
<td vAlign=top width=214>
<p><strong>File Name</strong></p></td>
<td vAlign=top width=447>
<p><strong>Description</strong></p></td></tr>
<tr>
<td vAlign=top width=214><strong>ACXDTRIG.txt</strong></td>
<td vAlign=top width=447>
<p>COBOL 3GL source code</p></td></tr>
<tr>
<td vAlign=top width=214><strong>ACXTJCL.txt</strong></td>
<td vAlign=top width=447>
<p>JCL to compile the COBOL program</p></td></tr>
<tr>
<td vAlign=top width=214><strong>DTRIG.XML</strong></td>
<td vAlign=top width=447>
<p>Schema of the DotNetTrig Adapter</p></td></tr>
<tr>
<td vAlign=top width=214><strong>TRSCHEMA.txt</strong></td>
<td vAlign=top width=447>
<p>Modified schema (Read the GUIDELINES)</p></td></tr>
<tr>
<td vAlign=top width=214><strong>ACXSJCL.txt</strong></td>
<td vAlign=top width=447>
<p>Create the ESDS file containing the schema</p></td></tr></tbody></table></p></li></ul>
<p><strong>SAMPLE FLOW</strong></p>
<ol>
<li>The Cobol program starts by calling the <strong>ACXACNT </strong>API, to connect to the target server (LINE 000730):</li></ol>
<ul>
<ul>
<li>CP-SERVERS-URL: The target IP:PORT of the server.
<li>CP-USERNAME, CP-PASSWORD: authentication if needed.
<li>CP-WORKSPACE: workspace, default to “Navigator“.
<li>CP-ADAPTER: target adapter name, for the .NET Trig example use the default “DotNetTrig“, for the COMAdapter sample specify “Trig“.</li></ul></ul>
<blockquote dir=ltr style="MARGIN-RIGHT: 0px">
<blockquote dir=ltr style="MARGIN-RIGHT: 0px">
<p>Note: You can modify the COBOL code and specify any adapter.</p></blockquote></blockquote>
<ul>
<ul>
<li dir=ltr>CP-SCHEMA-FILE: This parameter specifies the XML Schema file, which was created under CICS (using the <strong>ACXSJCL </strong>script).
<li dir=ltr>CP-ENC-KEY-NAME, CP-ENC-KEY-VALUE:Encryption key and value, when used.</li></ul></ul>
<ol>
<li value=2>Execute the interaction COMPUT (which is the same as comPropertyPut), and set the trigUnit to“DEG“ and the precession to 6, callACXAEXEC&nbsp;(LINE 000890):</li></ol>
<ul>
<ul>
<li>EP-INTERACTION-NAME: Specifies the interaction name to be executed.</li></ul></ul>
<ol>
<li value=3>Execute the CS in interaction with angl=45.(LINE 001060).</li></ol>
<p><strong>SCHEMA GUIDLINES</strong></p>
<p>In this sample, the COBOL program calls an adapter on the PC machine, which is a COMAdapter (but can be any other adapter).</p>
<p>As to the 3GL spec, you should have a copy of the schema locally (on the Mainframe). Follow these steps to generate the correct schema:</p>
<ol>
<li>Export the schema on the PC (DotNetTrig adapter, or the standard TRIG in the samples):</li></ol>
<ul>
<li>nav_util export adapter_def DotNetTrig DTRIG.XML</li></ul>
<ol>
<li value=2>Edit the DTRIG.XML:</li></ol>
<ul>
<li>Remove the second line, starting with 'navobj', and thelast line with the closing tag of 'navobj'.
<li>Remove the 'Encoding' attribute from the first line.
<li>Compact the whole XML file into a single line.
<li>Make sure the last character is a space.</li></ul>
<blockquote dir=ltr style="MARGIN-RIGHT: 0px">
<p>These changes are required in order to build the ESDS file of the schema, in a single record.</p></blockquote>
<ol>
<li value=3>The schema should be uploaded as a <span STYLE="FONT-WEIGHT: bold="">dataset name and not as a&nbsp;member. If you upload the schema as a member, the schema may be corrupt after building the ESDS file.<br />&lt;/span&nbsp;STYLE="FONT-WEIGHT:&gt;
<p dir=ltr>Upload the schema (TRSCHEMA) as:</p>
<ul dir=ltr>
<li>
<div>SUPPORT.CICS3GL.XML</div></li></ul>
<blockquote></blockquote>
<ol dir=ltr>
<li value=2>
<div>Modify the ACXSJCL script (as needed), which generates the ESDS schema file under VSAM:</div></li></ol>
<ul>
<li>Change the DSN of the input schema (SUPPORT.CICS3GL.XML).
<li>Change the output ESDS file (TEST.VSAM.DATA.ACXDTRIG.SCHEMA).
<li>Change the VOLUME of the VSAM (VOL001).</li></ul>
<ol dir=ltr>
<li value=3>
<div>Modify the ACXTJCL script (as needed), which compiles the COBOL program:</div></li></ol>
<ul>
<li>Change the INFILE, to your input COBOL file (ACXDTRIG).
<li>Change the OUTFILE, to your CICS LOAD library.
<li>Change the path for the ACX3GL in the Attunity Connect installation at your machine (TEST.AC4100).
<li>Change the SYSLIB, to your CICS (SDFHLOAD).</li></ul>
<ol dir=ltr>
<li value=4>
<div>Modify the ACXDTRIG as follows:</div></li></ol>
<ul>
<li>Change the the IP to your target machine IP where the DotNetTrig is located. (LINE 00070)
<li>Change the Adapter name if you want to use the standard TRIG example. (LINE 000110)</li></ul>
<p><strong>BUILDING THE SAMPLE</strong></p>
<ol>
<li>Submit the ACXSJCL to create the ESDS file.
<li>Submit the ACXTJCL to compile the COBOL program.</li></ol>
<p>In case of any errors in these steps, refer to the source code of the JCLs, and make sure you've modified them to work in your environment.</p></li></ol>

[agtsounos_us]

are these the same APIs I would use to call BPEL.

In other words, I could modify the COBOL code and specify appropriate adapter and could then communicate with a BPEL process running on my PC?

If not how would you recommend calling a BPEL process

thanks

[Adeeb Mass'ad]

These APIs are standard Attunity ACX APIs which you can use to call the different Attunity Adapters.

This sample calls a COMadapter on the PC, you can easily change the target adapter to be an eventQueue adapter, or simply call a the COMadapter which can perform several actions, including a call to the target eventQueue.

SOLUTION 1 - eventQueue

The Oracle BPEL product includes full support for the Legacy Adapters. This support includes the ability to trigger a process using an Inbound port/channel.

Please, follow the Oracle BPEL documentation for setting up the Inbound process with Legacy Adapters, here are some highlights:-

1. Set up the Attunity Server product and make sure the daemon is up and running.
2. Create an eventQueue using the Studio, including the target "event".
3. Configure BPEL with the Attunity Daemon configurations (server, port, workspace, ...). This is done in the "collaxa-config.xml" (LegacyServer, LegacyPort, etc...).
4. Create a new BPEL process.
5. Drop a Receive port, and a Partner Link.
6. Configure the Partner Link, and click on the "Browse WSIL". Choose the corrent Server, Workspace and your eventQueue.
7. Link the Partner Link and the Receive port, and complete your process.

The eventQueue can be created on the Attunity Server on the same machine where BPEL resides, or even on the Mainframe.

Modify the COBOL 3GL code, to target the MACHINE:PORT where your eventQueue was created:

• Workspace, the workspace of the eventqueue, usually the same name as the eventQueue itself.
• Adapter, the adapter name, usually the same name as the eventQueue itself.
• Interaction, the target event name.
• Schema, the schema of the input format of the event. Follow the steps as it appears in this sample.

SOLUTION 2 - COMadapter

The second solution is using the COMadapter. The sample shows how to call a COMadapter on the PC.

In your COM object you can use the Attunity ACX APIs to perform the task of sending an event to the eventQueue.

If you are writting the COMadapter in .NET you would use the NetACX interface, and if you are writting in VB 6.0 for example, you would use the ComACX.

Both interfaces allow you to contact the Attunity Server, and perform the task of sending the event.

NOTES

• In both solutions the support is Asynchronous, meaning you will not get a response from the triggered process. You should provide your own response mechanism (write to confirm Table, response file, etc...)
• You can test your eventQueue using the Attunity XML Utility (acxDemo). The utility can be used to both send and receive events.

This can be used a a debugging tool to make sure that the eventQueue is working as expected, before starting to create the BPEL process.