JSON schema to language structure scenarios
This chapter describes how language structures for Common Business Oriented Language (COBOL), PL/I, C, and C++ can be generated from existing JavaScript Object Notation (JSON) schema definitions. Two approaches for calling existing or new Customer Information Control System (CICS) applications incorporating the generated copybooks are explored in detail.
Procedures for calling CICS applications from the JSON web service Request-Response pattern, and from a Representational State Transfer (REST)-conforming (RESTful) JSON web service interface, are provided.
This chapter describes a process known as the top-down scenario, and is of particular relevance where a mobile application is required to interact with a CICS Transaction Server (CICS TS) system from predefined JSON schema definitions.
 
This chapter contains the following topics:
10.1 JSON web services: Request-Response and RESTful
The first part of this chapter provides information about implementation aspects of the Request-Response JSON web service pattern. Two JSON schemas, one for request and a second for response, are used as an example case for this model.
This chapter will then build on the RESTful JSON web service information found in earlier chapters to describe an implementation scenario of several RESTful methods.
 
Note: See the information in 2.4.1, “JSON with feature pack” on page 13, “Request-Response” on page 23, and “RESTful” on page 24, which describe the Request-Response and RESTful JSON web service patterns, and aspects of the CICS implementation of these patterns.
10.2 JSON web services: A use case
In this use case, a company wants to integrate a new mobile application, developed with IBM Worklight, to an existing CICS application, the general insurance application (GENAPP).
The business requirement is for a state of the art mobile application to retrieve customer data from the customer inquiry process contained within GENAPP. In this scenario, the business priority is for a mobile application that is highly intuitive, and that data transfer between the mobile application and CICS is kept to a minimum.
As such, not all of the customer data contained within GENAPP, and stored on a DB2 database, is required by the mobile application. Additionally, given that the GENAPP business logic serves a number of application functions, and that the company has time constraints to deliver the mobile application to the market, no changes are permitted to the base GENAPP application.
A solution to this requirement is for the JSON payload emitted from the mobile application to be processed as a JSON web service by CICS interfacing to GENAPP. This JSON payload could be created from scratch and supplied by the mobile development team, an application design team, or a team of architects. The deliverable is a set of JSON schemas specifying only the data required:
•One for the request payload
•One for the response
The JSON schemas are mapped using the DFHJS2LS utility to COBOL language structures. A wrapper program, in this case written in COBOL and deployed to CICS, is used to map the relevant data items in the wrapper program to the format expected by GENAPP. Therefore, no changes are required to GENAPP itself.
The technique described, known as the top-down approach, processes existing JSON schema to create traditional language structures. It should be noted that the scenario described interfaces to an existing CICS application. However, the top-down approach, given that it creates traditional language structures (such as copybooks and the relevant CICS artifacts) is equally applicable for writing functions in new CICS applications.
The following sections in this chapter describe how this scenario can be implemented by integrating a JSON web service with GENAPP. A step-by-step approach is described, and shows how this business requirement is achieved by both a Request-Response and a RESTful approach.
Figure 10-1 shows how the DFHJS2LS utility processes the JSON schema, and generates both the appropriate language structures and the associated WSBIND file.
Figure 10-1 DFHJS2LS utility processing
10.3 Request-Response JSON web service implementation
This section details the step-by-step process in implementing the business scenario previously described.
At the end of this section, you will have processed an incoming JSON web service request, potentially arriving from a mobile device, to perform a customer inquiry request to GENAPP. Data returned from the GENAPP customer inquiry request is returned in JSON format.
The following tasks are performed:
1. A review of the incoming and outgoing JSON schema.
2. The definition of the necessary parameters as input to the JSON assistant that maps the JSON schema to the language structure.
3. The development of the CICS wrapper program that performs the transformation between the language structures created by the JSON assistant and the COBOL format required by GENAPP.
4. The definition of the necessary CICS resources, and execution of the PIPELINE scan operation.
5. Testing of the JSON web service to application transformation when starting a GENAPP customer inquiry request.
10.3.1 Reviewing the JSON schema
The mobile development team has created a functional mobile application that is required to interface to the CICS GENAPP application through defined JSON schema interfaces. To facilitate lightweight data transfer, the request schema is required to contain only a couple of elements. This is a key advantage of the JSON schema to language structure mapping process, in that only the JSON elements that are specifically required need to be defined, and can be mapped to a new or existing language structure (for example, a COBOL copybook).
This contrasts with the language structure to JSON schema mapping process, as described in Chapter 9, “Language structure to JSON schema scenario” on page 93, whereby the JSON schema elements are generated for each and every defined data item in the language structure.
Similarly, the response schema contains only the elements required to satisfy the mobile application. Note also that, in terms of naming conventions and data length, there is no direct relationship between the elements defined in the schema and data definition in the existing GENAPP COBOL copybook.
The request JSON schema and an extract of the response JSON schema definitions follow. See Example 10-1 and Example 10-2.
 
Note: The request and response JSON schema definitions are provided in full in the additional materials that accompany this IBM Redbooks publication.
Example 10-1 Request JSON schema definition
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "JSON request schema for Customer Inquiry",
"type": "object",
"properties": {
"cust_inquiry_request": {
"type": "object",
"properties": {
"function_request_id": {
"type": "string",
"minLength": 15,
"maxLength": 15
},
"cust_number": {
"type": "integer",
"maximum": 9999999999,
"minimum": 0
}
},
"required": [
"function_request_id",
"cust_number"
]
}
},
"required": [
"cust_inquiry_request"
]
}
 
Example 10-2 Extract of response JSON schema definition
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "JSON response schema for Customer Inquiry",
"type": "object",
"properties": {
"cust_inquiry_response": {
"type": "object",
"properties": {
"ret_code": {
"type": "integer",
"maximum": 999,
"minimum": 0
},
"cust_number": {
"type": "integer",
"maximum": 9999999999,
"minimum": 0
},
"first_name": {
"type": "string",
"minLength": 20,
"maxLength": 20
},
"last_name": {
"type": "string",
"minLength": 20,
"maxLength": 20
},
"date_of_birth": {
"type": "string",
"minLength": 10,
"maxLength": 10
......
 
When provided by the mobile development team, the request and response JSON schemas are uploaded, using File Transfer Protocol (FTP) or another mechanism, to an appropriate directory in the z/OS UNIX directory structure (z/OS File System, or zFS). For example, this could include the following directories:
/u/cicsuser/genapp/json/CustInquiryRequest.jsanon
/u/cicsuser/genapp/json/CustInquiryResponse.json
The uploaded JSON schema forms the input to the JSON assistant that performs the mapping between the JSON schema and the language structures.
10.3.2 Mapping the JSON schema to language structures
The CICS TS Feature Pack for Mobile Extensions V1.0 contains JSON assistant utilities that can be used in the creation of service provider applications derived from JSON schema.
 
Note: See the “Creating a service provider application from a JSON schema” topic in the CICS TS Information Center. It provides a full list of prerequisite configuration information needed before running the JSON assistant utility. This information, for CICS TS 5.1, can be found at the following website:
The DFHJS2LS batch program is supplied in the SDFHMOBI data set supplied with the CICS TS Feature Pack for Mobile Extensions V1.0.
This batch program is used to generate a web service bind file and the appropriate language data structures. DFHJS2LS contains a large set of optional parameters that are fully documented in the CICS TS Information Center.
Example 10-3 shows the batch processing of the JSON schema (previously uploaded), and creates two COBOL copybook files.
Example 10-3 Sample JCL for the DFHJS2LS batch procedure
//JS2LSGRR JOB ,,CLASS=A,REGION=900M,
// MSGCLASS=H,NOTIFY=&SYSUID
//*
//********************************************************
//* JSON to language structure conversion routine
//********************************************************
//*
//JS2LS JCLLIB ORDER=(CICS51.SDFHMOBI)
// EXEC DFHJS2LS,
// JAVADIR='java/J7.0_64/J7.0_64',
// PATHPREF='',
// USSDIR='uss dir',
// TMPDIR='/tmp',
// TMPFILE=''
//INPUT.SYSUT1 DD *
PDSLIB=USER.JS2LS.COPYLIB
LANG=COBOL
MAPPING-LEVEL=3.0
MAPPING-OVERRIDES=UNDERSCORES-AS-HYPHENS
PGMINT=COMMAREA
PGMNAME=GENAJSNW
REQMEM=JSONRQ
RESPMEM=JSONRP
URI=/genapp/CustInquiry
LOGFILE=/u/cicsuser/genapp/json/logs/CustInquiry.log
WSBIND=/u/cicsuser/genapp/json/wsbind/CustInquiry.wsbind
JSON-SCHEMA-REQUEST=/u/cicsuser/genapp/json/CustInquiryRequest.json
JSON-SCHEMA-RESPONSE=/u/cicsuser/genapp/json/CustInquiryResponse.json
/*
Some of the key parameters referenced in the DFHJS2LS utility, shown in Example 10-3, are described in the Table 10-1.
Table 10-1 Key parameters referenced in the DFHJS2LS utility
Parameter
Description
PDSLIB
Specifies the name of the partitioned data set that contains the generated high-level language structure, for example, the generated COBOL copybooks.
LANG
Specifies the programming language of the high-level language structure, for example, COBOL. DFHJS2LS can generate COBOL, C/C++, or PL/I language data structures.
MAPPING-LEVEL
The value of 3.0 should be used as the mapping level to generate JSON schema. MAPPING-LEVEL specifies the level of mapping that DFHJS2LS uses when generating the WSBIND file and language structure.
MAPPING-OVERRIDES
Set as UNDERSCORES-AS-HYPHENS. This parameter value converts any underscores in the Web Services Description Language (WSDL) document to hyphens, rather than the character X, to improve the readability of the generated COBOL language structures.
PGMNAME
Specifies the CICS PROGRAM resource name of the application program, such as the CICS wrapper program that is to be linked to when the service is called.
PGMINT
For a service provider, specifies how CICS passes data to the target application program, either in a CHANNEL or communication area (COMMAREA).
REQMEM
Specifies a 1 - 6 character prefix that DFHJS2LS uses to generate the names of the partitioned data set members that contain the high-level language structures for the web service request, which is the input data to the application program.
RESPMEM
Specifies a 1 to 6 character prefix that DFHJS2LS uses to generate the names of the partitioned data set members that contain the high-level language structures for the web service response, which is the output data from the application program.
URI
This parameter specifies the relative Uniform Resource Identifier (URI) that a client uses to access the web service. CICS uses this when installing the web service as part of a PIPELINE scan operation.
LOGFILE
The fully qualified zFS name of the file into which DFHJS2LS writes its activity log and trace information.
WSBIND
The fully qualified zFS name of the web service bind file to be created.
JSON-SCHEMA-REQUEST
The fully qualified zFS name of the location where the request JSON schema is stored.
JSON-SCHEMA-RESPONSE
The fully qualified zFS name of the location where the response JSON schema is stored.
 
Note: For more information regarding the JSON to language structure mapping data types, see the “High-level language and JSON schema mapping” topic in the CICS TS Information Center.
10.3.3 Submitting the DFHJS2LS JCL
After configuration of the DFHJS2LS JSON assistant, the job should be submitted to the Job Entry Subsystem (JES) queue, and its return code checked for a successful execution, with a return code value of 0. If a return code value of 0 is not returned, investigate the causes of the failure. In the event of an error, messages are produced in the job log, and they can be a useful source of diagnostic information for further analysis and investigation.
On successful execution, CICS generates the WSBIND file and places it in the location specified by the WSBIND parameter.
The COBOL language structures are also created and placed in the partitioned data set specified by the PDSLIB parameter, prefixed by the values provided in the REQMEM and RESPMEM parameters.
An extract of the COBOL copybook, generated as a result of processing the request JSON schema, is shown in Example 10-4.
Example 10-4 Generated DFHJS2LS language structure
06 cust-inquiry-request.
09 function-request-id PIC X(15).
09 cust-number PIC 9(10) DISPLAY.
The data names and the data item-level information contained in the generated copybook can be manually amended to adhere to site standards. However, it is important that no changes to the actual data definitions or order of the data items are made, because this will negate the mapping of the language structures contained within the WSBIND file.
10.3.4 Developing the CICS wrapper application program
The COBOL copybooks have been generated and can now be included in a CICS wrapper program. The function of the wrapper program is to map the COBOL data structures defined in the language structure copybooks to a format that is recognizable by an existing CICS application.
At this point, create a new CICS wrapper program, GENAJSNW, that will map the generated language structure copybooks into a format that GENAPP can process.
An evaluation of how data is passed to the wrapper program is done during the design stage. For example, if the PGMINT parameter was set to COMMAREA in the DFHJS2LS batch procedure, standard COMMAREA processing will have to be included in the wrapper program logic. Similarly, if CHANNEL was specified as the value for PGMINT, channel and container logic should be included in the CICS wrapper program.
Compile the CICS wrapper program using standard compilation procedures, and ensure that the program is in a data set referenced in the DFHRPL concatenation or referenced by a LIBRARY resource.
 
Note: The content of the CICS wrapper program, GENAJSNW in this example, is provided in the additional materials that accompany this IBM Redbooks publication.
10.3.5 Defining the CICS resources
For the compiled CICS wrapper program, if the CICS autoinstall facility is not used, create a new PROGRAM or LIBRARY definition for the GENAJSNW program using CICS Explorer. Define the Program Type as Assembler, C/C++, COBOL, or PL/I.
The DFHJS2LS JSON assistant generated the WSBIND file and placed it in the location specified by the WSBIND parameter. The generated web service bind file should be copied to the pickup directory of the provider mode PIPELINE resource that you want to use for your web service application.
 
Note: Details about creating a PIPELINE configuration can be found in 5.2.2, “How to configure CICS as a service provider” on page 34.
A PIPELINE scan operation should now be performed:
1. Select the appropriate PIPELINE definition in CICS Explorer.
2. Right-click to view options, and select the SCAN operation, as shown in Figure 10-2.
Figure 10-2 Pipeline SCAN operation
The PIPELINE scan operation will dynamically create the WEBSERVICE resource and URIMAP resource. The WEBSERVICE resource encapsulates the web service bind file in CICS, and is used at run time. The URIMAP resource provides CICS with the information to associate the WEBSERVICE resource with a specific URI to accept JSON requests for the GENAPP function.
After the PIPELINE scan operation, validate that the URIMAP and WEBSERVICE resources have been correctly installed into CICS. Using CICS Explorer, use the URI Maps and web service views, as shown in Figure 10-3 and Figure 10-4 on page 114.
Specifically, the CICS WEBSERVICE definition is shown in Figure 10-3.
Figure 10-3 CICS WEBSERVICE definition
Specifically, the CICS URIMAP definition is shown in Figure 10-4.
Figure 10-4 CICS URIMAP definition
Note that the name of the WEBSERVICE is derived from the name of the WSBIND file. The path setting, in the URIMAP, is obtained from the URI parameter in the DFHJS2LS batch procedure.
Results of the PIPELINE scan operation can also be obtained by viewing the CICS MSGUSR log. Messages will be produced to indicate a successful generation of the WEBSERVICE, or diagnostic information will be produced for further analysis and investigation.
10.3.6 Testing the application
 
Note: See Chapter 10, section 10.3.5, for details of the cURL utility that is used to test the Request-Response JSON web service.
Our application is now ready for testing. To test our scenario, we will send a single function (getCustomer) to retrieve customer data from GENAPP. The JSON payload that is sent to CICS for processing is displayed in Example 10-5.
Example 10-5 JSON web service payload for GENAPP customer retrieval
{
"cust_inquiry_request": {
"function_request_id": "getCustomer",
"cust_number": 9
}
}
The JSON web service request in Example 10-5 sends the getCustomer request to CICS to retrieve customer inquiry data for a specific customer (account number 9).
Because cURL is a command-line tool, the command line requires flattening out to the command line and the quotations escaped. The resulting command line is shown in Example 10-6.
Example 10-6 The cURL command line for GENAPP customer retrieval
curl -v -H "Content-Type: application/json" -X POST -d {"cust_inquiry_request":{"function_request_id":"getCustomer","cust_number":"0000000009"}} http://your.cics.region:30661/genapp/CustInquiry
Running this command file will send the JSON web service payload to the CICS PIPELINE using the URI specified. The WSBIND file is processed, the JSON web service request is transformed to application data, and the CICS wrapper program is started. The CICS wrapper program maps the COBOL data into a structure that is suitable for processing by GENAPP.
After standard GENAPP processing, in which the appropriate customer information is retrieved, the CICS wrapper program will again convert the GENAPP format data structures into a COBOL format. The COBOL format is transformed to JSON web service data for returning to the cURL process.
Successful invocation of the cURL command file results in a 200 OK status response, with the customer inquiry data returned from GENAPP, as per Example 10-7.
Example 10-7 Invocation of the CustInquiryRequest command file
> POST /genapp/CustInquiry 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: your.cics.region:30661
> Accept: */*
> Content-Type: application/json
> Content-Length: 89
>
* upload completely sent off: 89 out of 89 bytes
< HTTP/1.1 200 OK
< content-type: application/json
< Date: Mon, 17 Jun 2013 16:04:12 GMT
< Server: IBM_CICS_Transaction_Server/5.1.0(zOS)
< Content-Length: 000000000000183
<
{"cust_inquiry_response":{"ret_code":0,"cust_number":9,"first_name":"Micky","last_name":"Murphy",
"date_of_birth":"1966-01-03","zipcode":"CA316RN","cell_number":
"","email_address":""}}* Connection #0 to host your.cics.region left intact
* Closing connection #0
Note: The content of the CustInquiryRequest command file is provided in the additional materials that accompany this IBM Redbooks publication.
10.4 RESTful JSON web service implementation
This section details the step-by-step process used in implementing the business scenario, described in 10.2, “JSON web services: A use case” on page 106, but this time taking advantage of the RESTful capabilities available with JSON web services.
REST defines a set of architectural principles by which you can design web services that focus on a system's resources, including how resource states are addressed and transferred over Hypertext Transfer Protocol (HTTP).
The example in this book demonstrates some of the key design elements regarding the implementation of a RESTful web service:
•It uses HTTP methods explicitly.
•It is stateless.
•It transfers JSON.
As such, a one-to-one mapping between create, read, and update operations to HTTP methods is used.
This mapping uses the following commands:
POST To create a resource on the server (a new GENAPP customer).
GET To retrieve a resource (an existing new GENAPP customer).
PUT To change the state of a resource or to update it (an existing new GENAPP customer).
At the end of this section, the scenario has processed an incoming JSON web service request, potentially arriving from a mobile device, to perform a number of customer operations. Those operations include customer inquiry request, customer update, and the addition of new customer information. Data returned from these GENAPP customer operations is returned in JSON format.
The following tasks will be performed:
1. Reviewing the JSON schema used for the RESTful operations
2. Defining the necessary parameters as input to the JSON assistant that maps the JSON schema to the language structure for RESTful processing
3. Developing the CICS wrapper program that performs the transformation between the language structures created by the JSON assistant and the COBOL format required by GENAPP
4. Defining the necessary CICS resources, and executing the PIPELINE scan operation
5. Testing the JSON web service to application transformation when starting GENAPP customer operations
10.4.1 Reviewing the JSON schema
The mobile development team has created a functional mobile application that is required to interface to the CICS GENAPP application through a defined JSON schema interface. Unlike the Request-Response scenario, a single JSON schema definition is processed for RESTful processing, and is used for both input and output operations.
An extract of the RESTful JSON schema is included in Example 10-8.
Example 10-8 Extract of the CustService JSON schema for RESTful processing
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "JSON restful schema for Customer Operations",
"type": "object",
"properties": {
"cust_details": {
"type": "object",
"properties": {
"cust_number": {
"type": "integer",
"maximum": 9999999999,
"minimum": 0
},
"first_name": {
"type": "string",
"minLength": 20,
"maxLength": 20
},
"last_name": {
"type": "string",
"minLength": 20,
"maxLength": 20
},
"date_of_birth": {
"type": "string",
"minLength": 10,
"maxLength": 10
},
"zipcode": {
"type": "string",
"minLength": 8,
"maxLength": 8
},
.....
Note: The JSON schema definition for RESTful processing is provided in full in the additional materials that accompany this IBM Redbooks publication
When provided by the mobile development team, the JSON schema for RESTful processing is uploaded, via FTP or another mechanism, to an appropriate directory in the zFS (for example, in the following directory):
/u/cicsuser/genapp/json/CustService.json
The uploaded JSON schema forms the input to the JSON assistant that performs the mapping between the JSON schema and the language structures.
10.4.2 Mapping the JSON schema to language structures
The CICS TS Feature Pack for Mobile Extensions V1.0 contains JSON assistant utilities that can be used in the creation of service provider applications derived from JSON schema. Artifacts, created by the JSON assistants, apply to both the Request-Response and RESTful JSON web service patterns, and in the development of a JSON web service client application.
 
Note: See the “Creating a service provider application from a JSON schema” topic in the CICS TS Information Center for a list of prerequisite configuration information before running the JSON assistant.
The DFHJS2LS batch program is provided in the SDFHMOBI data set supplied with the CICS TS Feature Pack for Mobile Extensions V1.0. This batch program is used to generate a web service bind file and the appropriate language data structures. DFHJS2LS contains a large set of optional parameters that are fully documented in the CICS TS Information Center.
The job control language (JCL) shown in Example 10-9 processes the JSON schema for RESTful JSON web service processing that was previously uploaded, and creates a COBOL copybook.
Example 10-9 Sample JCL for the DFHJS2LS batch procedure for RESTful processing
//JS2LSGRS JOB ,,CLASS=A,MSGCLASS=A,NOTIFY=&SYSUID
//*
//********************************************************
//* JSON schema to wsbind conversion routine
//********************************************************
//*
//JS2LS JCLLIB ORDER=(CICS51.SDFHMOBI)
// EXEC DFHJS2LS,
// JAVADIR='java/J7.0_64/J7.0_64',
// PATHPREF='',
// USSDIR='uss dir',
// TMPDIR='/tmp',
// TMPFILE=''
//INPUT.SYSUT1 DD *
PDSLIB=USER.JS2LS.COPYLIB
PDSMEM=GENRST
MAPPING-LEVEL=3.0
MAPPING-OVERRIDES=UNDERSCORES-AS-HYPHENS
CHAR-VARYING=NO
LANG=COBOL
PGMNAME=GENARSTW
PGMINT=CHANNEL
HTTP-METHODS=GET,POST,PUT
URI=/genapp/CustService/*,
LOGFILE=/u/cicsuser/genapp/json/logs/CustService.log
WSBIND=/u/cicsuser/genapp/json/wsbind/CustService.wsbind
JSON-SCHEMA-RESTFUL=/u/cicsuser/genapp/json/CustService.json
/*
Some of the key parameters referenced in the DFHJS2LS batch procedure in Example 10-9 on page 117 are described in Table 10-2.
Table 10-2 Referenced key parameters
Parameter
Description
PDSLIB
Specifies the name of the partitioned data set that contains the generated high-level language structure (for example, the generated COBOL copybooks).
LANG
Specifies the programming language of the high-level language structure (for example, COBOL). DFHJS2LS can generate COBOL, C/C++, or PL/I language data structures.
MAPPING-LEVEL
The value of 3.0 should be used as the mapping level to generate JSON schema. MAPPING-LEVEL specifies the level of mapping that DFHJS2LS uses when generating the WSBIND file and language structure.
MAPPING-OVERRIDES
Set as UNDERSCORES-AS-HYPHENS. This parameter value converts any underscores in the WSDL document to hyphens, rather than the character X, to improve the readability of the generated COBOL language structures.
PGMNAME
Specifies the CICS PROGRAM resource name of the application program, such as the CICS wrapper program that is to be linked to when the service is called.
PGMINT
For a service provider, specifies how CICS passes data to the target application program, either in a CHANNEL or COMMAREA.
PDSMEM
Specifies a 1 - 6 character prefix that DFHJS2LS uses to generate the name of the partitioned data set member that contains the high-level language structures for the web service request, which is the input data to the application program.
HTTP-METHODS
If a value is provided, DFHJS2LS builds a WSBIND file in which only the explicitly specified HTTP methods are accepted. The default value is for GET, POST, PUT, and DELETE to be set, which tells DFHJS2LS that the application supports the four main RESTful operations.
URI
This parameter specifies the relative URI that a client uses to access the web service. CICS uses this when installing the web service as part of a PIPELINE scan operation.
LOGFILE
The fully qualified zFS name of the file into which DFHJS2LS writes its activity log and trace information.
WSBIND
The fully qualified zFS name of the web service bind file to be created.
JSON-SCHEMA-RESTFUL
The fully qualified zFS name of the location where the RESTful JSON schema is stored.
 
Note: For more information regarding the JSON to language structure mapping data types, see the “High-level language and JSON schema mapping” topic in the CICS TS Information Center.
10.4.3 Submitting the DFHJS2LS JCL
After configuration of the DFHJS2LS JSON assistant utility, the job should be submitted to the JES queue, and its return code checked for a successful execution with a return code value of 0. If a return code value of 0 is not returned, investigate the causes of the failure. In the event of an error, messages are produced in the job log, and they can be a useful source of diagnostic information for further analysis and investigation.
On successful execution, CICS generates the WSBIND file and places it in the location specified by the WSBIND parameter. The COBOL language structures are also created, and are placed in the partitioned data set specified by the PDSLIB parameter, prefixed by the value provided in the PDSMEM parameter.
An extract of the COBOL copybook generated as a result of processing the RESTful JSON schema is included in Example 10-10.
Example 10-10 Extract of DFHJS2LS generated COBOL copybook for RESTful processing
06 cust-details.
09 cust-number PIC 9(10) DISPLAY.
09 first-name PIC X(20).
09 last-name PIC X(20).
09 date-of-birth PIC X(10).
09 zipcode PIC X(8).
09 cell-number PIC X(20).
09 email-address PIC X(40).
 
The data names and the data item-level information contained in the generated copybook can be manually amended to adhere to site standards. However, it is important that no changes to the actual data definitions or order of the data items are made, because this negates the mapping of the language structures contained within the WSBIND file.
10.4.4 Developing the CICS wrapper application program
The COBOL language structure copybook for RESTful processing was created, and it can now be included in a CICS wrapper program. The function of the wrapper program is to map the COBOL data structures defined in the language structure copybooks to a format that is recognizable by a new or existing CICS application.
A new CICS wrapper program, GENARSTW, is created, and it maps the generated language structure copybook into a format that GENAPP can process. GENARSTW then processes inbound JSON web service requests that are started using RESTful method formats. Note that in the sample GENARSTW CICS wrapper program (Example 10-11), the HEAD and DELETE RESTful methods are not supported.
Example 10-11 Code sample from the GENARSTW COBOL wrapper program
*****************************************************************
* Perform the method
*****************************************************************
PROCESS-METHOD.
EVALUATE WS-HTTP-METHOD
WHEN METHOD-GET
PERFORM GET-DATA
WHEN METHOD-PUT
PERFORM PUT-DATA
WHEN METHOD-POST
PERFORM POST-DATA
WHEN OTHER
EXEC CICS ABEND
ABCODE(UNSUPPORTED-METHOD-ABCODE)
END-EXEC
END-EVALUATE.
Compile the CICS wrapper program using standard compilation procedures, and ensure that the program is in a data set referenced in the DFHRPL concatenation, or referenced by a LIBRARY resource.
 
Note: The content of the CICS wrapper program, GENARSTW in this example, is provided in the additional materials that accompany this IBM Redbooks publication.
10.4.5 Defining the CICS resources
If the CICS autoinstall facility is not used for the compiled CICS wrapper program, create a new PROGRAM or LIBRARY definition for the GENAJSNW program using CICS Explorer. Define the Program Type as Assembler, C/C++, COBOL, or PL/I.
The DFHJS2LS JSON assistant generates the WSBIND file and places it in the location specified by the WSBIND parameter. The generated web service bind file should be copied to the pickup directory of the provider mode PIPELINE resource that you want to use for your web service application.
 
Note: Details about creating a PIPELINE configuration can be found in the section How to configure CICS as a service provider in Chapter 5, “Configuring CICS for the example scenarios” on page 31.
A PIPELINE scan operation should now be performed:
1. Select the appropriate PIPELINE definition in CICS Explorer.
2. Right-click to view options.
3. Select the SCAN operation, as shown in Figure 10-5.
Figure 10-5 Pipeline scan operation
The PIPELINE scan operation will dynamically create the WEBSERVICE resource and URIMAP resource. The WEBSERVICE resource encapsulates the web service bind file in CICS, and is used at run time. The URIMAP resource provides CICS with the information to associate the WEBSERVICE resource with a specific URI to accept JSON requests for the GENAPP function.
After the PIPELINE scan operation, validate that the URIMAP and WEBSERVICE resources have been correctly installed to CICS. Using CICS Explorer, use the URI Maps and web service views as per Figure 10-6 and Figure 10-7 on page 122.
Specifically, CICS WEBSERVICE is shown in Figure 10-6.
Figure 10-6 CICS WEBSERVICE definition
Specifically, CICS URIMAP is shown in Figure 10-7.
Figure 10-7 CICS URIMAP definition
Note that the name of the WEBSERVICE is derived from the name of the WSBIND file. The path setting in the URIMAP is obtained from the URI parameter in the DFHJS2LS batch procedure.
Results of the PIPELINE scan operation can also be obtained by viewing the CICS MSGUSR log. Messages are produced to indicate a successful generation of the WEBSERVICE, or diagnostic information is produced for further analysis and investigation.
10.4.6 Testing the application
 
Note: See 9.3.5, “Test that the JSON request can be successfully performed” on page 101, for details of the cURL utility that is used to test the RESTful JSON web service.
The application is now ready for testing. To test the scenario, you send various RESTful functions to process GENAPP from various cURL command files.
RESTful customer inquiry function
The JSON web service payload is sent to CICS for processing to start the customer inquiry function as a RESTful service.
Because cURL is a command-line tool, the command line requires flattening out to the command line and the quotations escaped. The resulting command line is displayed in Example 10-12.
Example 10-12 The cURL command line for the CustServiceREST_GET command file
curl -v -H "Content-Type: application/json" -X GET http://your.cics.region:30661/genapp/CustService/0000000009
The JSON web service request (Example 10-12 on page 122) sends a single function to CICS to retrieve customer inquiry data for a specific customer (account number 9).
The CICS wrapper program obtains the customer number by accessing CICS containers available for processing web services, such as DFHWS-URIMAPPATH. The code sample in Example 10-13 demonstrates an access of one such container.
Example 10-13 Sample DFHWS-URIMAPPATH container access
*****************************************************************
* Get containers
*****************************************************************
GET-RESID.
MOVE ' ' TO WS-RESID
EXEC CICS GET CONTAINER('DFHWS-URIMAPPATH')
INTO(WS-RESID)
RESP(RESP)
RESP2(RESP2)
END-EXEC
Note, in keeping with RESTful processing convention, the service name, CustService, is generic, and the operation to be performed, GET, is specified as an HTTP method. This supports reuse of the JSON web service.
Running this command file sends the JSON web service payload to the CICS PIPELINE using the URI specified. The WSBIND file is processed, the JSON web service request is transformed to application data, and the CICS wrapper program is started. The CICS wrapper program maps the COBOL data into a structure that is suitable for processing by GENAPP.
After standard GENAPP processing, in which the customer account information is retrieved, the CICS wrapper program converts the GENAPP format data structures into a COBOL format. That format can be mapped to JSON web service data for returning to the cURL process.
Successful invocation of the cURL command file results in a 200 OK status response, with the customer inquiry data returned from GENAPP, as shown in Example 10-14.
Example 10-14 Invocation of the CustServiceREST_GET command file
> GET /genapp/CustService/0000000009 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: your.cics.region:30661
> Accept: */*
> Content-Type: application/json
>
< HTTP/1.1 200 OK
< content-type: application/json
< Date: Wed, 19 Jun 2013 12:38:35 GMT
< Server: IBM_CICS_Transaction_Server/5.1.0(zOS)
< Content-Length: 000000000000161
<
{"cust_details":{"cust_number":9,"first_name":"Micky","last_name":"Murphy","date
_of_birth":"1966-01-03","zipcode":"CA316RN","cell_number":"","email_address":""}
}* Connection #0 to host your.cics.region left intact
* Closing connection #0
Note: The content of the CustServiceREST_GET command file, for running in a Microsoft Windows environment, is provided in the additional materials that accompany this IBM Redbooks publication.
RESTful customer update function
The JSON web service payload, which is sent to CICS for processing to start the customer update function as a RESTful service, is displayed in Example 10-15.
Example 10-15 JSON web service payload
{
"cust_details": {
"first_name": "James",
"last_name": "Smith",
"date_of_birth": "2001-01-01",
"zipcode": "SO212JN",
"cell_number": "07756576667",
"email_address": "[email protected]"
}
}
Because cURL runs on a command-line basis, the JSON web service payload, in Example 10-15, requires flattening out to the command line and the quotations escaped. The resultant command line is displayed in Example 10-16.
Example 10-16 The cURL command line for the CustServiceREST_PUT command file
curl -v -H "Content-Type: application/json" -X PUT -d {"cust_details":{"first_name":"James","last_name":"Smith","date_of_birth":"2001-01-01","zipcode":"SO212JN","cell_number":"07756576667","email_address":"[email protected]"}} http://your.cics.region:30661/genapp/CustService/0000000009
The JSON web service request, shown in Example 10-16, sends a request to CICS to update customer inquiry data for a specific customer (account number 9).
Note, in keeping with RESTful processing convention, that the service name, CustService, is generic, and the operation to be performed, PUT, is specified as an HTTP method. This enables reuse of the web service.
Running this command file sends the JSON web service payload to the CICS PIPELINE using the URI specified. The WSBIND file is processed, the JSON web service request is transformed to application data, and the CICS wrapper program is started. The CICS wrapper program maps the COBOL data into a structure that is suitable for processing by GENAPP.
After standard GENAPP processing, in which the customer account information is updated, the CICS wrapper program converts the GENAPP format data structures into a COBOL format. This format can be mapped to JSON web service data for returning to the cURL process.
Successful invocation of the cURL command file results in a 200 OK status response, as shown in Example 10-17.
Example 10-17 Invocation of the CustServiceREST_PUT command file
> PUT /genapp/CustService/0000000009 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: your.cics.region:30661
> Accept: */*
> Content-Type: application/json
> Content-Length: 182
>
* upload completely sent off: 182 out of 182 bytes
< HTTP/1.1 200 OK
< content-type: application/json
< Date: Wed, 19 Jun 2013 14:45:08 GMT
< Server: IBM_CICS_Transaction_Server/5.1.0(zOS)
< Content-Length: 000000000000100
<
/genapp/CustService/0000000009
* Connection #0 to host your.cics.region left intact
 
* Closing connection #0
Note: The content of the CustServiceREST_PUT command file, for running in a Microsoft Windows environment, is provided in the additional materials that accompany this IBM Redbooks publication.
The application has returned a URI format structure in the following format:
/genapp/CustService/0000000009
This was returned to the application after being placed in the DFHRESPONSE container. This URI can now be processed by the application for additional function.
RESTful customer addition function
The JSON web service payload, which is sent to CICS for processing to start the customer addition function as a RESTful service, is displayed in Example 10-18.
Example 10-18 JSON web service payload
{
"cust_details": {
"first_name": "James",
"last_name": "Smith",
"date_of_birth": "2001-01-01",
"zipcode": "SO212JN",
"cell_number": "07756576667",
"email_address": "[email protected]"
}
}
Because cURL runs on a command-line basis, the JSON web service payload, shown in Example 10-18 on page 125, requires flattening out to the command line and the quotations escaped. The resulting command line for processing cURL is displayed in Example 10-19.
Example 10-19 The cURL command line for the CustServiceREST_POST command file
curl -v -H "Content-Type: application/json" -X POST -d {"cust_details":{"first_name":"James","last_name":"Smith","date_of_birth":"2001-01-01","zipcode":"SO212JN","cell_number":"07756576667","email_address":"[email protected]"}} http://your.cics.region:30661/genapp/CustService/
The JSON web service request, shown in Example 10-19, sends the request to CICS to add new customer data for a new specific customer. GENAPP returns a new account number.
In keeping with RESTful processing convention, the service name, CustService, is generic, and the operation to be performed, POST, is specified as an HTTP method.
Running this command file sends the JSON web service payload to the CICS PIPELINE using the URI specified. The WSBIND file is processed, the JSON web service request is transformed to application data, and the CICS wrapper program is started. The CICS wrapper program maps the COBOL data into a structure that is suitable for processing by GENAPP.
After standard GENAPP processing, in which the customer account information is added, the CICS wrapper program converts the GENAPP format data structures into a COBOL format. That format can be mapped to JSON web service data for returning to the cURL process.
Successful invocation of the cURL command file results in a 200 OK status response, with the new customer data returned from GENAPP, as shown in Example 10-20.
Example 10-20 Invocation of the CustServiceREST_POST command file
> POST /genapp/CustService/ 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: your.cics.region:30661
> Accept: */*
> Content-Type: application/json
> Content-Length: 183
>
* upload completely sent off: 183 out of 183 bytes
< HTTP/1.1 200 OK
< content-type: application/json
< Date: Wed, 19 Jun 2013 12:56:02 GMT
< Server: IBM_CICS_Transaction_Server/5.1.0(zOS)
< Content-Length: 000000000000100
<
/genapp/CustService/0001000165
* Connection #0 to host your.cics.region left intact
 
* Closing connection #0
The new customer account number, assigned as part of GENAPP customer addition logic, is returned to the JSON web service client program in the DFHRESPONSE container, potentially for further processing.
Note: The content of the CustServiceREST_POST command file, for running in a Microsoft Windows environment, is provided in the additional materials that accompany this IBM Redbooks publication.
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset