Upgrading applications
This information applies to all currently supported CICS® TS releases, regardless of your current release and the target release. Existing applications typically continue to run in a later version of CICS.
If you are upgrading from an end-of-service release, you might need to take additional actions that are relevant to your current, end-of-service release, along with the actions summarized in the upgrade instructions in this information. For details, see Upgrading from end-of-service releases.
Upgrade actions
Table 1 lists the actions you must perform when upgrading to a higher CICS release, regardless of your current release and the target release. The sections that describe these actions in detail are tagged with All versions.
Action | Mandatory or optional? |
---|---|
Modify routing programs to tolerate channels | Mandatory |
Modify routing programs to update the DYRDCYN field in the DFHDYPDS copybook to support daisy-chaining of non-terminal START requests | Mandatory if you are using a user-written routing program |
Modify applications that rely on the order in which containers are returned | Mandatory |
Modify applications that access Db2 special registers | Optional, if your applications access Db2® at Db2 12 with APAR PH31447 or higher |
Modify applications that use Db2 held cursors | Optional |
Migrate from the separate CICS translator to the integrated CICS translator | Optional for COBOL programs |
Modify all Java applications that call previously deprecated methods which have now been removed | Mandatory |
Modify all Java applications that access previously deprecated data holder fields which have now been made private | Mandatory |
Modify routing programs to tolerate channels
All versions
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.
Modify routing programs to update the DYRDCYN field in the DFHDYPDS copybook to support daisy-chaining of non-terminal START requests
All versions
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 unchanged to the local instance of the distributed routing, and sets the DYRDCYN field to N. For CICS TS Version 6.1 or later, the originator's data is contained in the DYRUSERN field in DFHDYPDS. For version 5.x, it is contained in the DYRUSER field in DFHDYPDS. 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 DYRUSERN (or 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.
Modify applications that rely on the order in which containers are returned
All versions
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
Modify applications that access Db2 special registers
All versions
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.
Modify applications that use Db2 held cursors
All versions
- For CICS TS 5.5 and 5.6, the feature
toggle
com.ibm.cics.db2.sharelocks=true
is enabled in a CICS region (see Changes to feature toggles). - For CICS TS 6.1 and later, SHARELOCKS(YES) is specified on a DB2ENTRY definition.
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.
(COBOL only) Migrate from the separate CICS translator to the integrated CICS translator
All versions
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.
- Delete the separate translation step from the compile process.
- Change the XOPTS translator option to the CICS compiler option and delimit the suboptions with quotes or apostrophes.
- Move all CBL/PROCESS statements to the first lines of the source program. The integrated CICS translator does not accept comment lines preceding a CBL/PROCESS statement. The source program must conform to Enterprise COBOL rules.
- Check if you have nested programs that redefine DFHCOMMAREA. The integrated translator will not generate declarations of DFHCOMMAREA or DFHEIBLK in nested programs. COBOL programs that depend on these generated declarations within nested programs require source changes.
Follow the migration instructions in the Enterprise COBOL for z/OS Migration Guide.
Modify all Java™ applications that call previously deprecated methods which have now been removed
All versions
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.
Modify all Java applications that access previously deprecated data holder fields which have now been made private
All versions
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)