Configuring a JVM server for a CICS Security Token Service

Configure the JVM server to run a CICS Security Token Service if you want to validate and process SAML tokens.

About this task

The supplied sample DFHJVMST.jvmprofile is suitable for a JVM server that runs a CICS Security Token Service.

Start of changeYou can define the JVM server either with CICS® online resource definition or in a CICS bundle. For more help with using the CICS Explorer® to create and edit resources in CICS bundles, see Working with bundles in the CICS Explorer product documentation.End of change

Procedure

Create a JVMSERVER resource for the JVM server.
  1. Specify a name for the JVM profile for the JVM server.
    On the JVMPROFILE attribute, specify a 1 - 8 character name. This name is used for the prefix of the JVM profile, which is the file that holds the configuration options for the JVM server. You do not need to specify the suffix .jvmprofile.
  2. Specify the thread limit for the JVM server.
    The number of threads depends on the workload that you want to run in the JVM server. To start with, you can accept the default value and then tune the environment later. You can set up to 256 threads in a JVM server.
  3. Create the JVM profile to define the configuration options for the JVM server.
    The JVM profile must be in the directory that you specify on the system initialization parameter, JVMPROFILEDIR. You can use the sample profile, DFHJVMST.jvmprofile, as a basis. This profile contains a subset of options that are suitable for starting the JVM server. You can either copy DFHJVMST.jvmprofile from the installation directory into the directory that you specify on JVMPROFILEDIR, or select it in CICS Explorer and save to the target directory.

    All options and values for the JVM profile are described in JVM profile validation and properties. Follow the coding rules in Rules for coding JVM profiles.

    Make the following changes to the sample profile:
    • Set JAVA_HOME to the location of your installed IBM Java SDK.
    • Set WORK_DIR to your choice of destination directory for messages, trace, and output from the JVM server.
    • Set SECURITY_TOKEN_SERVICE to YES.
    • Start of changeSet TZ to specify the timezone for timestamps on messages from the JVM server. An example for the United Kingdom is TZ=GMT0BST,M3.5.0,M10.4.0.End of change
  4. Save your changes to the JVM profile
    The JVM profile must be saved as EBCDIC on the USS file system.

Results

When you install and enable the JVMSERVER resource, CICS creates a Language Environment enclave and passes the options from the JVM profile to the JVM server. The JVM starts up and the OSGi framework resolves any OSGi middleware bundles. When the JVM server completes startup successfully, the JVMSERVER resource installs in the ENABLED state.

If an error occurs, for example CICS is unable to find or read the JVM profile, the JVM server fails to initialize. The JVMSERVER resource installs in the DISABLED state and CICS issues error message. See Troubleshooting Java applications.

What to do next

You can further customize the JVM server, for example:
  • Specify any directories that contain native C dynamic link library (DLL) files, such as DB2 or WebSphere MQ. You specify these directories on the LIBPATH_SUFFIX option.
  • For more information see Configuring the CICS Security Token Service.