IBM Support

Performance problems with the CICS Web services assistants DFHWS2LS and DFHLS2WS

Troubleshooting


Problem

The CICS Web services assistants (DFHWS2LS and DFHLS2WS) run too slowly and consume excessive amounts of CPU time. You think the length of time it takes to generate a WSBind file is a significant factor in the length of time it takes you to create a CICS Web service. You might also experience OutOfMemory conditions.

Cause

There are many reasons why DFHWS2LS and DFHLS2WS can run slowly. Some of these reasons include:

  1. The programs are written in Java™ and therefore have to start up a Java Virtual Machine (JVM) before processing can begin. This is a comparatively slow thing to do.

  2. Once the JVM has been initialized the Just In Time (JIT) compiler within the JVM will start trying to compile the assistants. Once the assistants have finished running, the JVM and the JIT compiled code it contains are discarded. This means that the initialization cost is experienced every time that the Web services assistants are used.

  3. The heap size assigned to the JVM is relatively small. If a complex Web Services Description Language (WSDL) document or language structure is processed then the JVM may go short on storage. When this happens a process called garbage collection (GC) is used to recover storage. There may be excessive GC activity in the Web services assistants due to a lack of storage.

  4. The z/OS Work Load Manager (zWLM) may associate the Web services assistants and perhaps other BPXBATCH, Java, or UNIX® System Services (USS) based applications with a poor Service Class. This means that it will take longer in elapsed time to process the Web services assistants than would otherwise be the case.

  5. There may be system wide default Language Environment (LE) parameters in effect that could impact the performance of Java. In particular, the JVM is sensitive to the size of the LE downstack.

  6. The input passed to the Web service assistants may be excessively complicated. A complex WSDL document will require significantly more processing than a simple one. The language structures produced will also be similarly complex.

Resolving The Problem

A number of possible options exist if the run time of the Web services assistants DFHWS2LS and DFHLS2WS is excessive.

  1. Ensure that you are running with an up to date maintenance level of the Web services assistants. APAR PK23547 for CICS TS V3.1 contained some performance improvements that reduce the total amount of storage required by the assistants. There are no APARs required to get this behavior in CICS TS V3.2 or V4.1.

  2. Ensure that you are using the most recent 'mapping level' available to you. Mapping level V1.2 relieves certain internal constraints within the WSBind file that can cause problems if complex WSDL documents are processed. It also provides slightly better runtime performance in CICS.

  3. Ensure that the LE downstack is set to an appropriate value (the 5th and 6th parameters of the STACK LE runtime option that is in effect). For Java to perform well they need to be set to 128K.

  4. Consider using IBM WebSphere Developer for zSeries (WDz) for producing CICS WSBind files. If you use WDz on a Microsoft® Windows® work station then your application developers can use the same environment for editing COBOL source code and producing WSBind files. There is no application development impact to the z/OS environment as all the CPU intensive work is done off platform.

  5. Consider options for simplifying your input WSDL or language structures. For example, if a WSDL document contains information for many different Operations some of which are not needed, you could remove them from the WSDL.

  6. If you receive a message that reports an OutOfMemory condition has occurred then you could try increasing the amount of heap space available to the JVM. This option is not recommended at this time as it involves changing files shipped with CICS. See Increasing the maximum heap size of a JVM below for further details.

  7. Make use of the programmatic application programming interface (API) for launching the Web services assistants. This API requires the use of Java. If you use the API then you can, for example, create your own framework for processing multiple different Web services assistants jobs in the same JVM, thereby avoiding the initialization costs and exploiting the JIT compiled code.

    The API is supported under both z/OS and Microsoft Windows which means you can produce WSBind files on your work station even if you do not use WDz. This option is likely to offer the best results but also requires the most effort. See Using the Web services assistants API for Java below for further details.




Increasing the maximum heap size of a JVM



The CICS Web services assistants do not specify a maximum heap size for the JVM used. Therefore, the default maximum heap for z/OS JVMs is used. For Java V1.4.2 this default maximum heap size is 64M. You could try setting the maximum heap size to something much larger.

This requires two changes. There is a parameter that can be passed to a JVM when it starts up to tell it the maximum heap size to use. This parameter is called '-Xmx'. For example, if you want to set a maximum heap size of 200M then the parameter to specify when starting the JVM is '-Xmx200M'.

There are two USS script files shipped with CICS that actually start the JVM. They are both in the '/lib/wsdl' UNIX file system directory below the root directory under which the CICS UNIX files have been installed. Usually this will be '/usr/lpp/cicsts/cicstsxx/lib/wsdl' where xx corresponds with the version (31 or 32) of CICS you are running. The two files are called DFHWS2LS and DFHLS2WS.

They contain the following line (or similar):
    java com.ibm.cics.wsdl.ls2ws.ls2ws $3.in

To set a larger maximum heap size, it should be changed to the following (or similar):
    java -Xmx200M com.ibm.cics.wsdl.ls2ws.ls2ws $3.in

Finally, the REGION size specified on the JCL job that runs the Web services assistants has to be large enough to allocate the specified maximum heap size. If a maximum heap size of 200M is specified then the REGION size in the JCL will need to be around 250M.

Warning: If you do change the supplied DFHWS2LS or DFHLS2WS script files then your changes will be lost if corrective maintenance is subsequently applied that changes these same files.



Using the Web services assistants API for Java



This API was first introduced to CICS TS V3.1 in APAR PK12805, but it was later extended in APAR PK23547. This API provides a programmatic interface that can be used to launch the Web services assistants from Java without the use of JCL. It is supported under both USS and Microsoft Windows. There are no APARs required for CICS TS V3.2, V4.1, V4/2, or V5.1.

The documentation for the API is in a representation known as 'Javadoc'. This is a form of documentation that is generated directly from the Java source code. In addition to the copy of the documentation in the CICS documentation under CICS Web services assistant there is a copy in a zip file in the CICS UNIX file system. This is in a file called 'docs/dfjwsdl_docs.zip' below the root directory under which the CICS UNIX files have been installed. Usually this will be '/usr/lpp/cicsts/cicstsxx/docs/dfjwsdl_docs.zip' where xx corresponds with the version (31 or 32 ...) of CICS you are running. A further copy of the API and its documentation can also be found in CICS SupportPac CA71, CICS Web Services Assistant for Windows.

This API can be used to create a program that overcomes some of the limitations of the JCL interface to the Web services assistants. If you run the Web services assistants on a Microsoft Windows work station, using the API, you can expect a significant performance improvement in the run time of the assistants. This API is also used internally within WDz to generate CICS WSBind files.

[{"Product":{"code":"SSGMGV","label":"CICS Transaction Server"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Component":"Web Services","Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"5.1;4.2;4.1;3.2;3.1","Edition":"Not Applicable","Line of Business":{"code":"LOB35","label":"Mainframe SW"}}]

Product Synonym

CICS/TS CICS TS CICS Transaction Server

Document Information

Modified date:
15 June 2018

UID

swg21249544

Page Feedback