A COBOL batch program which demonstrate how to use the WebSphere Optimized Local Adapters (WOLA) native APIs to register to a z/OS Connect Enterprise Edition (EE) server and host a service.
- z/OS Connect Enterprise Edition is installed and a z/OS Connect EE instance has been created and configured with WOLA. Refer to the z/OS Connect EE documentation in the IBM Knowledge Center for further information on how to create a new z/OS Connect Enterprise Edition Server and using the WOLA service provider. The steps to configure batch for WOLA is similar to configuring CICS to use WOLA.
- Enterprise COBOL Compiler
- Clone this repository
git clone git://github.com/zosconnect/zosconnect-sample-wola-batch.git - Allocate a PDS with 30 tracks for the jobs and source files
Average record unit
Primary quantity . . 30
Secondary quantity 5
Directory blocks . . 10
Record format . . . . FB
Record length . . . . 80
Block size . . . . . 27920
Data set name type PDS
- Allocate a PDSE with 15 tracks for the load module
Average record unit
Primary quantity . . 10
Secondary quantity 5
Directory blocks . . 10
Record format . . . . U
Record length . . . . 0
Block size . . . . . 32760
Data set name type LIBRARY
- Upload the following source and sample JCLs to your z/OS system and store on the PDS that was allocated
runcobol.jcl
baqls2js.jcl
complink.jcl
zconresp.cpy
zconreq.cpy
zconcbl.cbl
- Customize the uploaded copy of complink.jcl for your environment and submit. Additional instructions are provided in the sample JCL. The expected return code is 0.
- Customize the uploaded copy of baqls2js.jcl for your environment and submit. Additional instructions are provided in the sample JCL. The expected return code is 0.
- Create a directory (if not done yet) called dataXform under your server path.
/var/zosconnect/servers/<server-name>/dataXform
- Create the following subdirectories under that
/var/zosconnect/servers/<server-name>/dataXform/json
/var/zosconnect/servers/<server-name>/dataXform/bind
/var/zosconnect/servers/<server-name>/dataXform/sars
- Copy the files generated by the BAQLS2JS job to the directories you just created. At this point, you should have:
/var/zosconnect/servers/<server-name>/dataXform
|
+--/json
| /CobolService_request.json
| /CobolService_response.json
|
+--/bind
| /CobolService.wsbind
|
|--/sars
/CobolService.sar
- Recursively chown and chmod the output directories so your Liberty z/OS server ID has access to them.
cd /var/zosconnect/servers/<server-name>
chown -R <serverID>:<serverGroup> ./dataXform
chmod -R 750 ./dataXform
- Setup definitions for the COBOL batch sample in server.xml. The server.xml should have the following entries added:
<zosconnect_zosConnectAPIs location="">
<zosConnectAPI name=“CobolService”/>
</zosconnect_zosConnectAPIs>
<zosconnect_zosConnectService dataXformRef="xformJSON2Byte"
id="CobolService"
invokeURI="/CobolService"
requireAuth="false"
requireSecure="false"
serviceDescription="Test COBOL batch program"
serviceName="CobolService"
serviceRef="wolaBATCH"/>
<zosconnect_zosConnectDataXform bindFileLoc="/var/zosconnect/servers/<server-name>/dataXform/bind"
bindFileSuffix=".wsbind"
id="xformJSON2Byte"
requestSchemaLoc="/var/zosconnect/servers/<server-name>/dataXform/json"
requestSchemaSuffix=".json"
responseSchemaLoc="/var/zosconnect/servers/<server-name>/dataXform/json"
responseSchemaSuffix=".json">
</zosconnect_zosConnectDataXform>
<zosconnect_localAdaptersConnectService connectionFactoryRef="wolaCF"
id="wolaBATCH"
registerName="COBOLZCON"
serviceName="CobolService"/>
<zosLocalAdapters wolaGroup=“GRPNAME1”
wolaName2=“GRPNAME2”
wolaName3=“GRPNAME3”/>
<connectionFactory id="wolaCF" jndiName="eis/ola">
<properties.ola/>
</connectionFactory>
NOTE: Change the server-name to the actual name of the z/OS Connect instance you created. A sample server.xml is included in the package. If you want to use the sample server.xml file then upload it to z/OS in binary mode to keep the contents in ASCII format.
At this point you have service definitions to match the COBOL service sample provided but do not yet have an API created and deployed.
Before deploying the sample API, import the sample project provided. A sample API archive CobolService.aar is included in the project.
-
On your IBM Explorer for z/OS (or any of the supported Eclipse environment), click on File -> Import then click on General -> Existing Projects into Workspace. Select the CobolService.zip file included in the package (confirm that the CobolService project is selected under the Projects field) and click Finish.
-
To deploy the sample API, follow the steps described in the Deploying an API section of the z/OS Connect EE documentation in the IBM Knowledge Center.
At this point, you are ready to test the sample APIs provided to call the COBOL batch service using z/OS Connect EE.
- Customize the uploaded copy of runcobol.jcl for your environment and submit. Additional instructions are provided in the sample JCL. The job is a long-running batch job and is expected to run until it is cancelled, stopped or an unexpected error occured that forces the job to terminate.
- The following output is displayed on the job log to indicate that the COBOL batch program is ready to accept requests:
========================================
***** ****** *** **** ** **
** *** ** ** ** ** ** ** **
***** ****** ******* ** ** ****
** ** ** ** ** ** ** **
** ** ****** ** ** **** **
========================================
Register Name : COBOLZCON
========================================
Successfully registered into:
GRPNAME1 GRPNAME2 GRPNAME3
========================================
-
To test the API using the z/OS Connect EE API Editor, refer to the section on Examining, testing, starting and stopping an API section of the z/OS Connect EE documentation in the IBM Knowledge Center.
-
To test the POST method using a REST client, use the following:
Method: POST
URL: http://<host>:<port>/CobolService/employee
JSON:
{
"ZCONCBLOperation": {
"svc_rqst_variables": {
"svc_rqst_data": {
"svc_rqst_email": "[email protected]",
"svc_rqst_empid": "12345",
"svc_rqst_remarks": "Sample",
"svc_rqst_empname": "John Doe",
"svc_rqst_phone": "123-456-7890"
}
}
}
}
- To test the GET method using a REST client, use the following:
Method: GET
URL: http://<host>:<port>/CobolService/employee
JSON: No JSON and parameter is used. Only one record is kept by the batch program.
- To test the PUT method using a REST client, use the following:
Method: PUT
URL: http://<host>:<port>/CobolService/employee
JSON:
{
"ZCONCBLOperation": {
"svc_rqst_variables": {
"svc_rqst_data": {
"svc_rqst_email": "[email protected]",
"svc_rqst_empid": "54321",
"svc_rqst_remarks": "Sample Update",
"svc_rqst_empname": "Michael Doe",
"svc_rqst_phone": "111-222-3333"
}
}
}
}
- To test the DELETE method using a REST client, use the following:
Method: DELETE
URL: http://<host>:<port>/CobolService/employee
JSON: No JSON and parameter is used. Only one record is kept by the batch program.
© Copyright IBM Corporation 2016
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.