Language structure to JSON schema scenario
This chapter describes a scenario that takes an existing Customer Information Control System (CICS) Common Business Oriented Language (COBOL) application, and enables it for use as a JavaScript Object Notation (JSON) web service.
This chapter contains the following topics:
9.1 General insurance sample application
The scenarios in this IBM Redbooks publication use a general insurance application (GENAPP) available with IBMGENAPP CB12 SupportPac (CB12 SupportPac), which can be found on the following web page:
The general insurance application (GENAPP) is a CICS COBOL application that simulates transactions made by an insurance company to create and manage customer and insurance policy data. It provides sample data and an IBM 3270 interface for creating and inquiring about customers and insurance policy information.
The SupportPac documentation describes the application architecture, how to install and set up the application, and how to test the application is working correctly.
For the purposes of the scenarios in Chapter 9, “Language structure to JSON schema scenario” on page 93, and Chapter 10, “JSON schema to language structure scenarios” on page 105, you will require a single CICS region version of the GENAPP. This setup is described in the CB12 SupportPac documentation.
|
Note: When using a single CICS Region, you do not require the coupling facility named counter server, or the shared temporary storage queue.
|
When you have a working application, you can then extend the application to use JSON web services.
9.2 Use case for language structure to JSON
In this scenario, the fictional general insurance company wants to quickly enable a mobile solution for its existing COBOL GENAPP.
The company intends to create an application for mobile devices, implemented in JavaScript and accessing existing CICS and DB2 assets. The initial version of the application will allow customer records to be added to the DB2 database, and for specific records to be queried and updated. It wants to get the solution into the market as soon as possible, and does not currently have the resources to change the existing COBOL application programs.
To resolve the issue, the insurance company is going to enable its existing COBOL applications to use JSON by creating a JSON web service from their existing language structures. In this way the COBOL programs can be left completely unchanged. The following sections of the chapter describe in detail how this will be done using the GENAPP.
9.3 Language Structure to JSON schema solution
Having completed the setup of the GENAPP as described in 9.1, “General insurance sample application” on page 94, you are now in the position to extend the existing GENAPP to make use of JSON web services without changing any of the existing COBOL source or compilations.
This tutorial will configure CICS to enable the following actions:
•Enable a JSON request to create a customer record.
•Enable a JSON request to inquire on a customer record.
•Enable a JSON request to update a customer record.
Perform the following tasks:
1. Identify the general insurance COBOL programs and copybooks to use.
2. Tailor the job control language (JCL) for running DFHLS2JS for the COBOL customer programs.
3. Submit the JCL to create WSBIND files and JSON schemas for each of the listed requests.
4. Set up a PIPELINE to install the WSBIND files and enable a Uniform Resource Identifier (URI) for each request.
5. Test that the JSON request can be successfully performed.
|
Note: It is assumed that you have set up and installed an appropriate JVMServer and TCPIPSERVICE in your CICS region, as described in Chapter 5, “Configuring CICS for the example scenarios” on page 31.
|
9.3.1 Identifying the COBOL programs and copybooks
The three requests that this scenario covers (create, inquire, and update a customer record), are handled in the GENAPP by three COBOL programs.
These can be found in the GENAPP source data set:
<HLQ>.CB12.SOURCE
The following list notes the source code members:
•LGACUS01 (Customer Create program)
•LGICUS01 (Customer Inquiry program)
•LGUCUS01 (Customer Update program)
The GENAPPs are supplied already compiled and installed as programs of the same name in the general insurance load library.
In this scenario, no changes are required to the programs. Instead, you need to create a WEBSERVICE resource that can transform a JSON request to the expected application data.
You need to identify the customer data structure that these programs use to take as input. In three cases the COBOL copybook that they import is LGCMAREA. This copybook is also in the GENAPP source data set.
Looking at the COBOL source code and copybook, you see that the data that you need to be sending to the program is in the CA-CUSTOMER-REQUEST structure, as show in Example 9-1.
Example 9-1 CA-CUSTOMER-REQUEST in LGCMAREA copybook
03 CA-REQUEST-ID PIC X(6).
03 CA-RETURN-CODE PIC 9(2).
03 CA-CUSTOMER-NUM PIC 9(10).
03 CA-REQUEST-SPECIFIC PIC X(32482).
* Fields used in INQ All and ADD customer
03 CA-CUSTOMER-REQUEST REDEFINES CA-REQUEST-SPECIFIC.
05 CA-FIRST-NAME PIC X(10).
05 CA-LAST-NAME PIC X(20).
05 CA-DOB PIC X(10).
05 CA-HOUSE-NAME PIC X(20).
05 CA-HOUSE-NUM PIC X(4).
05 CA-POSTCODE PIC X(8).
05 CA-NUM-POLICIES PIC 9(3).
05 CA-PHONE-MOBILE PIC X(20).
05 CA-PHONE-HOME PIC X(20).
05 CA-EMAIL-ADDRESS PIC X(100).
05 CA-POLICY-DATA PIC X(32267).
|
Note: It is a requirement of the JSON assistants that the data structures are separated from the program code. It also does not support REDEFINEs.
|
The GENAPP already provides support for SOAP web services. You can therefore use the supplied data set member SOAIC01 (shown in Example 9-2), which contains the customer request data structure of interest.
Example 9-2 The Customer Request data structure in SOAIC01
01 CA.
03 CA-REQUEST-ID PIC X(6).
03 CA-RETURN-CODE PIC 9(2).
03 CA-CUSTOMER-NUM PIC 9(10).
* Fields used in INQ All and ADD customer
03 CA-FIRST-NAME PIC X(10).
03 CA-LAST-NAME PIC X(20).
03 CA-DOB PIC X(10).
03 CA-HOUSE-NAME PIC X(20).
03 CA-HOUSE-NUM PIC X(4).
03 CA-POSTCODE PIC X(8).
03 CA-NUM-POLICIES PIC 9(3).
03 CA-PHONE-MOBILE PIC X(20).
03 CA-PHONE-HOME PIC X(20).
03 CA-EMAIL-ADDRESS PIC X(100).
03 CA-POLICY-DATA PIC X(30000).
Having identified the data that the programs require, you look at using this data to generate a JSON schema and a WSBIND file that can be use by a JSON request.
9.3.2 Tailoring DFHLS2JS for the COBOL customer programs
CICS Transaction Server (CICS TS) Feature Pack for Mobile Extensions V1.0 supplies the DFHLS2JS procedure for running the JSON assistants to create a WSBIND file for deployment by your PIPELINE and JSON schemas, which map to the response and requests related to the COBOL data structure.
The DFHLS2JS JCL procedure is found in the Mobile Extensions feature pack installed library, SDFHMOBI. This procedure accepts many parameters, and these are documented in the CICS TS Feature Pack for Mobile Extensions V1.0 Information Center.
For the purpose of this book and this scenario, you will be using a minimum number of parameters to call the DFHLS2JS procedure. In Example 9-3, the JCL needs to be tailored to your environment. Examples of the Inquire Customer and Update Customer assistant JCL are included in Appendix A, “Sample level for a JSON schema” on page 163.
Example 9-3 Sample JCL to run the DFHLS2JS Procedure for Create Customer
//LS2JS JOB 'accounting information',name,MSGCLASS=A
//JCLLIB JCLLIB ORDER=CICS51.SDFHMOBI
//LS2JS EXEC DFHLS2JS,
// JAVADIR='java7',
// USSDIR='fp uss dir’,
// PATHPREF='',
// TMPDIR='/tmp',
// TMPFILE=''
//INPUT.SYSUT1 DD *
PDSLIB=GENAPP.CB12.SOURCE
LANG=COBOL
MAPPING-LEVEL=3.0
PGMNAME=LGACUS01
REQMEM=SOAIC01
RESPMEM=SOAIC01
DATETIME=PACKED15
Log file=/u/cicsuser/genapp/json/logs/LS2JS_LSJSCUSC.LOG
URI=GENAPP/LSJSCUSC
PGMINT=COMMAREA
WSBIND=/u/cicsuser/genapp/json/wsbind/LSJSCUSC.wsbind
JSON-SCHEMA-REQUEST=/u/cicsuser/genapp/json//LGJSCUSCQ.json
JSON-SCHEMA-RESPONSE=/u/cicsuser/genapp/json/LGJSCUSCR.json
/*
|
Note: The values in bold need changing for suitable values when running the DFHLS2JS for the Inquire (LGICUS01) and Update (LGUCUS01) requests. They all use the same SOAIC01 copybook.
|
The following parameters are supplied:
Log file The z/OS file system (zFS) file where a log of the DFHLS2JS processing is created.
PDSLIB The partitioned data set where the language structure source is stored.
PGMNAME The name of the program that the language structure relates to.
LANG The high-level language of the language structure source.
MAPPING-LEVEL The level of mapping applied by the JSON assistant. 3.0 or greater should be used, earlier mapping levels are supported only for compatibility with the SOAP web services assistants.
REQMEM The copybook in the partitioned data set (PDS) specified by the PDSLIB parameter that the request JSON schema is generated from.
RESPMEM The copybook in the PDS specified by the PDSLIB parameter that the response JSON schema is generated from.
DATETIME Specifies if JSON date-time properties in the language structure are mapped as time stamps. PACKED15 indicates that they are mapped as time stamps.
URI Specifies the relative or absolute URI to be used by the client to access the JSON web service.
PGMINT Sets how CICS passes the data to the target program.
WSBIND The zFS file and location of the produced WSBIND file.
JSON-SCHEMA-REQUEST The zFS location of the JSON schema for the request output.
JSON-SCHEMA-RESPONSE The zFS location of the JSON schema for the response output.
Full details of all the parameters for DFHLS2JS can be found in the “DFHLS2JS and high-level language to JSON schema conversion for linkable interface” topic in the CICS TS Feature Pack for Mobile Extensions Information Center, which for CICS TS V5.1 is located at the following website:
Example JCL for the Customer Inquiry (Example A-1 on page 164) is found in Appendix A, “Sample level for a JSON schema” on page 163.
9.3.3 Submitting the DFHLS2JS JCL
Having tailored the JCL to run the DFHLS2JS, submit the JCL for each of the three programs.
A successful execution of the DFHLS2JS will finish with a return code 0. Verify the job output and log file to resolve any problems, should they occur.
The successful completion will create the following artifacts:
•A WSBIND file in the location specified to DFHLS2JS.
•A log file containing diagnostics related to the WSBIND file. You will be asked to supply this file if you need to contact IBM support for assistance.
•A JSON schema that describes the request to CICS.
•A JSON schema that describes the response from CICS.
In the case of a language structure to JSON, the produced response and request schemas will often be identical, because the communication area (COMMAREA) will normally be the same. This is the case in this scenario, however the JSON schema would be different, of course, if the copybooks differed.
The key parts of the generated JSON schema for the Customer Create request are shown in Example 9-4. For the full JSON schema that was produced, see “Sample JSON schema generated from COBOL customer create program” on page 164.
Example 9-4 JSON request schema produced from DFHLS2JS for Customer Create
{
"$schema":"http://json-schema.org/draft-04/schema#",
"description":"Request schema for the LGACUS01 JSON interface",
"type":"object",
"properties":{
"LGACUS01Operation":{
"type":"object",
"properties":{
"ca":{
"type":"object",
"properties":{
"ca_request_id":{
"type":"string",
"maxLength":6
},
"ca_customer_num":{
"type":"integer",
"maximum":9999999999,
"minimum":0
},
.....
},
"required":[
"ca_request_id",
"ca_return_code",
"ca_customer_num",
.....
]
}
},
"required":[
"ca"
]
}
},
"required":[
"LGACUS01Operation"
]
}
The JSON produced by the assistant from the COBOL copybook includes all of the data fields that the program requires for input in the JSON schema.
After the schema and description tags, there is the JSON structure itself. The top element in the language structure to JSON generated schema is always a wrapping operation field. In the customer create example, this is LGACUS01Operation.
After the operation field is the JSON representation of the COBOL data structure from the copybook. Because the original copybook has an 01 CA top-level structure, this is mapped to a JSON object, as is the LGACUS01Operation. In the Customer Create copybook, the data fields that the COBOL program expects are all at level 03. The assistant examines their COBOL data types, and then creates a mapping to a JSON data type.
This results in the COBOL CA-REQUEST-ID field (PIC X(6)) being converted to a JSON string with a maximum length of 6 characters. Conversely, the CA-CUSTOMER-NUM (PIC 9(10)) is mapped to a JSON integer property ranging from 0 - 9999999999.
For more details of language data types and their mappings, see the CICS TS Feature Pack for Mobile Extensions V1.0 Information center.
In addition, the assistant generates a WSBIND file that is used by CICS to transform the JSON request to the application data.
9.3.4 Enabling the JSON Request URI
To enable CICS to accept JSON requests, for the three customer functions of the GENAPP, the PIPELINE must perform a scan of the WSBIND files.
To perform a scan, you should have already created a PIPELINE resource in a CICS region that has permissions to read the zFS location of the WSBIND files directory specified on the WSBIND parameter of the assistants that were run in 9.3.3, “Submitting the DFHLS2JS JCL” on page 98.
Creating a PIPELINE resource is described in Chapter 5, “Configuring CICS for the example scenarios” on page 31.
To perform the PIPELINE scan in CICS Explorer, complete the following steps:
Figure 9-1 IBM CICS Explorer menu for PIPELINE resource
Figure 9-2 IBM CICS Explorer Perform SCAN Operation
The PIPELINE will then scan the pickup directory defined for the resource. This will cause your newly created WSBIND file to be read, and creates the required WEBSERVICE and URIMAP for the JSON web service.
Use CICS Explorer web service operations views to see that these have been created and are in service.
The messages, shown in Example 9-5, are also viewable in the CICS MSGUSR log on a successful PIPELINE scan.
Example 9-5 Example CICS MSGUSR log of PIPELINE Scan success messages
DFHPI0703 I 25/06/2013 10:10:34 IYCKZCCE CICSUSER PIPELINE LSTOJSPI is about to scan the WSDIR directory.
DFHPI0715 I 25/06/2013 10:10:35 IYCKZCCE CICSUSER PIPELINE LSTOJSPI explicit scan has completed. Number of wsbind files found in the
WSDIR directory: 000003. Number of WEBSERVICEs created or updated: 000000. Number of WEBSERVICEs not requiring an update:
000003. Number of failed WEBSERVICE creates or updates: 000000.
Having successfully performed the PIPELINE scans, for each of the three WSBIND files, and created the required resources for the JSON requests, CICS can now accept JSON requests for the customer create, inquire, and update functions of the GENAPP.
9.3.5 Test that the JSON request can be successfully performed
To test the JSON request, use the command-line tool cURL. It is an open source tool that can be downloaded from the following website:
|
Note: For more information about alternative tools to perform this check, see the following website:
|
To complete this scenario, you make three JSON requests to the GENAPP using cURL. Use the following steps to complete this procedure:
1. Send a request to create a customer record. The syntax for cURL to send a test JSON request is composed of the following options:
– The curl option, to run the cURL executable file
– The -v option, for verbose (useful for debugging purposes)
– The -H option, to specify the header (use "Content-Type: application/json")
– The -d option, the JSON data to send
– The URI to send the data to
For the Create Customer request, send some JSON data to the create customer URI.
The data to be sent can be gathered from the JSON schema produced by the assistant. You do not need to send all of the fields in the request, because CICS will populate the fields with blank data where values are not supplied. Then, it is up to the application to handle uninitialized values.
The GENAPP does this and initializes the numeric fields on input. Care must be taken, because failing to handle uninitialized values, and passing this data back, might cause a conversion error on the response. In this scenario, shorten the JSON to just send in the data required by omitting unnecessary string fields.
The data this scenario sent in JSON format is shown in Example 9-6.
Example 9-6 JSON customer create data
{"LGACUS01Operation":{ "ca" : {
"ca_request_id" : "02ACUS",
"ca_first_name" :"anew",
"ca_last_name": "customer",
"ca_dob" :"1970-01-01",
"ca_house_num" :"22",
"ca_postcode" : "ZP1 1EX",
"ca_email_address" : "[email protected]",
}
}
}
This example will need flattening out on the command line, and the quotations escaped.
The command line then looks as per Example 9-7. Change the URI to your CICS JSON customer create URI.
Example 9-7 cURL command line request for create customer request
curl -v -H "Content-Type: application/json" -d {"LGACUS01Operation":{"ca":{"ca_request_id":"02ACUS","ca_first_name":"anew","ca_last_name":"customer","ca_dob":"1970-01-01","ca_house_num":"22","ca_postcode":"ZP11EX",,"ca_email_address":"example@example.
com",}}} http://your.cics.region:30661/GENAPP/LSJSCUSC
Running the cURL command sends the request, of your JSON request, to the PIPELINE resource. There the data will be transformed to the COBOL program. It processes and creates a new customer record in the DB2 database. Having completed the new customer record task, it will then send a response back to the cURL tool with the status of its request and a new customer number. In addition, it includes all of the other customer data described in the JSON responses schema that is produced by the assistant.
Assuming your request was successful, cURL should receive an HTTP 200 OK response, application headers, and data (as shown in Example 9-8).
Example 9-8 Example HTTP 200 OK Success Response with headers returned to cURL
* About to connect() to your.cics.region:3066 (#0)
* Trying 256.256.256.256... connected
> POST /GENAPP/LSJSCUSC HTTP/1.1
> User-Agent: curl/7.23.1 (x86_64-pc-win32) libcurl/7.23.1 OpenSSL/0.9.8r zlib/1
.2.5
> Host: winmvs.host.ibm.com:30610
> Accept: */*
> Content-Type: application/json
> Content-Length: 253
>
* upload completely sent off: 253 out of 253 bytes
< HTTP/1.1 200 OK
< content-type: application/json
< Date: Tue, 18 Jun 2013 09:43:31 GMT
< Server: IBM_CICS_Transaction_Server/5.1.0(zOS)
< Content-Length: 000000000000360
<
{"LGACUS01OperationResponse":{"ca":{"ca_request_id":"02ACUS","ca_return_code":0,
"ca_customer_num":1000106,"ca_first_name":"anew","ca_last_name":"customer","ca_dob":"1970-01-01","ca_house_name":"","ca_house_num":22,"ca_postcode":"ZP11EX","ca_num_policies":0,"ca_phone_mobile":"","ca_phone_home":"","ca_email_address":"[email protected]","ca_policy_data":""}}}
After the headers, the JSON data is returned. This should include a return code of 0, and the new customer number created by your request.
For the purposes of this scenario, the customer number returned was 1000106. You can then use the customer number in a follow-up request to perform an inquiry on this newly created customer.
2. Send a request to inquire on a customer record.
As before, you can shorten the JSON request, and in this case just supply the two integer fields in the request.
In a more readable format of the JSON, the request this scenario sent is as shown in Example 9-9. Note that the operation field (LGICUS01Operation) has changed to the operation field in the generated customer inquiry JSON schema generated by the assistant.
Example 9-9 JSON Customer Inquire data
{"LGICUS01Operation":{ "ca" : {
"ca_customer_num" : "1000106",
}
}
}
The command line then looks as shown in Example 9-10. Again, change the URI to your CICS JSON customer inquiry URI.
Example 9-10 The cURL command-line request for inquire customer request.
curl -v -H "Content-Type: application/json" -d {"LGICUS01Operation":{"ca":{"ca_customer_num":"1000106"}}} http://your.cics.region:30661/GENAPP/LSJSCUSI
On a successful request, the data to be returned will look as shown in Example 9-11. Again, the request returns all of the required fields in the JSON response schema.
Example 9-11 The JSON data returned by the Inquire Request
{"LGICUS01OperationResponse":{"ca":{"ca_request_id":"","ca_return_code":0,"ca_
customer_num":1000106,"ca_first_name":"anew","ca_last_name":"customer","ca_dob":"1970-01-01","ca_house_name":"","ca_house_num":22,"ca_postcode":"ZP1 1EX","ca_num_
policies":0,"ca_phone_mobile":"","ca_phone_home":"","ca_email_address":"[email protected]","ca_policy_data":""}}}
3. Send a request to update a customer record.
Finally, you send a request to update the customer record. In this example, the customer’s house number will be changed from 22 to 42.
You need to send all of the fields back that are populated in the database, because sending blank strings will put a blank string into the customer record on the host database.
So the JSON request looks as shown in Example 9-12.
Example 9-12 Customer Update JSON data
{"LGUCUS01Operation":{ "ca" : {
"ca_request_id" : "01UCUS",
"ca_customer_num" : "1000106",
"ca_first_name" :"anew",
"ca_last_name": "customer",
"ca_dob" :"01-01-1970",
"ca_house_name": "",
"ca_house_num" :"42",
"ca_postcode" : "ZP11EX",
"ca_phone_mobile" : "",
"ca_phone_home" : "",
"ca_email_address" : "[email protected]",
"ca_policy_data" : ""
}
}
}
Change the URI to match your configuration, using cURL command-line format, as shown in Example 9-13.
Example 9-13 The cURL command-line request for update customer request
curl -v -H "Content-Type: application/json" -d {"LGUCUS01Operation":{"ca":{"ca_request_id":"01UCUS","ca_customer_num":"0001000106","ca_first_name":"anew","ca_last_name":"customer","ca_dob":"1970-01-01","ca_house_name":"","ca_house_num":"42","ca_
postcode":"ZP11EX","ca_phone_mobile":"","ca_phone_home":"","ca_
email_address":"[email protected]","ca_policy_data":""}}} http://your.cics.region:30661/GENAPP/LSJSCUSU
A successful request results in the customer’s house number being updated to 42, and the updated record being returned to you.
As can be seen from the JSON that is used in the examples in this chapter, the input structure contains some output-only fields. The reverse might also be true, in that some output data contains input-only data. In addition, the data names are based on the language structure’s original names. These names might not be meaningful to the JSON developer.
To make the JSON schema more meaningful to a JSON application developer, it could be modified to suit the service for which it is being used. If the JSON schema is modified, the WSBIND file and the COBOL structures would need regenerating using DFHJS2LS. This would necessitate the creation of a wrapper application to use this new COBOL interface with the existing COBOL applications. This is described in detail in the scenario in Chapter 10, “JSON schema to language structure scenarios” on page 105.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.