Contents of Customization Input File

This topic describes in detail the contents of the Customization Input File (mqsicompcif), which holds configuration data needed for component customization. See Example Customization Input File (mqsicompcif) and use it to collect your configuration information.

All environment variables need to be made explicit in mqscompcif. For example do not use $JAVAHOME; write the full path of the Java home directory. This is because ENVFILE is parsed by BPXBATCH before the shell environment for the started task has been created, and BPXBATCH does not recognize the use of $ to indicate environment variables.

Component name and key

Each component must have a component name and a component key.

When deciding on component names and keys, use the name of the queue manager appended with either BRK for a broker or UNS for a User Name Server as the component key. When you follow this naming convention you might have, for example:
Component name Broker User Name Server
Component key MQP1BRK MQP1UNS

Create the started task procedure with the same name as your broker to avoid confusion. Although your started task and broker can have different names, it is easier to manage if you make the broker component name and component key the name of the started task procedure. However, you are free to choose your own values as long as they comply with the requirements below. Additionally, you are recommended to choose uppercase-only names.

The component name is used in the workbench on Windows to identify different brokers. The User Name Server always has the component name UserNameServer, which you cannot change. The broker name must follow the following naming restrictions:
  • The name must not exceed 64 characters in length.
  • It must start with an alphanumeric character.
  • It can contain alphanumeric characters. The following characters are also accepted:

    = (equals)

    - (dash)

    _ (underscore)

    . (dot)

If you expect to trace the operation of an execution group, restrict the name of the execution group to include only the valid alphabetic and numeric characters listed above (US English alphabet only). The trace commands do not support the use of special characters for an execution group name.

The acceptable characters are representations in code page 1047. Because component names are part of the messages displayed on the system log, ensure that your broker names contain only characters that your system log can display. You are recommend to use digits and uppercase letters.

Add your component name and component key to your copy of the Customization planning checklist for z/OS.
Queue manager name
The name of the queue manager used. Typically, the queue manager name is part of the broker name.
Brokername
If you make this the same name as the started task, it is easier to manage. This name is used by the Configuration Manager.
ComponentDirectory
This is a directory in an HFS. You create the component directory manually at the start of customization. For more information about the size of the directory, see Disk space requirements (z/OS). Also, add this name to the Create commands checklist.
UserNameServerQueueManagerName
If you plan to use a User Name Server for Publish/Subscribe authentication, this is the name of the queue manager where the broker resides. Note that, on non-z/OS platforms, this name can be a long name.

DB2 information

Specify the following values related to DB2 in the Customization Input File. You might need to speak to your DB2 administrator to collect these values. You can also add these names to the Customization planning checklist for z/OS.
DB2_SAMPLE_PGMNAME
Name of the DB2 sample program, used to run DB2 statements in batch. This is usually DSNTIAD or DSNTEP2, but your installation might have changed it. If you use SPUFI, run the query select name from SYSIBM.SYSPLAN. This shows you all the plans defined. Ensure that you include the library containing this program in the STEPLIB concatenation.
DB2_SAMPLE_PGMPLAN
Name of the DB2 sample program plan.
DB2_DSNACLI_PLANNAME
Name of the DSNACLI plan used by your DB2.
DB2_SUBSYSTEM
DB2 subsystem name. This is used by the DB2 customization JCL. You can use the DB2 global data sharing name, or the name of the DB2 subsystem itself.
DB2_LOCATION
DB2 location name. When your DB2 system starts up, you get a message DSNL004I DDF START COMPLETE. The location needed during your configuration is just after this message.
DB2_TABLE_OWNER
DB2 table owner (CURRENTSQLID). This prefix is used to create and access the DB2 tables. Each broker must have its own set of DB2 tables. This table owner is used to qualify the different tables, similar to a data set high level qualifier. This is referred to in the ODBC documentation as the CurrentSQLID. See Setting up DB2 for further information.
DB2_STORAGE_GROUP
DB2 storage group name.
DB2_STOR_GROUP_VCAT
ICF catalogue name. The DB2 data sets for the broker are cataloged here. If the catalog name is longer than 8 characters, use an alias instead.
DB2_STOR_GROUP_VOL
DB2 storage group volume or '*' for SMS managed volumes. Used for the broker only. This identifies the DASD volumes to be used for the DB2 tables.
DB2_DATABASE
DB2 database name, which can be the name of the broker.
DB2_BUFFER_POOL
DB2 buffer pool name.

WebSphere Business Integration Message Broker for z/OS information

Component PDSE
You need to allocate a partitioned data set (PDSE) for each component to hold all the necessary jobs, procedures and input data to customize and administer the component. You create the component PDSE manually at the start of customization. You can use a PDS instead of a PDSE. However, PDSs do not automatically reuse free space and you might experience problems during recustomization, and have to manually compress the data set.

Select a name that fits your installation naming convention and have the broker name as part of the data set name. For example, use WMQI.MQP1BRK.CNTL or MQ.MQP1BRK.BIPCNTL, where MQP1 is the queue manager being used. WebSphere Business Integration Message Broker, DB2, WebSphere MQ and z/OS administrators need UPDATE access to this PDSE.

Add the name of the PDSE to your copy of the Customization planning checklist for z/OS.

Component key
The component key must be unique for each broker and is usually given the name of that broker.
STPN (Started Task Procedure Name)
Each component is started using JCL and runs as a started task. The name of the started task procedure can be a maximum of 7 characters long and must not begin with the characters BIP. Give the started task the same name as your broker to avoid confusion.

Add the name of the started task procedure to your copy of the Customization planning checklist for z/OS.

USER_PROCLIB_PDS
The started task procedure is copied to a SYS1.PROCLIB concatenation PDS. The customization creates a job that performs this copy. Specify the name of the PDS that will be used. You can also copy the procedure manually.
STEPLIB_NAME
The data set names for the corequisite libraries, DB2, WebSphere MQ, and Language Environment (LE). The JCL produced by customization refers to this name. See Setting up JCL for corequisite products.
JAVAHOME
Points to the root directory of your Java installation.
Check that you have the correct version of Java installed (see Checking the level of Java). If it is, issue the command whence java. The result will be similar to the following:
/usr/lpp/java/IBM/J1.4/bin/java
Take the path up to, but not including, the bin directory, as your JAVAHOME. Add this path to your copy of the Customization planning checklist for z/OS.
CLASSPATH
Use the default unless you want to install plug-ins. Refer to the relevant documentation for this information.
PATH
Use the default unless you want to install plug-ins. Refer to the relevant documentation for this information.
LIBPATH
Use the default unless you want to install plug-ins. Refer to the relevant documentation for this information.
LILPATH
Use the default unless you want to install plug-ins. Refer to the relevant documentation for this information.
DISTHUB_PATH
The location of the distribution hub executables. Use the default unless you have installed the distribution hub in a non-standard location.
LANG
A UNIX System Services environment variable. It specifies the international language value so that WebSphere Business Integration Message Broker messages are output in the locale's language. The default is En_US; you can change it Ja_JP or Zh_CN. Add the value of LANG to your copy of the Customization planning checklist for z/OS.
LC_ALL
UNIX System Services environment variable used in conjunction with LANG. It allows you to override other environment variables starting with LC_ . The default is En_US, and you can change it to Ja_JP or Zh_CN. Add the value of the LC_ALL to your copy of the Customization planning checklist for z/OS.
TZ
Time Zone settings that hold the time zone setting in which you are located. Refer to the UNIX System Services User's Guide for more information. Add the value of TZ to your copy of the Customization planning checklist for z/OS.
NLSPATH
Use the default unless you want to install plug-ins. Refer to the relevant documentation for this information.
CONSOLE_NLSPATH
Use the default unless you want to install plug-ins. Refer to the relevant documentation for this information.
MC_MESSAGES
Whether console messages appear in mixed case or uppercase. Add the value of the MC_MESSAGES to your copy of the Customization planning checklist for z/OS.
DB2_CONVERSION
The DB2 convertor; follow the instructions in the CIF to tailor your DB2_CONVERSION setting.
JOBCARDBEGIN and JOBCARDEND
Follow the instructions in the CIF to tailor your JOBCARD. The syntax of the job card parameters is the same as described in the MVS JCL Reference.
ENVIRONMENTBEGIN and ENVIRONMENTEND
Follow the instructions in the CIF to tailor your environment variables.

Automatic Restart Manager planning

WebSphere Business Integration Message Broker for z/OS allows you to register a component to the Automatic Restart Manager (ARM).

When customizing a broker for the first time, you can allow USE_ARM to default to NO. Revisit it when you prepare your production system. To enable ARM, you can change this value and recustomize

To enable automatic restart:
  • Set up an ARM couple data set.
  • Define the automatic restart actions that you want z/OS to perform in an ARM policy.
  • Start the ARM policy.
The following manuals provide detailed information about ARM couple data sets, including samples:
  • z/OS MVS Programming: Sysplex Services Guide
  • z/OS MVS Programming: Sysplex Services Reference
  • z/OS MVS Setting up a Sysplex

To register a component to ARM at startup, set USE_ARM to YES. You then have to supply values for the variables ARM_ELEMENTNAME and ARM_ELEMENTTYPE.

ARM_ELEMENTNAME can be a maximum of 8 characters in length, because WebSphere Business Integration Message Broker adds a prefix of SYSWMQI. For example, if you supply the value MQP1BRK to ARM_ELEMENTNAME, the element you define in your ARM policy is SYSWMQI_MQP1BRK.

Specify the following values in the Customization Input File:
Description Name
Switch that determines whether ARM will be used (YES or NO). USE_ARM
ARM element name ARM_ELEMENTNAME
ARM element type ARM_ELEMENTTYPE

Add these values to the Customization planning checklist for z/OS.