Problem determination
This chapter outlines common user faults that you might encounter, provides advice for how to avoid these faults, and directions to further information.
This chapter contains the following topics:
8.1 Introduction
With the Customer Information Control System (CICS) support for JavaScript Object Notation (JSON) web services being built on the existing web services infrastructure, the approach to take if you encounter problems is largely the same.
Notable however, is the relatively small set of tools available for assisting with the construction of JSON schemas and JSON data, compared to the rich tools available for working with Web Services Description Language (WSDL) and Extensible Markup Language (XML) for SOAP web services.
In addition, the JSON schema standard is still evolving. The CICS JSON assistants are based on draft 4 of the specification. For further information see the following websites:
•Get information about JSON schema:
•Get information about JSON schema core definitions and terminology:
•Get information about JSON schema interactive and non-interactive validation:
As a result of the smaller set of tools, you might find the most common cause of problems to be badly constructed JSON data. Section 8.4, “Problems with requests to JSON web services” on page 88, provides information about common pitfalls and identify tools that can provide assistance.
|
Tip: You can confirm that the CICS Transaction Server (CICS TS) Feature Pack for Mobile Extensions is working correctly by running the sample program DFH0MOBI. For more information and instructions, see the “Verifying the operations of the CICS TS Feature Pack for Mobile Extensions” topic in the CICS TS Information Center.
|
If you encounter a problem, before you contact IBM support, see “Collect troubleshooting data for CICS Transaction Server for z/OS Feature Pack for Mobile Extensions V1.0”, found at the following website:
This page lists the documentation that you must collect so that the CICS support team can diagnose your problem.
8.2 Deployment problems
Deployment problems are errors that occur when you try to install a PIPELINE resource or a WEBSERVICE resource.As demonstrated in Chapter 9, “Language structure to JSON schema scenario” on page 93, and Chapter 10, “JSON schema to language structure scenarios” on page 105, using the PIPELINE scan operation automatically creates WEBSERVICE and URIMAP resources.
If you are encountering problems after manually defining these resources, the automation of the PIPELINE scan operation might prove easier and less error-prone. For more information about resolving deployment problems, see the section on troubleshooting deployment problems in the CICS TS Information Center.
8.3 Problems with the JSON assistants
This section covers problems that you might encounter when using the JSON assistants. For additional information see the “Troubleshooting the JSON assistant” topic in the CICS TS Information Center.
As presented earlier in this chapter, the JSON assistants are based on draft 4 of the JSON schema specification. This should not be confused with the MAPPING-LEVEL parameter in the JSON assistants. This parameter concerns how information is converted between language structures and JSON schema. To benefit from the most sophisticated mappings available, set this to level 3.0.
|
Tip: With a MAPPING-LEVEL of 1.2 or higher, you can use the CHAR-VARYING parameter to specify how variable-length character data is mapped between JSON and high-level language structures (and vice versa). For details of usage, see the sub-topic of the “High-level language and JSON schema mapping” topic in the CICS TS Information Center, which applies to the mapping you want to produce.
|
On multiple occasions, when running DFHJS2LS or DFHLS2JS, we encountered the following DFHPI9523 message:
DFHPI9523E An unexpected error occurred whilst processing file
"//USER.JS2LS.COPYLIB(CRREQ01)". The problem is: "//USER.JS2LS.COPYLIB(CRREQ01)".
The cause of such messages is usually that the partitioned data set (PDS) cannot be opened because a user has a member of the PDS open for editing, using IBM Rational Developer for IBM System z or Interactive System Productivity Facility (ISPF).
8.3.1 DFHJS2LS
When writing a JSON schema, in preparation for using DFHJS2LS, you might find it helpful to refer to the JSON schema specification and related tutorials. We also suggest that you read the following CICS TS Information Center topics, which describe the subset of the JSON schema specification that is supported:
•JSON schema to Common Business Oriented Language (COBOL) mapping
•JSON schema to C and C++ mapping
•JSON schema to PL/I mapping
We also suggest that you validate your schema. One such tool for validation is the online JSON schema validator:
A JSON schema specifies that a property is optional if it does not appear in the required keyword array that is associated with the enclosing JSON schema object type. As such, DFHJS2LS will add a field, with a suffix _num, to generated language structures for optional fields. At run time, this field is set to 1 to indicate that the value was present in the JSON data and set to 0 if it was not.
We suggest that all properties be included in the required keyword array as standard practice. However, CICS does not perform a runtime check for required properties.
Note that CICS cannot transform integer values greater than the maximum value for a signed long (263 - 1) unless they are enclosed within quotation marks.
|
Tip: You can improve the appearance of COBOL language structures generated by DFHJS2LS, by using the MAPPING-OVERRIDES=UNDERSCORES-AS-HYPHENS parameter. As a result, DFHJS2LS will use hyphens rather than X characters in variable names in generated high-level language structures.
|
8.3.2 DFHLS2JS
Before using DFHLS2JS, you might want to read the following CICS TS Information Center topics, which describe the supported mappings and any restrictions that might apply:
•COBOL to JSON schema mapping
•C and C++ to JSON schema mapping
•PL/I to JSON schema mapping
|
Note: DFHLS2JS does not fully implement the padding algorithms of PL/I. As a result, you might be required to explicitly declare padding bytes. DFHLS2JS will issue a DFHPI9029 or DFHPI9030 message if this is necessary. Further explanation is provided in the PL/I to JSON schema mapping topic, as referenced previously.
|
8.4 Problems with requests to JSON web services
As introduced at the start of this chapter, the most common problem we have encountered is badly formed JSON data being passed to CICS, which has resulted in the JSON data being rejected, or other unintended results.
It is common to programmatically produce JSON data within your applications. It is suggested that you validate the JSON data produced against the JSON schema as part of the application testing process. The JSON schema validator, referenced in 8.3.1, “DFHJS2LS” on page 87, enables JSON to be validated against a schema.
In addition, ensure that the Multipurpose Internet Mail Extensions (MIME) type of the Hypertext Transfer Protocol (HTTP) requests sent to CICS is application/json. This is the official type, as assigned by the Internet Assigned Numbers Authority (IANA).
If you encounter a runtime problem with a JSON web service, you should refer to the following sources of diagnostic information:
•For web service requests into CICS that fail, first check the HTTP response and status code. The response might contain a CICS message that describes the problem encountered, and perhaps a solution.
•If the HTTP response and status code does not provide sufficient diagnostic information, further messages might be present in MSGUSR.
In the case of JSON parse errors, which occur when CICS detects that the JSON data received is syntactically invalid, exception messages will be written to the Java virtual machine (JVM) server stderr, and to the HTTP response.
|
Tip: The WORK_DIR parameter specified in the JVM profile determines the location of a JVM server’s stderr file. If WORK_DIR is omitted, /tmp is used. For further information, see the “Options for JVMs in a CICS environment” topic in the CICS TS Information Center.
|
If presented with a CICS message in the range DFHPI1007 - DFHPI1010, a transformation error has occurred. These occur when CICS detects that the JSON data received does not match the expected data format from the WSBIND file.
If you encounter a JSON parse error or transformation error, see any messages issued by CICS, and validate your JSON data against the schema to identify the cause of the problem.
Note that DFHJS2LS produces WSBIND files that describe how to map JSON data to the best fit data types of a particular high-level language. Therefore, CICS does not issue a transformation error message if transformations succeed. This is because the data is within the limits of the high-level language data type, but was outside the range of acceptable values as described in the JSON schema. Such validation should be completed by your mobile application or CICS application.
Because CICS does not perform a runtime check for the existence of required variables, missing numeric fields will be populated with a null value. If uninitialized, such null data might cause a transformation error when the high-level language structure is converted into JSON data for the HTTP response.
For more information, see the topic about troubleshooting problems with JSON requests, found in the CICS TS information center.
..................Content has been hidden....................
You can't read the all page of ebook, please click here login for view all page.