Upgrading applications

Upgrade actions

All versions Modify routing programs to tolerate channels

If you use a user-written dynamic routing program or distributed routing program for workload management, rather than CICSPlex® SM, you must modify your program to handle the new values that it might be passed in the DYRLEVEL, DYRTYPE, and DYRVER fields of the DFHDYPDS communications area. This modification is required even if you do not intend to implement channels and containers in your own applications.

All versions Modify routing programs to update the DYRDCYN field in the DFHDYPDS copybook to support daisy-chaining of non-terminal START requests

If you are using a user-written distributed routing program to daisy chain non-terminal START requests over APPC connections, you must change the program to put the value Y into the DYRDCYN field (which replaces DYRFILL1 field) in the DFHDYPDS copybook.

If daisy-chaining is supported by a non-terminal START request, CICS passes the originator's data, which is contained in the DYRUSER field in DFHDYPDS, unchanged to the local instance of the distributed routing, and sets the DYRDCYN field to N. It is the responsibility of the distributed routing program to decide whether to continue daisy-chaining of the START request and update the contents of fields DYRDCYN and DYRUSER accordingly. You must ensure that your dynamic routing program performs appropriate workload routing and that unpredictable routing does not take place.

For more information, see Dynamic Routing and Telling CICS whether daisy-chaining of non-terminal-related START requests is supported.

All versions Modify applications that rely on the order in which containers are returned

A container performance improvement introduced in CICS TS 5.5 changes the order in which containers are returned. It is important to be aware that the order in which containers are returned is undefined and might change. Therefore, applications should not rely on the order in which containers are returned.

If an existing application has been written in such a way as to rely on the order in which containers are returned, you should modify the application to ensure that it is does not rely on the order of returned containers.

com.ibm.cics.container.hash=false 

All versions Modify applications that access Db2 special registers

In CICS TS 5.4 through 5.6 with APAR PH30252 and in CICS TS 6.1 or later, the CICS Db2 attachment facility has been enhanced to pass adapter data to Db2.

The Db2 special register CURRENT CLIENT_ACCTNG normally returns an empty string for CICS Db2 applications. However, when ACCOUNTREC(UOW) or ACCOUNTREC(TASK) is set on the DB2CONN or DB2ENTRY definition, the special register returns the accounting correlation token passed to Db2, which is a derivative of the LU6.2 unit of work ID (UOWID). At Db2 12 with APAR PH31447 or higher, this has changed so that for CICS tasks that have adapter data present in the CICS origin data (see Adapter tracking), when ACCOUNTREC(UOW) or ACCOUNTREC(TASK) is in effect, the adapter data is passed as an accounting string to Db2. For these tasks, the Db2 special register CURRENT CLIENT_APPLNAME returns the origin data adapter ID instead of the first eight bytes of the thread correlation ID, and the Db2 special register CURRENT CLIENT_ACCTNG returns the origin adapter data1, data2 and data3 fields instead of the accounting correlation token.

All versions Modify applications that use Db2 held cursors

This means that at the start of each UOW the CICS Db2 attachment facility issues a signon call to Db2. The signon call closes cursors, so held cursors are not held across syncpoints. A subsequent fetch for a previously held cursor will result in a SQLCODE of -501 to be returned. Therefore, you must modify applications that use held cursors. Applications must reposition cursors after a syncpoint. See Db2 SQL programming: Held and non-held cursors.

In addition, for CICS to pass an XID to Db2, CICS first queries MVS™ RRS to determine if there is a global unit of work with a matching LU6.2 UOWID. The query for a global unit of work involves issuing an ATRQUERY request with a sysplex scope. Ensure that auditing of successful access to RRS system management functions is not enabled with the MVSADMIN.RRS.COMMANDS.** profile in the FACILITY class; otherwise, an excessive number of SMF 80 records will be produced. For more information, see ATRQUERY — Obtain RRS Information in z/OS MVS Programming: Resource Recovery.

All versions (COBOL only) Migrate from the separate CICS translator to the integrated CICS translator

The separate CICS translator has not been updated for newer COBOL language such as floating comment delimiters, JSON GENERATE and JSON PARSE, and compiler directives. To use the latest features of the COBOL compiler, use the integrated CICS translator.

Follow the migration instructions in the Enterprise COBOL for z/OS® Migration Guide.

All versions Modify all Java applications that call previously deprecated methods which have now been removed

Several methods across several classes, which were previously deprecated, have now been removed. Applications that use these methods will no longer work at this release and must be changed prior to upgrading. Applications that are not changed fail with Caused by: java.lang.NoSuchMethodError errors at runtime following the upgrade.

All versions Modify all Java applications that access previously deprecated data holder fields which have now been made private.

public static void main(CommAreaHolder cah)
   {
        System.out.println(“Commarea = “ + cah.value); 
   }

Should be changed to 

public static void main(CommAreaHolder cah)
   {
        System.out.println((“Commarea = “ + cah.getValue()); 
   }
Applications which are not changed will see one of two runtime errors similar to the following examples

Caused by: java.lang.NoSuchFieldError: com/ibm/cics/server/DataHolder.value

Caused by: java.lang.IllegalAccessError: Class com/ibm/test/Test illegally accessing "package private" member of class com/ibm/cics/server/CommAreaHolder
    at com.ibm.test.Test.main(Test.java:13)