z/OS configuration variables

The variables that you use for configuring an Decision Runtime for z/OS instance are held in the HBRINST or HBRCTRL dataset member. To be valid, the values you specify must not contain spaces.

Overview

Variables for configuring the environment have the following notation: ++VARIABLE_NAME++. The equivalent runtime variables do not have any special notation.

The variables in the ++HBRHLQ++.SHBRPARM(HBRINST) dataset member must be customized. The ++HBRHLQ++ variable represents the high-level qualifier that is assigned to the working datasets. The HBRUUPTI job must then be submitted to generate the working datasets. The datasets created by the HBRUUPTI job are then used to configure the runtime instance.

Important: For some variables, after you run HBRUUPTI, you must check the working dataset to ensure that the JCL is valid. If the JCL is not valid because, for example, an entry was truncated, you must manually edit the JCL. For more information, see the variables descriptions.

Set the configuration variables to configure a new Decision Runtime for z/OS instance. The configuration variables include postinstallation configuration variables, and variables that initialize the runtime variables in the other members of this dataset, and in other datasets. These variables are also used for generating the working datasets for configuring and running an execution environment. The version of HBRINST or HBRCTRL must match the version of the zRule Execution Server for z/OS instance you configure. The HBRINST or HBRCTRL dataset member belongs to SHBRPARM.

Configuration variables

Table 1. Configuration variables for configuring Decision Intelligence Client Managed Software to run on zRule Execution Server for z/OS
Variable Description

++HBRADSFILELOCATION++

The directory that contains your deployed Decision Intelligence archives.

++HBRADSLOGCACHING++

When set to true, an extra log file is created that shows the contents of the decision service in-memory cache.
Table 2. <title>Configuration variables for configuring Decision Manager Open Edition to run on zRule Execution Server for z/OS
Variable Description

++HBRDMOEFILELOCATION++

The directory that contains your Decision Manager Open Edition archives.

++HBRDMOELIBPATH++

Use this variable to point to a different runtime library directory for Decision Manager Open Edition, instead of the one that is shipped with Decision Runtime for z/OS. This helps if the Decision Manager Open Edition moves up a level and the user wants to run KJAR at this level. Each instance of the Decision Manager Open Edition runtime on z/OS can support only one level of runtime.

Alternatively, a value of default can be used. In this case, the shipped Decision Manager Open Edition libraries are used from location +HBRINSTPATH+/executionserver/DMOElib. If no value is provided for this parameter, the default location is used.
Table 3. Configuration variables for emitting events to IBM Business Automation Insights (BAI)
Variable Description
++HBRBAIENABLE++ Set to true to enable emitting events to BAI.
++HBRBAITOPIC++ The name of your BAI topic to which you are sending events.
++HBRBAIBOOTSTRAPSERVERS++ The BAI bootstrap server address and port, for example, exampleserver.com:1234.
++HBRBAISECURITYPROTOCOL++ Security protocol that is used for communication, for example, SASL_SSL.
++HBRBAISSLTRUSTSTORELOCATION++ Location of your trust store on the z/OS UNIX file system that holds your keys to access BAI.
++HBRBAISSLTRUSTSTOREPASSWORD++ Password for the trust store.
++HBRBAISSLTRUSTSTOREPROTOCOL++ Protocol to use with a secure sockets layer (SSL), for example, TLSv1.3.
++HBRBAISASLMECHANISM++ SSL mechanism to use with the connection, for example, PLAIN
++HBRBAISASLJAASCONFIGMODULE++ Apache Kafka® brokers that support client authentication through a simple authentication and security layer (SASL). This property shows the SASL configuration module to use, for example, plain.PlainLoginModule.
++HBRBAISASLJAASCONFIGOPTIONS++ Any further options required for the SASL configuration, for example, required.
++HBRBAISASLJAASCONFIGUSERNAME++ User name to connect to BAI through SASL.
++HBRBAISASLJAASCONFIGPASSWORD++ Password to connect to BAI through SASL.
Table 4. Configuration variables for configuring a new zRule Execution Server for z/OS instance.
Variable Description

++HBRHLQ++

The high-level qualifier for Decision Runtime for z/OS datasets.

Example: HBR.ODM

This variable is mandatory.

++HBRINSTPATH++

The installation root directory.

Example: /usr/lpp/zDM/V8R10MX

This variable is mandatory.
++HBRWLPSTRICTTRANSPORT++ When set to true, this variable changes the configuration of Liberty to include the HTTP Strict-Transport-Security response header. You must define it in HBRINST before submitting HBRUUPTI.

++HBRWLPANGELNAME++

Specifies the name of the Liberty Angel process which the zRule Execution Server for z/OS should connect to when running in CONSOLE, HTDS or TEST mode.

++HBRWLPTIMEOUT++

Specifies how long (in minutes) the zRule Execution Server for z/OS should wait for the embedded Liberty server to start when running in CONSOLE, HTDS or TEST mode.

++HBRWORKPATH++

The working directory that is used for the execution environment, unless it is overridden in the control statements in HBRCTRL.

Example: /u/HBR1

If this variable is 35 characters or less in length, the value can be used by all working data sets. If the value exceeds 35 characters, the customized members in SHBRJCL must be manually updated where this value is inserted into the JCL, otherwise the job might not contain valid JCL.

++HBRWORKDS++

The high-level qualifier for the working datasets that contain customized JCL for creating an execution environment instance.

Example: HBR.WORKDS

The value of this variable must be different from the value of the ++HBRHLQ++ variable.

++HBRJAVAHOME++

The location of the JVM. (Only Java™ 21.0 is supported).

Example: /java/java21_64/J21.0_64

++HBRPORT++

The port number on which the zRule Execution Server for z/OS running in CONSOLE, HTDS, or TEST mode can be found. The value must be an integer.

The value of this variable must be different from the value of the ++HBRSECUREPORT++ and ++HBRCONSOLECOMPORT++ variables.

Example: 34114

++HBRSECUREPORT++

The port number on which the zRule Execution Server for z/OS running in CONSOLE mode can be found using a secure connection. The value must be an integer.

The value of this variable must be different from the value of the ++HBRPORT++ and ++HBRCONSOLECOMPORT++ variables.

Example: 24114

++HBRCONSOLECOMPORT++

The port that is used by the console to communicate with the server. The value must be an integer.

The value of this variable must be different from the value of the ++HBRPORT++ and ++HBRSECUREPORT++ variables.

Example: 44114

++HBRCONSOLECOMHOST++

The host name of the machine where the console runs. Specify localhost when the console and the server that is run on the same machine.

Example: localhost

++HBRLANG++
The language that is used by the server. The default value is En-US. The server uses the following valid language values:
  • De_DE: German
  • En_US: US English
  • Es_ES: Spanish
  • Fr_FR: French
  • It_IT: Italian
  • Ja_JP: Japanese
  • Ko_KR: Korean
  • Nl_NL: Dutch
  • Pl_PL: Polish
  • Pt_BR: Brazilian Portuguese
  • Ru_RU: Russian
  • Zh_CN: Simplified Chinese
  • Zh_TW: Traditional Chinese

The supported languages are also listed in the HBRCMMN dataset member.

The value is case-sensitive and must be specified in mixed-case exactly as shown.

++HBRTRACELEVEL++
The trace level during execution. Choose from the following options:
  • ALL: Logs all messages, including internal traces.
  • FINE: Logs debug messages, informational messages, errors, and warnings.
  • INFO: Logs informational messages, errors, and warnings.
  • WARNING: Logs errors and warnings.
  • SEVERE: Logs errors only.
  • OFF: No tracing.

The value is case-sensitive and must be specified in uppercase exactly as shown.

++HBRPERSISTENCETYPE++

The type of persistence layer that is used to store deployed artifacts. Set this variable to Db2 or FILE. The value is case-sensitive and must be specified in uppercase exactly as shown.

++HBRSSLKEYSTORE++

The location of the certificate keystore when zRule Execution Server for z/OS is configured for SSL. Allowed values are JAVA for a Java keystore or SAF for a SAF keystore such as RACF®.
Table 5. Configuration variables for configuring CICS to execute rules on a zRule Execution Server for z/OS instance.
Variable Description

++CICSLIST++

The CICS startup group list that is specified by using the GRPLIST parameter.

Example: DFHLIST

The list of groups contains the resource definitions that are created when you run the ++HBRWORKDS++.<HBRSSID_NAME>.SHBRJCL(HBRCSD) job in Configuring CICS to execute rules on zRule Execution Server for z/OS. When CICS starts, it looks at the lists of groups in the table and installs the resources that they specify.

Table 6. Configuration variables for configuring zRule Execution Server for z/OS to access IBM Machine Learning.
Variable Description

++HBRHLQ++.SHBRPARM(HBRINST)

 To configure zRule Execution Server for z/OS to access Machine Learning, add the following variables to ++HBRHLQ++.SHBRPARM(HBRINST).

++HBRMLZRESTAPIKEY++

 The API key that is presented to the cloud AUTHURL token server endpoint to get a token.

++HBRMLZRESTBASEURL++

 The endpoint for RESTFUL Machine Learning execution.

Example: http://winmvsga.hursley.ibm.com:24018/iml/v2/scoring/online

++HBRMLZRESTAUTHURL++

 The endpoint to obtain a security token for use with Machine Learning.

Example: https://9.20.5.81:9888/auth/generateToken

++HBRMLZRESTAUTHUSERNAME++

 The username to provide to the authentication endpoint when obtaining a token.

Example: aMLZUsername

++HBRMLZRESTAUTHPASSWORD++

 The password to provide to the authentication endpoint when obtaining a token.

Example: aMLZPassword

++HBRMLZRESTBASEURL++

 The endpoint for RESTFUL Machine Learning execution.

Example: http://winmvsga.hursley.ibm.com:24018/iml/v2/scoring/online

++HBRMLZRESTONZOS++

 When set to false, the rest calls are for a cloud endpoint instead of a z/OS endpoint. The default value is true to use a z/OS endpoint.

++HBRMLZRESTURLSUFFIX++

A URL suffix to add to the end of a REST API URL: 

++HBRMLZRESTBASEURL++/ deployment id / ++HBRMLZRESTURLSUFFIX++

For example, the URL looks like this:

south.ml.cloud.ibm.com/ml/v4/deployments/30d8241b-49ad-48e1-8c68-3f142484ff91/predictions?version=2021-05-01

If no value is specified, the default value is as follows:

/predictions?version=yyyy-MM-dd

The parameter yyyy-MM-dd is substituted with the day's date, and results in the latest version being obtained.

Note: If the deployment ID specified in the rule application contains a '/', no suffix is appended.
Table 7. Configuration variables for configuring zRule Execution Server for z/OS running on a CICS JVM server.
Variable Description

++CICSHLQ++

 The high-level qualifier for CICS.

Example: CTS510.CICS

++CICSCSDDSN++

 The high-level qualifier for the CICS system.

Example: CTS510.APPLID.DFHCSD

++CICSAPPLID++

The APPLID of the CICS region.

++JDBCPLAN++

Plan that is used for JDBC connections and CICS.

Example: DSNJCC
Table 8. Configuration variables for configuring IMS to run rules on a zRule Execution Server for z/OS instance.
Variable Description
++IMSHLQ++ The high-level qualifier for the datasets of the main IMS installation.

Example: IMS.V12.DBDC
++IMSREGID++ The ID of the IMS instance to be used.

Example: IM0A
++IMSREGHLQ++ The high-level qualifier of the IMS region datasets.

Example: IMSDATA.IM0A
Table 9. Configuration variables for configuring a Db2 database for Decision Runtime for z/OS.
Variable Description
++HBRWORKDS++ You can obscure the password HBRDBPASSWORD to prevent casual observation:
  1. Set a value for this property in ++HBRWORKDS++.SHBRPARM(HBRPSIST).
  2. Submit ++HBRWORKDS++.SHBRJCL(HBRPWDEN).

    The value HBRDBPASSWORD is replaced with HBRDBPASSENCR, which contains an obscured value.

To change the password at a later date:
  1. Replace property HBRDBPASSENCR with HBRDBPASSWORD=newpassword.
  2. Submit ++HBRWORKDS++.SHBRJCL(HBRPWDEN).
++DB2HLQ++ The high-level qualifier for the Db2 data sets.

Example: SYS2.DB2.V11
++DB2GROUP++ The RACFRACF group that is granted access across the ODM tables. Connect ++DB2USER++ to this group.

Example: DB2GROUP
++DB2RUNLIB++ The Db2 runtime library.

Example: DSNV11GP.RUNLIB.LOAD
++DB2SUBSYSTEM++ The Db2 subsystem name.

Example: DJGP
++DB2LOCATION++ The Db2 location name that is used to connect to this Db2 subsystem.

Example: DSNV11GP

++DB2VCAT++ The Db2 integrated catalog facility catalog.

Example: DSNV11GP
++DB2ADMIN++ The user ID authorized to create Db2 databases.

Example: DB2ADMIN
++DB2SCHEMA++ The schema that is used to create and access the Db2 artifacts.

Example: HBR
++RESDATABASE++ The name of the database that is used by the zRule Execution Server for z/OS instance.

Example: RESDB1
++RESSTOGROUP++ The name of the storage group that is used by the zRule Execution Server for z/OS instance.

Example: RESSTG1
++DB2TABLEBP++ The buffer pool name for the tables.

Example: BP1
++DB2INDEXBP++ The buffer pool name for the indexes.

Example: BP2
++DB2LOBBP++ The buffer pool name for large objects.

Example: BP3
++DB2SAMPLEPROGRAM++ The Db2 program name.

Example: DSNTEP2
++DB2SAMPLEPROGRAMPLAN++ The Db2 plan name.

Example: DSNTEP10
++DB2BP4K++ The buffer pool name for 4 K objects.

Example: BP4K
++DB2BP8K++ The buffer pool name for 8 K objects.

Example: BP8K1
++DB2BP32K++ The buffer pool name for 32 K objects.

Example: BP32K
++DB2USER++ The user ID for accessing the Db2 database.

Example: DB2USER.
++DB2PSWD++ The password for accessing the Db2 database.

Example: DB2PASSWD.
++DB2JARLOCN++ The location of the Db2 classes.

Example: /usr/lpp/db211/classes
++DB2NATIVELOC++ The location of the Db2 native library files.

Example: /usr/lpp/db2v11/jdbc/lib
++DB2SERVNAME++ The Db2 host name or IP address.

Example: winmvsm.ibm.com
++DB2PORT++ The Db2 connection port.

Example: 40100
Table 10. Configuration variables for enabling wsadmin scripts for Decision Runtime for z/OS.
Variable Description
++RESADMIN++ The administrator user group for Rule Execution Server.

Example: resAdministrators
++RESDEPLOY++ The deployer user group for Rule Execution Server.

Example: resDeployers
++RESMONITOR++ The monitor user group for Rule Execution Server.

Example: resMonitors
++RESADMINUSER++ An admin user for Rule Execution Server.

Default value: resAdmin
++RESDEPLOYUSER++ A deployer user for Rule Execution Server.

Default value: resDeployer
++RESMONITORUSER++ A monitor user for Rule Execution Server.

Default value: resMonitor
Table 11. Configuration variables for configuring Liberty profile
Variable Description
++WLPSAFPREF++ The name of the SAF profile prefix that is used for SAF profile names.

Default value: BBGZDFLT
++WLPUSERDIR++ The WebSphere Liberty profile user directory that contains the servers directory.
++WLPSERVER++ The name of your WebSphere Liberty server.
++WLPPORT++ The HTTP port for your WebSphere Liberty server.
++WLPSECUREPORT++ The HTTP secure port for your WebSphere Liberty server.
++WLPINSTDIR++ The installation directory for your WebSphere Liberty profile runtime.

Example: /was/Liberty
++WLPVERSION++ The version of WebSphere® Liberty Profile.

Example: 18
++WLPTYPE++ The type of WebSphere Liberty profile to install Operational Decision Manager into.

Specify STD for standard WebSphere Liberty profile and CICS for CICS WebSphere Liberty profile.
++WLPANGELNAME++ Specifies the name of the Liberty Angel process which this Liberty server should use.
++HBRWOLACELL++ The first part of the WOLA group name. If set it must begin with "HBRWOLA" and be 8 characters in length. Default value: HBRWOLA.

HBRWOLACELL must be unique for each instance of WebSphere Liberty running on the LPAR.
++HBRWOLANODE++ The second part of the WOLA group name. Can be any value but must be 8 characters or less.

HBRWOLANODE must be unique for each instance of WebSphere Liberty running on the LPAR.
++HBRWOLASERVER++ The third part of the WOLA group name. Can be any value but must be 8 characters or less.

HBRWOLASERVER must be unique for each instance of WebSphere Liberty running on the LPAR.
Table 12. Configuration variables for configuring SMF
Variable Description
++HBRSMFST100++ Set this variable to YES to enable output of SMF execution data under zRule Execution Server for z/OS or CICS.

Default value: NO
++PSMFDS++ Set this variable to contain the name of the SMF primary dataset for your system.

The value can be obtained by issuing /D SMF in SDSF.
++SSMFDS++ Set this variable to contain the name of the SMF secondary dataset for your system.

The value can be obtained by issuing /D SMF in SDSF.
++CSVPATH++ If you are using the HBRSMFC sample program, set this variable to contain the name of the HFS directory where the CSV file must be written.