Specifying feature toggles

CICS® TS continuous delivery delivers new functional enhancements on a much shorter cadence, providing much more rapid access to those new features. Usually, these features are not CICS base functions and are disabled by default. To enable and use these features in your CICS region, you must set up one or more feature toggle configuration files. In the feature toggle configuration file, you can define feature toggles to switch features on or off. For some features, you can also define feature toggles to specify configuration options.

Note: Feature toggles are lightweight configuration options and are not subjected to validation. If an invalid feature toggle is specified, it appears in the system log under message DFHPA1956I, but its value is ignored and the default value is used instead.

Before you begin

A list of features that you can choose to install and configure in your CICS region is available in Feature toggles. Additional features might also be made available and described in APARs. The features that are available for enablement depend on which APARs were applied to your CICS system. For a summary of changes to feature toggles by release, see Changes to feature toggles.

Follow the links in Feature toggles to locate the topics that describe individual toggle-enabled features. Each topic gives you a function overview and describes the feature toggles for enabling the feature and setting its configuration options, as well as the default values that are used when no feature toggle configuration files are found during CICS startup.

About this task

There are two types of feature toggle configuration files: a common file and a region-level file.

You can use a common file to control the features that you want to enable in a group of CICS regions that share the same USSCONFIG directory. You can use the common file to prevent one or more feature toggle settings or configuration options from being set by region-level files.

You can use a region-level file to try out a feature on a single region before it is enabled in the production environment.

Both files are optional. If neither is present, default values are used.

A feature configuration file specifies feature toggles to enable features or set configuration options.

A feature toggle that is used to enable a feature takes the following form: 
com.ibm.cics.component.feature = {true|false}
A feature can have one or more configuration options. A feature toggle that is used to set a configuration option takes the following form: 
com.ibm.cics.component.feature.config_property = value
The value can be a number, string, or boolean.
Tip:
  • You can use a line-continuation character \ at the point you want the line to break. If a \ character is required in either a name or value, double the \ character to escape line continuation.
  • You can use a hash character # at the start of a line to specify a comment line.
You can use the optional parameter finalize in the common file to prevent a region-level file from changing the feature toggles. For example, if you have given developers access to their region-level file, you can prevent them from using certain features. To lock a feature toggle setting, specify finalize preceding the toggle setting in the same line, as in the following example:

finalize com.ibm.cics.bms.ids=true
finalize com.ibm.cics.bms.ids.vtamignore=false

Procedure

Results

The feature toggle configuration files are read at CICS startup, immediately after system initialization reads the SIT parameters. The common file is read first, followed by the region-level file. Settings in the region-level file override settings in the common file, except for common settings that are specified with the parameter finalize. If any region-level file attempts to override any finalized settings, message DFHPA1957 is issued during CICS initialization, and the region-level setting is ignored.

After the CICS region is started, you can see the feature toggles and their values in message DFHPA1956I in the CICS log. The message indicates which settings were read in and stored from the feature toggle configuration file, but it does not indicate whether and how the feature toggles are being used.

Restriction: CICSPlex® SM does not display feature toggles.

Example

This is an example feature toggle configuration file:

# Feature Toggle File 
com.ibm.cics.bms.ids=true  1 
com.ibm.cics.bms.ids.vtamignore=false  2 
com.ibm.cics.bms.ids.action=ABEND  3 

 1  switches on the BMS 3270 Intrusion Detection Service.

 2  and  3  are configuration options for the feature.

What to do next

You can inquire the enablement and configuration settings of any toggle-enabled features in a CICS region by using the SPI command INQUIRE FEATUREKEY or the parameter domain function DFHPAIQX INQUIRE_FEATUREKEY. For more information, see INQUIRE FEATUREKEY and Parameter domain XPI functions.