ALERT: Some images may not load properly within the Knowledge Base Article. If you see a broken image, please right-click and select 'Open image in a new tab'. We apologize for this inconvenience.

Gen web client/server to z/OS CICS with Unicode data gives TIRM158E

book

Article ID: 225374

calendar_today

Updated On:

Products

Gen - Workstation Toolset Gen - Run Time Distributed

Issue/Introduction

Want to insert data through Gen Web Generation app by many languages like Chinese, German, French, ...etc

Gen 8.6
Client: Web Generation
Server: z/OS CICS, DB2. Using Arabic codepage (CCSID) of 420

Seeing this string being corrupted after input on client and read back:
"ÄSS  DO─×UM "
becomes:
"?SS  DO?UM"

The above result is with CFBDynamicMessageEncodingExit.java customised to return encoding "cp1256".
If return encoding "UTF-8" see failed transaction:
TIRM158E: A communication error was encountered on the client
 [Function: TCPIPConnection::readData]Error attempting to read data (Connection reset)

Environment

Release : 8.6

Component : CA Gen Run Time, Distributed

Resolution

Having user exit CFBDynamicMessageEncodingExit.java return encoding "UTF-8" (Unicode) (rather than "cp1256") is the correct method to handle multiple language characters on the client.
The root cause of the "Error attempting to read data (Connection reset)" when returning encoding "UTF-8" is likely Gen codepage translation. From the TIRXINFO provided the z/OS server is using "DEFAULT CODE PAGE" of 420 which is the Host EBCDIC codepage (CCSID) for Arabic. When using "UTF-8" on the client it is sending codepage 1201 to the Host and the default MKCRUN likely has no Gen codepage pair included for the combination 420 <-> 1201.

There are 2 ways to resolve the codepage translation problem. The first option is normally used/recommended:

1. Add the 420 <-> 1201 pair in the MCKRUN JCL on the Host & rebuild DLL TIRCRUNC
DEFAULT:
*****
//SYSIN    DD *
 0    437       Gen default translation tables (REQUIRED)        <--(4)
 37   437       USA EBCDIC - ASCII translation tables (REQUIRED) <--(4)
 37   1252      AMERICAN EBCDIC - MICROSOFT ASCII (REQUIRED)     <--(4)
 37   850       Include only if needed                           <--(4)
 37   819       Include only if needed                           <--(4)
 1140 850       Include only if needed                           <--(4)
 1140 819       Include only if needed                           <--(4)
 1140 819       Include only if needed                           <--(4)
//*
*****
NEW: (Keep first 3 lines which are required and remove their comments. Add line for "420 1201")
*****
//SYSIN    DD *
 0    437
 37   437
 37   1252
 420  1201
//*
*****
The steps are also documented here: MKCRUN - Make C Runtimes - TIRCRUNC (CICS) and TIRCRUNI (IMS)
Other useful reference: Customize Code Page Translation
Run the MKCRUN JCL to create a new version of DLL TIRCRUNC.
Backup the current TIRCRUNC before replacing it.
Replacing it in CICS requires using NEWCOPY in CICS i.e. "CEMT SET PROGRAM(TIRCRUNC) NEWCOPY"

2. Change the user exit CFBDynamicMessageEncodingExit.java to return encoding "Cp420" on the client i.e.
+++
    public static String serverEncoding( String tran, String encoding ) {
        //if (tran.startsWith("AR")) { /* return transacion specific   */
        //    return "Cp420";          /* encoding.                    */
        //if ((encoding != null) && (encoding.length() > 0)) {
        //    return encoding;           /* Return Selected Encoding.    */
        //}
        //return System.getProperty("file.encoding");
        //return "UTF-8";              /* Default to Unicode Encoding  */ 
        return "Cp420";
    }
+++
That user exit just tells the Gen runtime what codepage to use when sending the data (CFB) to the server. 
The default exit just returns the encoding it receives as input (if not null) or System.getProperty("file.encoding") which is the JVM character encoding (may vary across the hosting OS). However, the exit can be changed to return other values like "Cp420". The value that the exit returns is used to look up the actual codepage value from the Gen codepage.properties file e.g. "Cp420" maps to codepage 420:
*****
# 420
Cp420=420
ibm-420=420
CPID.420=Cp420
*****
The Gen runtimes use JVM translation capabilities to convert the CFB data from the JVM encoding to the codepage returned by the exit & the CFB is sent to the server with that codepage. The main difference between this and the first option of changing MKCRUN is that with this option the codepage translation is being done on the client and not being done when the CFB reaches the server. A similar process happens in reverse when the server returns the data back to the client i.e. no codepage translation is done on the server and it is all done on the client.

Additional Information

However, even if the required codepage translation is set up having full multi-language data support for a Gen Web Generation client connecting to Gen z/OS CICS server is not likely to be successful.
That is because the Arabic codepage 420 will not recognise all multi-language characters irrespective of where the codepage translation is done and for those characters it does not recognise the codepage translation process will replace it with some "substitution" character.
Gen generated COBOL (and C) applications do not support Unicode at this time. If they did, then the Web client applications could send the CFB in codepage 1201 and the server applications would be able to handle it. At this time, Gen COBOL (and C) server applications are restricted to one non-Unicode codepage.
The only other option is to "clone" the applications and build multiple versions of the server runtimes to support each codepage. This would be a possibility if the environment allows knowing the codepage of the client application so each client connects to a language-specific version of the server application. However, in this case, the client application is a web application and could potentially be sending characters from any codepage, so it is probably not feasible.
The only way for Gen to be able to support full multi-language data on the Gen Web Generation client is to have the server application as either Java or C#. Gen generated Java and C# server applications do support Unicode and can properly handle any character sent from client to server.