How to specify a custom CCSID for a CICS service

You can specify a custom CCSID when you create a CICS® service.

1. Build a custom CharsetProvider JAR file that contains your own CharsetProvider and Charset class implementations.
   When you implement the CharsetProvider class, you must set a canonical name or an alias name for your custom character encoding. This canonical name or alias name is composed of (from left to right) a specific string "Cp" and a numeric string. The numeric string is the CCSID that you need to specify when you generate a service archive (.sar).

   The following two code examples show how to initialize a new character set with two kinds of names.

   Example 1: using a canonical name

   
   import java.nio.charset.spi.CharsetProvider;
   
   public class CustomCharsetProvider extends CharsetProvider {
       // The canonical name of the custom charset
       private static final String CUSTOM_CHARSET_NAME = "Cp99999";
       // A handler to the Charset object
       private Charset custom_charset = null;
   
       public CustomCharsetProvider() {
           String[] alias = new String[] { CUSTOM_CHARSET_NAME };
           this.custom_charset = new CustomCharset(CUSTOM_CHARSET_NAME, alias);
       }
       ...
   }
   

   In this example, "Cp99999" is a canonical encoding and the numeric part "99999" is used to specify the CCSID later.

   Example 2: using an alias name

   
   import java.nio.charset.Charset;
   import java.nio.charset.spi.CharsetProvider;
   
   public class CustomCharsetProvider extends CharsetProvider {
       // The canonical name of the custom charset
       private static final String CUSTOM_CHARSET_NAME="Unicode-at-on";
       // The specific numeric alias name of the custom charset
       private static final String CUSTOM_CHARSET_NAME_ALIAS = "Cp99999";
       // A handler to the Charset object
       private Charset custom_charset = null;
   
       public CustomCharsetProvider() {
           String[] alias = new String[] { CUSTOM_CHARSET_NAME_ALIAS };
           this.custom_charset = new CustomCharset(CUSTOM_CHARSET_NAME, alias);
       }
       ...
   }
   

   In this example, "Unicode-at-on" is a canonical encoding that is not supported in IBM z/OS Connect by default. "Cp99999" is the alias name that is set for "Unicode-at-on" and the numeric part "99999" is used to specify the CCSID later.

   For more information about how to build a custom CharsetProvider JAR file, see the Java API documentation for CharsetProvider.

2. Deploy the custom CharsetProvider JAR file to be included in the JVM.
   Choose the method that corresponds with your level of Java
   • Java 8
     1. Copy the JAR file to the z/OS Connect runtime JRE extensions directory. For example, $ZCEERUNTIME_JRE_Location/jre/lib/ext.

        In JVM OPTIONS, this directory is named by using the java.ext.dirs option. For example, -Djava.ext.dirs=${JAVA_HOME}/lib/ext.

     2. If you use the API toolkit, ensure that the JAR file is deployed to the API toolkit JRE extensions directory. For example, $ZOSExplorer_Install_Location/jdk/jre/lib/ext.
     3. If you use the build toolkit, ensure that the JAR file is deployed to the build toolkit JRE extensions directory. For example, $BUILDTOOLKIT_JRE_Location/jre/lib/ext.
   • Java 11 or 17
     1. If you use the API toolkit, modify the eclipse.ini file in ${ZOSExplorer_Install_Location/eclipse.ini}. In this file, anywhere under the -vmargs line, insert the following line:

        -Xbootclasspath/a:/Path/To/CharsetProvider.jar

        This appends the CharsetProvider.jar file to the boot class path of the Java that is used to run the API toolkit.
     2. If you use the build toolkit, set the environment variable ZCN_JAVA_OPTS to the following value before zconbt is called.

        -Xbootclasspath/a:/Path/To/CharsetProvider.jar

        This setting includes the value of ZCN_JAVA_OPTS in the JVM options that is used when running the build toolkit.
     3. Ensure that the same CCSID is available in the z/OS Connect server by ensuring that the JAR file is available. Update your JVM options to include the following line:

        -Xbootclasspath/a:/Path/To/CharsetProvider.jar