TXSeries For Multiplatforms Using CICS Workload Management Version 6.2

TXSeries for Multiplatforms
Using CICS Workload Management

Version 6.2
SC34-6638-02

Version 6.2
SC34-6638-02
Note
Before using this information and the product it supports, be sure to read the general information under Notices on page
131.
Third Edition (January 2008)

Order publications through your IBM representative or through the IBM branch office serving your locality.
Copyright International Business Machines Corporation 1999, 2008. All rights reserved.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures
. . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
About this book . . . . .
Who should read this book . .
Document organization . . .
Conventions used in this book
How to send your comments .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Chapter 1. Understanding CICS WLM . . . . . . . . . . . . . .

Using CICS WLM to optimize the CPU usage of multiple machines . . . .
Using CICS WLM to optimize internal communications on a single machine .
Planning for CICS WLM . . . . . . . . . . . . . . . . . . . .
.
.
.
.
.
.
.
.
1
2
3
3
Chapter 2. Components of WLM . . . . .

Global and local cache components . . . .
The workload management application cache
The workload management cache manager .
The workload management client . . . . .
The Health Monitor . . . . . . . . . . .
The Routing Monitor . . . . . . . . . .
WLM-provided user exit codes . . . . . .
WLM command set . . . . . . . . . . .
The initialization file . . . . . . . . . .
The configuration file . . . . . . . . . .
The configuration file parser and loader . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5
5
6
6
6
7
7
8
8
8
8
9
Chapter 3. Describing the environment

Object model specifications . . . . .
Object model hierarchy . . . . . .
Plex objects . . . . . . . . . .
SystemModel object . . . . . . .
SystemClone objects. . . . . . .
SystemImage objects . . . . . .
Node objects . . . . . . . . .
Connection objects . . . . . . .
ResourceModel objects . . . . . .
.
.
.
.
.
to
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
CICS WLM utility

. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
Chapter 4. Preparing for CICS WLM . . . . .

Gathering information for a CICS WLM environment
Examples of CICS environments . . . . . . .
Example environment using a Windows Client .
Example environment using a single machine .
Using the concept of following a work request .
Planning the location of CICS WLM components .
Environmental considerations required for WLM . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. xi
. xi
. xi
. xii
. xiii
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
11
11
13
13
15
15
16
16
16
17
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
21
21
22
22
23
24
24
25
Chapter 5. Customizing CICS WLM to your environment

Suggested sequence of events . . . . . . . . . . .
Describing the environment to CICS WLM . . . . . . .
Specifications for the Plex object . . . . . . . . .
Verifying and loading the configuration file . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
27
27
27
29
33
Copyright IBM Corp. 1999, 2008
.
.
.
.
.
.
.
.
.
.
.
.
.
iii
Customizing the initialization file . . . . . . . . . . .

Performing the initial configuration . . . . . . . . . . .
Modifying CICS definitions. . . . . . . . . . . . . .
Setting up the remote resource definitions . . . . . . .
Setting up CICS WLM user exits . . . . . . . . . . .
Distributed Program Link workload management . . . .
Dynamic Transaction Routing workload management . . .
Setting environment variables for EPI routing management
Defining an ApplicationModel . . . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
33
34
34
35
36
36
37
37
38
Chapter 6. Starting CICS WLM for

Before you start the CICS WLM .
Initial activation sequence . . . .
Starting a WAP . . . . . . . .
Starting a WCM . . . . . . .
Verifying the configuration file . .
Loading the configuration file . . .
the first time .

. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
39
39
40
41
41
41
42
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
43
44
44
45
Chapter 8. Creating a simple routing environment . . . . . .

The sample environment . . . . . . . . . . . . . . . .
CICS setup . . . . . . . . . . . . . . . . . . . . .
CICS system setup . . . . . . . . . . . . . . . . .
Application program setup . . . . . . . . . . . . . . .
CICS WLM setup . . . . . . . . . . . . . . . . . .
Ensuring that request routing works correctly without CICS WLM
Issuing routing requests using CICS WLM . . . . . . . . .
Validating routing requests . . . . . . . . . . . . . .
Application source code for DPL requests (called.css) . . . . .
Application source code for DTR requests (wlmt.ccs) . . . . . .
Application source code for ECI requests (cicseciwlm.c) . . . . .
Application source code for EPI requests (cicsepiwlm.c) . . . . .
Initialization file for Routing Test sample code . . . . . . . .
Configuration file for Routing Test sample code . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
47
47
48
49
49
52
52
53
54
55
55
56
59
64
64
Chapter 9. Using and maintaining CICS WLM

Stopping a WAP . . . . . . . . . . . .
Stopping a WCM . . . . . . . . . . . .
The effects of stopping and starting components
Listing active components . . . . . . . . .
Cleaning up CICS WLM resources . . . . .
Emptying CICS WLM resources . . . . .
Purging CICS WLM components . . . . .
Scheduled housekeeping procedures . . . .
Chapter 7. Testing CICS WLM . . . . . .

Using testing tools and a testing environment
Starting the HMON . . . . . . . . . .
Starting the RMON . . . . . . . . . .
|
|
|
|
|
|
|
iv
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
69
69
69
69
70
70
71
71
72
Chapter 10. CICS WLM configuration tool-cicswlmcfg

Creating a typical WLM configuration . . . . . . . .
Configuration commands . . . . . . . . . . . .
add - Adds object types . . . . . . . . . . . . .
delete - Deletes an object . . . . . . . . . . . .
modify - Modifies attributes of existing object . . . . .
verify - Checks for syntax errors . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
73
75
76
78
79
80
81
TXSeries for Multiplatforms: Using CICS Workload Management
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
|
|
|
|
|
|
|
list - Lists available configuration files . . . . .

Configuring WLM with IBM TXSeries Administration
The Plex Attributes . . . . . . . . . . . .
The Region Attributes . . . . . . . . . .
The Connection Attributes . . . . . . . . .
The Program/Transaction Attributes . . . . .
cicswlmcfg return codes . . . . . . . . . .
. . .
Console
. . .
. . .
. . .
. . .
. . .
Chapter 11. Adding resources to WLM . . . .

Adding a new program . . . . . . . . . . .
Adding a new CICS system . . . . . . . . .
A sample configuration of the WLM definition with
. . .
. . .
. . .
added
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
82
83
85
87
87
87
88
. . . .
. . . .
. . . .
resources
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
91
91
92
95
Appendix A. Volume testing . . . . . . . . . . . . . . . . . . . 101

Appendix B. Routing Monitor displays . . . . . .
The RMON display of available Plexes . . . . . .
The RMON display of available regions . . . . . .
The RMON display of routed requests distribution . .
The RMON display of routed programs and transactions
Determining routing outcome . . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
103
103
104
105
106
106
Appendix C. Troubleshooting . . . . . . . .
How to determine whether the WAP is started . . .
How to determine whether the WCM is started . . .
How to determine whether the user exits are in place
How to validate the CICS environment . . . . . .
How to check the configuration file . . . . . . .
Additional problem diagnosis . . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
107
108
108
109
109
110
110
CICS WLM
. . . . .
. . . . .
. . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
113
113
114
115
Appendix D. Directory structure created

Files created by CICS WLM. . . . . .
Files in the /var/cicssm/log directory . . .
Files in the /tmp directory . . . . . .
by
.
.
.
Appendix E. Code for the sample wlm.cfg

|
.
.
.
.
.
.
.
installing
. . . .
. . . .
. . . .
. . . . . . . . . . . . . 117
Appendix F. The generated WLM configuration file . . . . . . . . . . 121

Appendix G. Complete list of CICS WLM commands . . . . . . . . . 125
Appendix H. Glossary of CICS WLM terms . . . . . . . . . . . . . 127
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Trademarks and service marks . . . . . . . . . . . . . . . . . . 132
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Contents
vi
Figures
|
|
|
|
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
Environmental changes introduced through the use of CICS WLM . . . . . . . . . . . . . 2

CICS WLM components . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
CICS WLM object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Example environment using a Windows Client . . . . . . . . . . . . . . . . . . . . 22
Example environment using a single machine . . . . . . . . . . . . . . . . . . . . 23
The WLM configuration file cfgdb1 (the absolute file name is /var/cicssm/repos/cfgdb1.cfg)
76
IBM TXSeries Administration Console WLM Configuration . . . . . . . . . . . . . . . . 83
IBM TXSeries Administration Console Plex Database list . . . . . . . . . . . . . . . . 84
IBM TXSeries Administration Console Plex Objects . . . . . . . . . . . . . . . . . . 85
The RMON display of available Plexes . . . . . . . . . . . . . . . . . . . . . . 103
The RMON display of CICS regions available to WLM . . . . . . . . . . . . . . . . 104
The RMON display showing the distribution of routed requests . . . . . . . . . . . . . 105
The RMON display of routed programs and transactions . . . . . . . . . . . . . . . . 106
vii
viii
Tables
|
|
|
|
|
|
|
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
A road map for Using CICS Workload Management . . . . . . . . . . . . . . . . . . xi

Conventions that are used in this book . . . . . . . . . . . . . . . . . . . . . . . xii
Object models used by CICS WLM . . . . . . . . . . . . . . . . . . . . . . . . 12
Attributes and defaults for a Plex configuration . . . . . . . . . . . . . . . . . . . . 14
Attributes and defaults for a SystemClone object . . . . . . . . . . . . . . . . . . . 16
Attributes and defaults for a Connection object . . . . . . . . . . . . . . . . . . . . 17
Attributes and defaults for a ResourceModel object . . . . . . . . . . . . . . . . . . 18
Relationship associations for a ResourceModel configuration . . . . . . . . . . . . . . 18
Communication information for the sample environment . . . . . . . . . . . . . . . . 48
Relationship between object types and commands in cicswlmcfg . . . . . . . . . . . . . 73
Options and their meaning . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Attributes and defaults for a Plex configuration . . . . . . . . . . . . . . . . . . . . 85
Attributes and defaults for a region object . . . . . . . . . . . . . . . . . . . . . . 87
Attributes and defaults for a connection object . . . . . . . . . . . . . . . . . . . . 87
Attributes and defaults for a program/transaction object . . . . . . . . . . . . . . . . 88
cicswlmcfg return codes and their meaning . . . . . . . . . . . . . . . . . . . . . 88
Space requirements for installing CICS WLM . . . . . . . . . . . . . . . . . . . . 113
Directory structure for the install_dir/cicssm directory . . . . . . . . . . . . . . . . . 113
Directory structure for the /var/cicssm directory . . . . . . . . . . . . . . . . . . . 113
File structure created by CICS WLM in the /tmp directory . . . . . . . . . . . . . . . 115
ix
About this book

The CICS Workload Management utility (CICS WLM) optimizes the distribution of
processing tasks for CICS in the AIX environment. This document discusses the
concepts, components, and terminology that are relevant to WLM. It describes the
planning that you must do before you install, configure, operate, and troubleshoot
WLM in a CICS environment.
Who should read this book

This document is for system administrators who are responsible for the
configuration, operation, and management of machines running CICS in an AIX
network. The reader is expected to be familiar with common CICS concepts and
terminology. This document discusses the specific concepts and terminology that
are associated with WLM.
Document organization
Table 1. A road map for Using CICS Workload Management
If you want to...
Refer to...
Understanding CICS Workload Management...

Read a conceptual overview of WLM
Chapter 1, Understanding CICS WLM, on

page 1
Learn about WLM components
Chapter 2, Components of WLM, on page 5
Learn about the CICS WLM object model
Chapter 3, Describing the environment to

CICS WLM utility, on page 11
Preparing for CICS Workload Management...

Read about the preparation that you must do Chapter 4, Preparing for CICS WLM, on
to ready your system for CICS WLM
page 21
Learn about customizing CICS WLM to your
environment
Chapter 5, Customizing CICS WLM to your

environment, on page 27
See a sample CICS WLM Plex configuration

file
Sample configuration file (wlm.cfg) on page

29
See the steps for initial activation of CICS

WLM
Chapter 6, Starting CICS WLM for the first

time, on page 39
Get information about testing your

implementation of CICS WLM
Chapter 7, Testing CICS WLM, on page 43
See a simple WLM environment for testing

routing outcomes
Chapter 8, Creating a simple routing

environment, on page 47
Using CICS Workload Management...

Learn about using and maintaining WLM
components
Chapter 9, Using and maintaining CICS

WLM, on page 69
Learn about the WLM configuration tool cicswlmcfg
Chapter 10, CICS WLM configuration

tool-cicswlmcfg, on page 73
Learn about adding new resources to your

WLM configuration
Chapter 11, Adding resources to WLM, on

page 91
Learn about volume testing
Appendix A, Volume testing, on page 101
See example displays of the Routing Monitor Appendix B, Routing Monitor displays, on
page 103
xi
Table 1. A road map for Using CICS Workload Management (continued)

If you want to...
Refer to...
Learn about troubleshooting
Appendix C, Troubleshooting, on page 107
Examine the file structure created by CICS

WLM
Appendix D, Directory structure created by

installing CICS WLM, on page 113
Look at the code for the sample wlm.cfg
Appendix E, Code for the sample wlm.cfg,

on page 117
Look at the generated WLM configuration file Appendix F, The generated WLM
configuration file, on page 121
See a complete list of CICS WLM commands Appendix G, Complete list of CICS WLM
commands, on page 125
Refer to the Glossary
Appendix H, Glossary of CICS WLM terms,

on page 127
Conventions used in this book

TXSeries for Multiplatforms documentation uses the following typographical and
keying conventions.
Table 2. Conventions that are used in this book
xii
Convention
Meaning
Bold
Indicates values that you must use literally, such as commands,

functions, and resource definition attributes and their values. When
referring to graphical user interfaces (GUIs), bold also indicates
menus, menu items, labels, buttons, icons, and folders.
Monospace
Indicates text that you must enter at a command prompt. Monospace

also indicates screen text and code examples.
Italics
Indicates variable values that you must provide (for example, you
supply the name of a file for file_name). Italics also indicates
emphasis and the titles of books.
<>
Encloses the names of keys on the keyboard.
<Ctrl-x>
Where x is the name of a key, indicates a control-character

sequence. For example, <Ctrl-c> means hold down the Ctrl key
while you press the c key.
<Return>
Refers to the key labeled with the word Return, the word Enter, or
the left arrow.
Represents the UNIX command-shell prompt for a command that

does not require root privileges.
Represents the UNIX command-shell prompt for a command that

requires root privileges.
C:\>
Represents the Windows command prompt.
>
When used to describe a menu, shows a series of menu selections.

For example, Select File > New means From the File menu,
select the New command.
Entering commands
When instructed to enter or issue a command, type the command

and then press <Return>. For example, the instruction Enter the ls
command means type ls at a command prompt and then press
<Return>.
[]
Encloses optional items in syntax descriptions.
Table 2. Conventions that are used in this book (continued)

Convention
Meaning
{}
Encloses lists from which you must choose an item in syntax

descriptions.
Separates items in a list of choices enclosed in { } (braces) in syntax

descriptions.
...
Ellipses in syntax descriptions indicate that you can repeat the

preceding item one or more times. Ellipses in examples indicate that
information was omitted from the example for the sake of brevity.
IN
In function descriptions, indicates parameters whose values are used

to pass data to the function. These parameters are not used to
return modified data to the calling routine. (Do not include the IN
declaration in your code.)
OUT
In function descriptions, indicates parameters whose values are used

to return modified data to the calling routine. These parameters are
not used to pass data to the function. (Do not include the OUT
declaration in your code.)
INOUT
In function descriptions, indicates parameters whose values are

passed to the function, modified by the function, and returned to the
calling routine. These parameters serve as both IN and OUT
parameters. (Do not include the INOUT declaration in your code.)
$CICS
Indicates the full path name of the location in which the CICS
product is installed; for example, /usr/lpp/cics on AIX. If the CICS
environment variable is set to the product path name, you can use
the examples exactly as shown in this book; otherwise, you must
replace all instances of $CICS with the CICS product path name.
CICS on Open
Systems
Refers collectively to the CICS product for all supported UNIX

platforms.
TXSeries for
Multiplatforms
Refers collectively to the CICS for AIX, CICS for HP-UX, and CICS
for Windows products.
CICS
Refers generically to the CICS for AIX, CICS for HP-UX, and CICS
for Windows products. Other CICS products in the CICS Family are
distinguished by their operating system (for example, IBM
mainframe-based CICS for the z/OS platform).
How to send your comments

Your feedback is important in helping to provide the most accurate and highest
quality information. If you have any comments about this book or any other
TXSeries for Multiplatforms documentation, send your comments by e-mail to
idrcf@hursley.ibm.com. Be sure to include the name of the book, the document
number of the book, the version of TXSeries for Multiplatforms, and, if applicable,
the specific location of the information on which you are commenting (for example,
a page number or table number).
About this book
xiii
xiv
Chapter 1. Understanding CICS WLM

The CICS WLM utility is a stand-alone utility that optimizes the distribution of
processing tasks in a CICS environment that has two or more regions that can
process work requests. The CICS WLM utility is designed to work in an AIX system
in which CICS already exists and is configured and defined to the WLM utility.
This utility is included with CICS for AIX products. Appendix D, Directory structure
created by installing CICS WLM, on page 113 shows the directory structure that is
created when the CICS WLM code is installed. The discussion in this document
focuses on the analysis that you must do to deploy workload management in your
environment.
The CICS WLM utility improves service in the following ways:
v It increases application availability by enabling applications to be accessed from
multiple locations.
v It optimizes the use of available processing power by using a distribution
algorithm to route tasks. On the AIX platform, work requests using Distributed
Program Linking (DPL), Dynamic Transaction Routing (DTR), or from CICS
Universal Client or CICS Transaction Gateway can be routed by CICS WLM.
v It improves continuity of service by enabling requests to be routed to a healthy
server.
v It provides growth capability by enabling another instance of the common system
to be created and added to the WLM configuration.
v It enables transparent maintenance and upgrading of a shutdown server while an
application continues to be available for users.
v It saves the cost of hardware upgrades by spreading work requests over all
available Central Processing Units (CPUs) in the configuration.
CICS WLM uses the algorithm distribution approach to determine where to route
work requests. The Algorithm approach monitors the environment that is defined to
CICS WLM and adjusts its distribution in response to environmental conditions.
Monitored environmental conditions include:
v The turnaround time that is achieved by each server for a piece of work
v The health of each of the servers
v Identification of the types of processing that each server can perform
v Assessment of the communications costs that are incurred in reaching each
server
The CICS WLM utility can:
v Monitor the defined Application Owning Regions (AORs), and assign a health
value for each AOR server. The health value is a representation of the regions
current availability.
v Base its routing assignment on the most-recent performance statistics, instead of
on static averages. CICS WLM does this by continually recalculating a score for
each server that is a composite of the servers health value, the weighting
assigned for the servers capability, and its processing cost.
v Customize the distribution algorithm through modifying the collection of variables
that make up the composite score that is used for distribution assignment. See
Chapter 3, Describing the environment to CICS WLM utility, on page 11 for
more discussion and examples of these variables.
v Enable the distributed management of work from any CICS client to any remote
system from a Client Owning Region (COR). The COR must be a server that is
running CICS on AIX . In a completely distributed environment, work is routed
between CICS for Open System servers. In a more complex environment, work
is routed to other CICS systems, such as CICS for ESA. The CICS WLM utility
can manage the distribution of work to a remote system when an entry exists for
a CICS Communications Definition (CD) to represent the remote system.
Using CICS WLM to optimize the CPU usage of multiple machines

The ideal approach for workload management is to provide a common type of CICS
region that contains the resources that are required for the running of the specified
applications. This common region type is defined to CICS WLM as a SystemModel
object that can be reproduced on multiple systems. Multiple types of SystemModel
objects can be defined; each different SystemModel type is unique and contains the
resources that are required for the running of the applications that are specified for
it. (For additional discussion on SystemModel objects, see Chapter 3, Describing
the environment to CICS WLM utility, on page 11.)
Workload management distributes the incoming work requests over the systems
that can process the work. The combined machine resources are now available to
each application.
Although this approach is most valuable for your critical applications, it is also
useful in other conditions. The example in Figure 1 shows an AIX environment with
three separate CICS regions, each running a separate application. Consider this
scenario within the depicted environment: The application on Machine 1 is
approaching the limit of its CPU capacity. Machines 2 and 3 are lightly used. In the
workload-managed environment, the work of each application can be distributed
across the processing power of the three regions.
Beneficial outcome from using CICS WLM

CICS
CICS
CICS
Application Application Application
3
2
1
CICS
for AIX
CICS
for AIX
CICS
for AIX
AIX CICS
Client
AIX CICS
Client
AIX CICS
Client
CICS Application 1
CICS Application 1
CICS Application 1
CICS Application 2
CICS Application 2
CICS Application 2
CICS Application 3
CICS Application 3
CICS Application 3
CICS
for AIX
CICS
for AIX
CICS
for AIX
CICS for
AIX
AIX CICS
Client
WLM
AIX CICS
Client
Figure 1. Environmental changes introduced through the use of CICS WLM
A major benefit from this restructuring is seen on Machine 1, because it was

approaching its CPU limit. This restructuring provides additional capacity for
processing the work that is required by the application that is running on Machine 1.
The cost of buying a larger machine is saved.
As a result of this restructuring, the applications that are running on Machines 2 and
3 are now available on more systems. If any of the CICS systems or machines fails,
all the applications are still available.
Note: Figure 1 on page 2 is using CICS for AIX to show the benefits of using CICS
WLM.
Using CICS WLM to optimize internal communications on a single

machine
CICS WLM is most effective when used in an environment that combines multiple
machines. However, it also provides benefits to the management of multiple regions
on a single machine, especially when extensive communications are required with
databases. See Chapter 4, Preparing for CICS WLM, on page 21 for a discussion
about data access considerations.
Planning for CICS WLM

To customize CICS WLM for your environment, you need to do a thorough analysis.
The following steps are a guide through that analytic process:
1. You must understand the components that are in this utility. Chapter 2,
Components of WLM, on page 5 discusses these components.
2. You must become familiar with the internal object model that the CICS WLM
utility users to define the environment. Chapter 3, Describing the environment
to CICS WLM utility, on page 11 discusses this abstract definition of the CICS
WLM environment.
3. You must identify the types of work requests that are occurring in your
environment, and specifically clarify where those work requests are issued, how
they are to be routed, and where they are to be processed. Chapter 4,
Preparing for CICS WLM, on page 21 discusses ways to do this analysis.
4. You must be able to analyze the regions, machines, and resources in your own
environment and identify them with the internal objects that need to be defined
to the CICS WLM utility. Chapter 4, Preparing for CICS WLM, on page 21
discusses ways to do this analysis.
When you have completed this analysis, your are ready to install the CICS WLM
code, build the customized files, and make the modifications to your CICS
definitions that are needed for CICS WLM to be able to function in your
environment. See the TXSeries for Multiplatforms Installation Guidefor information
about installation. Chapter 5, Customizing CICS WLM to your environment, on
page 27 discusses the customization process.
Chapter 1. Understanding CICS WLM
Chapter 2. Components of WLM

CICS WLM consists of the following components:
v Global and local cache components:
The global Workload Management Application Program cache (WAP)
The local Workload Management Cache Manager (WCM)
v The Workload Management Client (WCL)
v The Health Monitor (HMON)
v The Routing Monitor (RMON)
v WLM-provided user exit codes
v The WLM command set
v The initialization file (cicssm.config)
v The configuration file (wlm.cfg)
v The configuration file parser and loader
Figure 2 shows the relationship between the components of CICS WLM.
Figure 2. CICS WLM components
Note: Figure 2 is using CICS for AIX to show the relationship between CICS WLM
components.
Global and local cache components

CICS WLM bases routing decisions on data about CICS regions and resources that
is held in two types of caches: global and local. The data is supplied to the caches
through a configuration file. CICS WLM uses one global cache and potentially many
local caches. The Workload Management Application Program cache (WAP) is
associated with the global cache, and a Workload Management Cache Manager
(WCM) is associated with each of the local caches. The global cache that is
associated with the WAP is called the WAP cache, and the local cache that is
associated with each WCM is called a WCM cache.
The workload management application cache

Information is placed into the WAP cache by the use of the commands that invoke
the configuration file parser and loader to read and load a user-supplied CICS WLM
configuration file. See Sample configuration file (wlm.cfg) on page 29 for more
details about the initial configuration file format and content. See Performing the
initial configuration on page 34 for a discussion about placing the WAP.
The WAP is the central control point of a CICS WLM configuration. The initial
configuration information and updates to the configuration are deposited in the
WAP. This information is transferred from the WAP cache to the WCM caches when
it is required. If the requested data is not available in the WCM cache, a request is
forwarded to the WAP to get the data from the global cache. If the data is not
available in the WAP cache, CICS WLM cannot make a routing decision. In that
case, the default system, as coded in the EXEC CICS LINK statement, or the
RemoteSysId, as configured in the CICS Program Definition (PD) or Transaction
Definition (TD) stanza for the resource, is used.
The workload management cache manager

A WCM is located on each machine on which a workload management routing
decision occurs. The WCM is associated with the point where the routing of CICS
requests takes place. At present this can be a CICS region. See Using the concept
of following a work request on page 24 and Chapter 8, Creating a simple routing
environment, on page 47 for more discussion about routing points.
The WAP cache transfers data to the local WCM cache. The WCM cache also
processes requests for data from workload management clients.
The workload management client

One Workload Management Client (WCL) exists for each CICS region that is
configured to make routing decisions. The WCL determines the most appropriate
CICS region to which work should be routed. On the AIX platform, CICS WLM
provides a CICS exit for Dynamic Transaction Routing (DTR) and Distributed
Program Links (DPL) work requests. All other ECI and EPI requests have to come
from the CICS Universal Client or CICS Transaction Gateway. (Earlier versions
CICS support RPC based ECI and EPI requests.)
The WCL does the following:
v Processes requests from CICS clients that are configured for WLM routing
determination
v Searches the WCM cache for the data that is required for the workload
management requests from CICS clients
v Applies a workload balancing algorithm to determine the optimal CICS system for
processing the work for a CICS client, then updates the cache to reflect this
decision
v Requests information from the WAP cache manager when the required data
cannot be found in the WCM cache
All WCLs on a machine use the same WCM. Each of the WCMs operates
independently; therefore, no information about the performance of CICS servers is
exchanged through WCM-to-WCM communications.
The WCL functions internally; it requires no start or stop procedure to be performed
by the administrator.
The Health Monitor

The Health Monitor (HMON) automatically detects the loss of a CICS system. The
HMON feeds the information about the loss of a CICS system into the routing
component of workload management, so work is automatically directed away from a
failed CICS system. Health monitoring is supplied with the CICS WLM utility. It can
be optionally started and stopped.
A CICS WLM health monitor (HMON) is located on the same machine as the WAP
is. The HMON continuously monitors the health of each of the CICS servers in the
current configuration. Environment variable settings control the frequency of health
monitoring. You do not need to install any code on the remote systems in a WLM
configuration to use the HMON component.
The HMON has three levels of state code values that it can associate with a CICS
system. These are:
v Level 1 The CICS system is running and can be contacted.
v Level 2 The CICS system is not running, but the host on which that system
runs can be contacted.
v Level 3 Neither the CICS system, nor machine on which it runs, can be
contacted.
Note: The health monitor uses the Remote Procedure Call (RPC)-based CICS EPI
client to communicate with the monitored CICS regions. Therefore, the
machine on which the HMON is installed must be running RPC, and the
client must operate successfully in the environment in which the HMON is
running.
In addition, the HMON monitors the health of object models based on the objects
composite algorithm weighting. It has three reporting levels ranging from 1, for
excellent, to 3, for out-of-service.
While the HMON is active, it overrides any health values that are assigned to CICS
regions in the configuration file, wlm.cfg. See Starting the HMON on page 44 for
discussion on the interaction between the health monitor and the configuration file,
wlm.cfg.
The Routing Monitor

The Routing Monitor (RMON) tracks activity in a WCM cache. It shows the routing
decisions that are made from all clients that are sharing a WCM. Use the Routing
Monitor to validate the routing of work requests that are passed to CICS WLM. The
RMON is installed on the same machine as the WAP is. An instance of the RMON
looks only at the WCM cache of the machine on which the RMON is running.
See Appendix B, Routing Monitor displays, on page 103 for a discussion about the
information the Routing Monitor screens display.
WLM-provided user exit codes

On the AIX platform, CICS WLM provides user exit code for DPL and DTR work
requests. If all requests are being routed though a Client Owning Region (COR),
the user exits need be installed only on the COR. These WLM user exits need to
be registered in the respective PD stanza of the COR.
If the user exits for DPL and DTR routings are installed on a machine, workload
management is enabled by CICS region. When multiple regions exist on a machine,
each region must designated for participation in workload management.
If a client on a machine issues a work request for a program or a transaction that is
not defined to the CICS WLM utility, CICS WLM cannot process the request. The
request is routed in accordance with the Program Definitions (PD) and Transaction
Definitions (TD) that are defined for that region.
Each of the CICS WLM-supplied user exits is provided as object code only. Each of
theses user exits is coded for use as the sole user of the exit. It is not possible to
combine the CICS WLM-supplied user exits with any versions of those CICS exits
that are already in place.
See Distributed Program Link workload management on page 36 and Dynamic
Transaction Routing workload management on page 37, for a discussion about
these user exits that CICS WLM supplies.
WLM command set

CICS WLM provides commands for manipulating its components. Command
examples are given throughout the document. A complete list of CICS WLM
commands is displayed in Appendix G, Complete list of CICS WLM commands, on
page 125.
The initialization file

The initialization file (cicssm.config) defines the component list for the CICS WLM
utility. It drives the initial configuration of each component; it is the input to the
cicswlm configure command.
On the AIX platform, a sample file /var/cicssm/repos/cicssm.config is installed
when the CICS WLM code is installed. Customizing the initialization file on page
33 discusses the purpose and placement of this file. Initialization file for Routing
Test sample code on page 64 shows the initialization file for the Routing Test
sample code.
The configuration file

The configuration file (wlm.cfg) is a flat file that contains the definitions of the
regions, machines, and resources that the CICS WLM utility uses to process work
requests. CICS WLM uses the definitions that are contained in this file, to build the
internal object model that represents the CICS environment to the workload
management utility.
On the AIX platform, a sample file /var/cicssm/repos/wlm.cfg.sample is installed

when the CICS WLM code is installed. Describing the environment to CICS WLM
on page 27 discusses the purpose and placement of this file. Configuration file for
Routing Test sample code on page 64 shows the configuration file for the Routing
Test sample code.
The configuration file parser and loader

CICS WLM can operate only with the CICS resources that you define to it in the
configuration file.
The configuration file is read by the parser and loaded into CICS WLM through
various cicswlm commands:
1. The cicswlm configure command must be run before any other cicswlm
command.
2. The cicswlm verify command ensures that no syntax errors are in the
configuration file.
3. The cicswlm load command loads a configuration file. Run this command only
on a verified file, and only on a machine on which a WAP has already been
started.
See Verifying and loading the configuration file on page 33 and Loading the
configuration file on page 42 for discussions about using these commands.
10
Chapter 3. Describing the environment to CICS WLM utility

CICS WLM serves an environment in which are multiple CICS regions. These CICS
regions can be grouped into specialized types of CICS systems that are designed
to serve different groups of applications. For example, you can have two instances
of a type system A, one instance of a type system B, and five instances of a type
system C. Each instance of a system type has the same CICS configuration. For
example, each has the same number of application servers, or the same programs
and transactions defined within them. The instances of a system type are clones of
one another.
CICS WLM creates an abstract representation of the regions and resources in your
environment, which is called an internal object model. The abstract representation is
defined in a configuration file. This representation is needed to enable CICS WLM
to put questions of the following nature:
v Which CICS systems have program XYZ defined on them?
v Which CICS system is able to process the transaction for this work request?
v Which CICS system has the lightest workload at this time?
By answering such questions, CICS WLM can determine the best routing for a work
request.
This section provides details about all the objects that can be defined in a CICS
WLM configuration file. Object names, default values, and short descriptions are
provided. When the CICS WLM-supplied commands for verifying and loading the
configuration file are implemented, the internal object model that represents the
environment is built. See Chapter 5, Customizing CICS WLM to your environment,
on page 27 for details about using these commands.
Object model specifications

The CICS WLM configuration file is a flat file that contains the object definitions that
you enter to represent your environment. The CICS WLM utility provides commands
to load the file. See Chapter 5, Customizing CICS WLM to your environment, on
page 27 for details about using these commands.
You must represent all CICS resources that are required for workload management
to CICS WLM. If work requests that are directed to an existing resource in your
environment do not require workload management, it is not necessary to define that
resource in your configuration file. Routing of work requests to that resource
continues in the same way, using the Communications Definitions CD), Program
Definitions (PD) and Transaction Definitions (TD), as it did before workload
management was introduced into the environment. When your processing needs
change over time, you can add or remove resources by modifying your
configuration file.
The following CICS resources can be represented to CICS WLM:
v CICS regions
v Connections between CICS systems
v Programs that are being routed between regions
v Transactions that are being routed between regions
v Machines on which CICS regions are running
11
Table 3 shows the objects that CICS WLM uses to represent these resources:
Table 3. Object models used by CICS WLM
Object
Description
Plex
The highest grouping of CICS resources
SystemModel
A generic type of CICS region
SystemClone
An individual CICS region
SystemImage
A representation of a SystemClone on a
Node
Node
An individual machine
Connection
A representation of communication links

between CICS systems
ResourceModel
A program or transaction that can be routed
Separation
A data-dependent control object
Partition
A subset of SystemClone objects within a

Separation object
The object model enables a single representation for an entity. This eliminates the
need to have multiple copies of an object. When a particular object (a program, for
example) is configured on more than one type of CICS system, a relationship is
established between the object and each of those CICS systems.
If a resource is required that has a difference of even one parameter from an
already-existing resource, another resource object must be created. The original
object continues to exist. Each of these resource objects has its own relationships.
It is possible that the two resource objects are configured on the same CICS
systems, but they represent different entities.
Objects in the CICS WLM object model can contain three properties:
v Attributes
v Relationships
v Contents
An attribute is a specific value, such as the response time that is associated with a
program object.
A relationship is an association between two object models. For example, a
SystemClone object has the relationship of installed_on with a Node object.
Relationships have a direction. For example, a SystemClone object is installed_on a
Node object, and not the other way round.
Note: This document describes the relationship only under the source objects
class. In the given example, the installed_on relationship is described under
the discussion on SystemClone objects; it is not repeated in the discussion
about Node objects. The SystemClone class owns the relationship, and
when defining objects in the configuration file, you define instances of a
relationship under the owning class.
Contents refers to other object types that are contained within this object type.
Some objects consist of a relationship to another object. Objects can also have
12
attributes. If the default value of an attribute is acceptable, you do not need to code
the value in your CICS WLM configuration file. Accepting the defaults can help
reduce the size of the file.
These three properties are discussed for each object model within the detailed
descriptions of the object.
Object model hierarchy

Figure 3 shows the hierarchy of the object model, along with each objects contents
and relationships.
Figure 3. CICS WLM object model
Plex objects
A Plex is the highest-level grouping of CICS systems and resources for
administrative purposes. It can consist of the whole CICS configuration or only the
CICS systems that are serving one application. It is whatever is meaningful to your
environment. A Plex is sometimes referred to as a CICSplex. You can partition the
environment into several independent Plexes or one all-encompassing Plex.
Connections do not cross Plex boundaries, and work is not routed from one Plex to
another.
Attributes for Plex objects
A Plex has multiple attributes that represent the values that are fed into the
workload-balancing algorithm. Plex attributes probably need to be changed
only by IBM customer service personnel. Table 4 on page 14 shows
attributes and defaults for a Plex object.
13
Table 4. Attributes and defaults for a Plex configuration

Attribute
Default
Description
load_limit
600
Maximum load that is used in WLM

algorithm
connection_scale
Parameter that is used in WLM algorithm
same_limit_1
Number of entries for short-term

performance
same_limit_2
10
Number of entries for long-term

performance
same_adjustment
0.1
Same system bias
same_scale_1
Importance of last systems short-term

performance
same_scale_2
Importance of last systems long-term

performance
known_adjustment
0.05
Bias toward previously-used system
known_scale_1
Importance of previously-used systems

short-term performance
known_scale_2

long-term performance
normalise_scale
Used to round scores
equal_delta
Margin for resolving equal scores
health_adjustment_1
Bias toward systems for health=1
health_adjustment_2
10
health_adjustment_3
100
health_timeout
120
Delay before restarting a failed system
score_limit
5,000
Maximum score that is allowable for a

system
retry_limit
Number of times to retry a system before

trying another system
reselection_limit
Number of systems to reselect before

giving up, when failure recovery is in
operation
wcm_resend_timeout
Timeout for messages from WCM to

WAP
wcm_retry_timeout
10
Timeout for reconnection attempts from

WCM to WAP
wcm_retry_limit_1
Number of attempts to connect to WAP

initially
wcm_retry_limit_2

following a communication failure
wcm_fail_timeout
600
Time in seconds to lock out a system

that has had a failure
autoinstall_load
Iincrease in response time because of

ECI autoinstall
Relationships for Plex objects

None. It is possible to have multiple Plexes; however, it is not possible to
route work between Plexes.
14
Contents for Plex objects

A Plex can contain the following types of objects:
v SystemModel
v
v
v
v
SystemClone
SystemImage
Node
ResourceModel
LocalProgramModel
RemoteProgramModel
LocalTransactionModel
RemoteTransactionModel
ApplicationModel
v Connection
v Separation
v Partition
SystemModel object
A SystemModel object represents a particular type of CICS region. For example,
you might have two SystemModel objects: one called AOR, which represents a
CICS Application Owning Region (AOR), and another, called COR, which
represents a CICS Client Owning Region (COR). The CICS systems that
correspond to a particular SystemModel entry are identical. Different SystemModel
entries have different CICS resources configured on them. So, a CICS system that
is of the type COR is different from one that is of the type AOR. For example,
CICS-to-CICS communication entries in the configuration file can differ for the AOR
SystemModel type and the COR SystemModel type. The communication entries for
the COR type have connections to all the AOR types; but it is possible that the AOR
SystemModel types have only one connection, which is to the COR type.
Attributes for SystemModel objects
SystemModel objects have no attribute values.
Relationships for SystemModel objects
SystemModel objects have a cloned_as relationship to SystemClone
objects.
Contents for SystemModel objects
SystemModel objects have no contents.
SystemClone objects
A SystemClone object represents a particular CICS system of one of the
SystemModel types. The SystemModel object represents the generic type of region;
a SystemClone object represents an individual CICS region.
Attributes for SystemClone objects
SystemClone objects have attribute values to describe the relative power of
the machine on which the CICS system is running, the maximum number of
application servers for the system, and the health of the CICS system.
Table 5 on page 16 shows attributes and defaults for a SystemClone object.
15
Table 5. Attributes and defaults for a SystemClone object

Attribute
Default
Description
factor
A measure of the systems capacity to do work

relative to the other systems in the WLM
environment.
maxServers
The maximum number of application servers that is

defined for the CICS system.
health
The state of the systems health:

v 1 = Excellent
v 3 = Very poor or offline
Relationships for SystemClone objects

SystemClone objects have an installed_on relationship to Node objects.
Contents for SystemClone objects
SystemClone objects can contain Connection objects.
SystemImage objects
A SystemImage object is used to represent the presence of a SystemClone entry
on a particular machine or Node object. Although the SystemClone object has an
installed_on relationship to a Node object, the SystemImage is required by the
object model. Without it, the representation of a CICS system to CICS WLM is not
complete. For each CICS system, the SystemClone and SystemImage objects are
both required.
SystemImage objects have no attributes, relationships or contents.
Node objects
A Node object represents an individual host or SystemImage object on which CICS
systems can possibly be installed. The Node name must correspond to the fully
qualified host name, including the domain name; for example,
testlab125.company_name.com.
Node objects have no attributes, relationships, or contents.
Connection objects
A Connection object is used to represent communication links between CICS
systems. For work to be routed from one CICS system to another, a pair of
Connection objects must be defined. Each half of the Connection pair is associated
with a SystemClone object, which is the CICS system from which the connection is
defined. The two half-connections must be related to each other so that CICS WLM
can detect that both halves of the relationship are present and correct. A
relationship is defined from one half of the connection to its other half. The reverse
relationship does not need to be coded, because CICS WLM detects this. For
routing to occur through a Connection object, both halves of the Connections must
be defined as being in service. It is possible to set the InService attribute for one
half of the Connection to zero. In that case, work is not routed to the region
because the CICS WLM utility does not see a healthy communication path to it.
16
The entries that are made for Connection objects in the CICS WLM configuration
file do not replace or affect the CICS Communications Definitions (CD). The CICS
WLM utility uses the Connection object entries to build the internal object model.
Attributes for Connection objects
Connection objects have attribute values to describe the cost of
communicating over the Connection object relative to the cost of using
other Connection objects in the configuration, and to indicate whether the
Connection object is in service or not. Table 6 shows the attributes and
defaults for a Connection object.
Table 6. Attributes and defaults for a Connection object
Attribute
Default
Description
load
0.1
The weighting factor that is applied to the object

that is using this Connection. Increasing this
number biases the WLM algorithm away from the
connected system.
inService
A switch to specify whether this Connection object

is currently enabled (1) or not (0). Note that both
Connections must be inService for routing to occur
between two systems.
Relationships for Connection objects

Connection objects have a my_other_half relationship to other Connection
objects.
Contents for Connection objects
Connection objects contain no objects.
ResourceModel objects
A ResourceModel object represents the CICS programs and transactions that can
be routed. Types of ResourceModel objects include:
v LocalProgramModel
v LocalTransactionModel
v RemoteProgramModel
v RemoteTransactionModel
v ApplicationModel
The same properties apply to the attributes, relationships, and contents for all the
types of ResourceModels. The following discussion first describes the
ResourceModel types; the discussion of the properties follows the descriptions of all
the types.
LocalProgramModel and LocalTransactionModel objects

A LocalProgramModel or a LocalTransactionModel object corresponds to the
Program Definition (PD) or Transaction Definition (TD) that is used for running a
CICS program or transaction resource. For a transaction, a LocalTransactionModel
object points to a locally running program.
A LocalProgramModel object contains an indicator to show whether the program
can be dynamically routed (the dynamic attribute). This indicator must be enabled
for workload management of that program to occur.
17
RemoteProgramModel and RemoteTransactionModel objects

A RemoteProgramModel or a RemoteTransactionModel object corresponds to the
remote definition of a CICS resource that is used within CICS. That is the definition
that is found in a COR for a resource that is in an AOR.
RemoteProgramModel and RemoteTransactionModel objects are for information
purposes and do not play an active part in making a routing decision.
ApplicationModel objects
An ApplicationModel object is a grouping of CICS resources that are used on the
AIX platform for the workload management of CICS EPI requests when the CICS
EPI client is assigned to a particular application.
The ApplicationModel refers to a SystemModel object. The user of an application
has access to all the LocalTransactionModel resources that are configured on a
SystemModel object.
See Specifications for the Plex object on page 29 to review a sample configuration
file that contains most of the objects that are discussed in this chapter.
Attributes for all the types of ResourceModel objects
ResourceModel objects both have attributes that indicate the processing
cost of running the requested type of work. Table 7 shows the attributes and
defaults for a ResourceModel object.
Table 7. Attributes and defaults for a ResourceModel object
Attribute
Default
Description
load
0.25
An estimate (in response time seconds) for the

duration of a request of this resource, on a system
with the attribute value of factor=1.0. Transaction
response times vary from instance to instance, so
this is only an estimated figure.
dynamic
no
Programs only- a switch (yes/no) to specify if this

program can be dynamically routed.
Relationships for all the types of ResourceModel objects

ResourceModel objects have a configured_on relationship to SystemClone
objects and a separated_by relationship to Separation objects. It is possible
to configure a ResourceModel object onto more than one SystemClone
objects. Table 8 shows the relationship associations for a ResourceModel
object.
Table 8. Relationship associations for a ResourceModel configuration
18
Relationship
Related Class
Description
configured_on
SystemClone (for
programs and
transactions)
The SystemClone objects that provide this

resource for a program or transaction.
configured_on
SystemModel (for an
ApplicationModel
only)
The SystemModel object that provides this

resource for an ApplicationModel.
Separated_by
Separation
The Separation object that is used to

determine the data-dependent routing rules
to apply to this resource for program and
transaction ResourceModels only.
Contents for all types of ResourceModel objects

ResourceModel objects have no objects.
Separation objects
A Separation object is used to control a particular mode of data-dependent routing.
Separation objects group together several Partition objects. Data-dependent routing
is defined as the making of a decision to route a piece of work to a particular CICS
system based on data that is associated with the item of work. This is usually done
by looking at some portion of the CICS COMAREA.
Attributes for Separation objects
Separation objects have no attributes.
Relationships for Separation objects
Separation objects have no relationships.
Contents of Separation objects
Separation objects contain Partition objects.
Partition objects
A Partition object is used within a Separation object to specify a subset of
SystemClone objects that is to be used as potential destinations for data-dependent
routing.
Attributes for Partition objects
Partition objects have one attribute, which is user-supplied data. This data
is used within the data-dependent routing user exit.
Relationships for Partition objects
Partition objects have a separated_to relationship to SystemClone objects.
Contents of Partition objects
Partition objects have no contents.
19
20
Chapter 4. Preparing for CICS WLM

This chapter suggests a strategy for analyzing your environment for CICS Workload
Management (WLM) utility. This analysis is designed to provide the information that
you require to do the following tasks:
v Customize the CICS WLM initialization file, cicssm.config
v Customize the CICS WLM configuration file, wlm.cfg
v Identify the user exits that are to be established
v Identify the CICS definitions that are to be modified
v Make a high-level review of the environment to ensure that it is prepared for
implementation of the CICS WLM utility
These processes are discussed in Chapter 5, Customizing CICS WLM to your
environment, on page 27.
Gathering information for a CICS WLM environment

A workload management environment is one in which two or more regions can
process the requested work item. Without a choice of routing locations, no benefit is
gained by introducing workload management functions into a configuration. On the
AIX platform, the requested work item can be a Dynamic Transaction Routing
(DTR) request, a Distributed Program Link (DPL) requestor or a request from the
CICS Universal Client or CICS Transaction Gateway. The CICS WLM utility does its
routing actions by using standard CICS WLM user exits. It also uses exit programs
that CICS WLM provides. The CICS WLM user exit programs must be defined to
CICS to enable these exits. This is described in more detail in Modifying CICS
definitions on page 34.
Your information gathering includes the following activities:
v Identifying the types of work requests that are made in the environment (DPL,
DTR, ECI, and EPI on AIX. )
v Anticipating the expected number of work requests for each identified type of
work requests
v Determining which machines are to handle the identified types of work requests
v Determining which applications handle the identified types of work requests
v Identifying the regions on which the required applications reside
v Determining the interaction required by clients; that is, whether the clients only
issue work requests, or whether they do the request routing to Application
Owning Regions (AORs).
When this information has been gathered from the environment that is to be defined
for workload management, the following types of decisions can be made:
v Which applications and regions are to be defined as a group that is dedicated to
processing specific types of work requests? (These groupings are your
SystemModel objects and are discussed in Chapter 3, Describing the
environment to CICS WLM utility, on page 11.)
v How many replicas are required for each grouping (SystemModel) to meet the
anticipated number of work requests? (The replicas of SystemModels are your
SystemClone objects and are discussed in Chapter 3, Describing the
environment to CICS WLM utility, on page 11.)
21
v How each machine is to participate in the environment; that is, will it be issuing
requests, routing requests, or processing requests?
v Which components of CICS WLM, if any, need to be installed on the machines to
enable their participation in the environment? (The components of CICS WLM
are discussed in Chapter 2, Components of WLM, on page 5.)
Examples of CICS environments shows examples of how CICS WLM can be
implemented in frequently occurring sample environments.
Examples of CICS environments

This section describes some typical CICS configurations and looks at planning
approaches for implementing CICS WLM. You can use these examples to help you
determine the location of CICS WLM components in your own environment.
Example environment using a Windows Client

Figure 4 shows an example environment that is using a Windows Client.
Figure 4. Example environment using a Windows Client
The environment
The clients are CICS for Windows Clients that are issuing a series of CICS ECI
calls to several CICS for AIX servers. The application code runs on all the servers.
All the data that is required for the CICS applications is available within the CICS
region. Therefore, a client can route an ECI request to any of the CICS for AIX
servers and have access to both the application and the required data. In this case,
the applications are running in a CICS for AIX server; however, the same
configuration can be used with other CICS on Open Systems servers.
22
The WLM planning approach

Because CICS WLM is not supported on CICS for Windows, the CICS for Windows
Clients must connect to an intermediate region. This intermediate region is referred
to as a Client Owning Region (COR), and it can be located on an AIX machine.
From the COR, the inbound CICS ECI calls from the CICS for Windows Clients are
managed as distributed program links to the CICS for AIX server that contain the
applications. For this to happen, a WCM and the appropriate CICS WLM exit must
be installed on the same machine as the COR is. Without this configuration, the
distributed program links that are being issued in the COR cannot be workload
managed. To ensure greater availability, the WAP and the HMON are located on a
machine that has low use and is rarely rebooted. The locating of them on a
machine that is not running a CICS for AIX server ensures that the maximum
processing power is available to the CICS for AIX servers.
Example environment using a single machine

Figure 5 shows an example environment that is using a single machine.
Figure 5. Example environment using a single machine
The environment
The clients are cicslterm processes that issue transaction requests or ECI/EPI
requests via CICS Universal Clients and the CICS Transaction Gateway to several
CICS for AIX servers. The application code runs on the servers. All the CICS
servers have a connection to a database system, which is located on another
machine. All the applications are available on all the CICS servers. Therefore, a
client can issue a transaction request that can be run on any of the CICS servers
and have access to both the application and required data.
23
The WLM planning approach

The cicslterm processes or the CICS Transaction Gateway connect to an
intermediate region, called a Client Owning Region (COR). From the COR, requests
to run transactions are routed to a CICS server. The CICS WLM utility can balance
the generated work over the available CICS servers by managing the transaction
routing requests. For this to happen, a WCM and the appropriate CICS WLM user
exit must be installed on the same machine as the COR is. To ensure greater
availability, the WAP and the HMON are located on a machine that has low use and
is rarely rebooted. The locating of them on a machine that is not running a CICS
server ensures that the maximum processing power is available to the CICS
servers.
Using the concept of following a work request

The CICS implementation varies in each of these sample configurations, but all
include the concept of a following a work request. Each work request is issued,
routed, and processed. A request that is issued on a client can be routed from a
server, as in the example that shows the COR. Configurations that are similar to
these have a single routing point; other configurations can have many routing
points. The number of routing points depends on the type and size of the CICS
configuration.
Each routing point requires a WCM and the appropriate CICS exit, which is
supplied with CICS WLM. One WAP and one HMON exist in a configuration. The
location of the WAP and the HMON is at some fixed and accessible location. The
WCMs must be able to communicate with the WAP over a TCP/IP connection.
Planning the location of CICS WLM components

As part of the implementation of CICS WLM, you must decide which machines in
your environment are going to run which WLM components. This section helps you
decide what that allocation should be.
The components of CICS WLM that need to be located are:
v The Workload Management Application cache (WAP)
v The Workload Management Cache Manager (WCM)
v
v
v
v
The Workload Management Client (WCL)

The Workload Management Health Monitor (HMON)
The Routing Monitor (RMON)
WLM-supplied user exits
The WAP and the HMON components must be located on the same machine. One
instance of each of these components exists. An HMON is automatically associated
with a WAP. Its use is optional. You specify only the location of the WAP; this is
done in the WAP configuration file, cicssm.config. The other components are
placed onto a machine by using the cicswlm start command to start a component.
How to specify the location of the WAP is discussed in Performing the initial
configuration on page 34. Use of the cicswlm start command is discussed in
Chapter 6, Starting CICS WLM for the first time, on page 39.
The WCM and the WCL must also be located on the same machine. One or more
instances of these components can exist, depending on the configuration in which
WLM is being implemented. Also, more than one type of workload management can
24
be occurring within a CICS configuration. The cicswlm start command places the
WCM onto a machine. The installation of the WCL is automatic.
The RMON is placed with each WCM. Running the cicswlm start rmon command
on the machine places the RMON onto that machine.
Before deciding where to place components, you need to define your system
architecture based on the applications, the data that is accessed, and the types of
CICS clients that are being used. You can be fitting workload management to an
existing CICS configuration, or you can be designing a new system into which CICS
WLM is to be implemented. It is possible to implement CICS WLM without changing
existing applications.
CICS WLM-supplied user exits are installed on any machine that acts as a routing
point within the CICS WLM configuration. When you have decided on the location
and type of routing points (CORs) in your configuration, you can easily identify the
machines on which the CICS WLM components need to be installed.
Note: CICS WLM components need to be installed only on a machine in the
configuration that is either a routing point or the WAP location. If you locate
the WAP and the HMON on either the same machine as is one of the routing
points, or on their own machine, you do not need to install any CICS WLM
component on the AOR machines to which work is to be routed.
Environmental considerations required for WLM

To run CICS WLM, ensure that the following considerations are met when you
combine applications into a single CICS system type:
Your environment must meet basic requirements.
v If you are using a Client Owning Region (COR), it must be an AIX
machine that is running CICS for AIX.
v If you are using a database, your database connections must be
established.
v IP Listener Definitions to TCP communications ports must be established.
v Ensure that an AIX user of cicssm is created.
v Ensure that an administrative group of cicssm exists on each region
where the code is to be installed.
v Ensure that the cicssm user ID is a member of the cicssm group and
the cics group.
v If the CICS WLM executable files are located on a shared file system,
ensure that machines that are accessing this file system have the same
userid and group numbers for the cicssm user and group.
v Ensure that you have installed CICS WLM code in accordance with the
instructions that are given in the TXSeries for Multiplatforms Installation
Guide.
v Ensure that you have reviewed the directory structure that was created
as a result of the installation of the CICS WLM code. Appendix D,
Directory structure created by installing CICS WLM, on page 113
displays the CICS WLM directory structure.
Your applications must be able to access the required data.
If multiple regions are to run an application, each region requires access to
the data that is used by that application. If the data is held in a serial
25
database-manager system, consider having the regions access the

database remotely by having an access path to the data for each CICS
system. Be aware that accessing data in this way has a negative effect on
performance. Use of a parallel database can have benefits.
All facilities required by your application must be defined.
If multiple regions are to run an application, you must include all the
facilities that the application requires. For example, you possibly need to
define more intersystem communication links because the applications that
are being placed within a region each access different remote systems.
Your applications must be compatible with each other.
Different applications can try to use the same temporary storage or
transient data queue names. If the names cannot be changed, the
conflicting applications must remain separate.
Your applications must not contain any affinities with other applications.
Applications contain affinities when they must be run in the same CICS
region because they require access to data or state information that exists
on that region. Remove affinities before introducing WLM into the
environment. If you cannot remove the affinities, ensure that those
applications are not configured for workload management. The
unconfigured applications continue performing in the same way as they did
before WLM was introduced into the environment.
Previous installations of the CICS SM product must be completely removed.
If the CICS SM product has been implemented in the environment, take
these steps:
1. Before you install CICS WLM, save any customization of workload
management components of CICS SM, such as routing exits and
associated makefiles.
2. Uninstall CICS SM, if it is installed on any of the machines on which
you intend to run CICS WLM.
26

This chapter describes the procedures for configuring, verifying and loading your
implementation of the CICS Workload Management (WLM) utility.
Customization of the CICS WLM initialization file, cicssm.config and the CICS WLM
configuration file, wlm.cfg, and how to establish user exits are also discussed.
Instructions for installing the CICS WLM code are contained in the TXSeries for
Multiplatforms Installation Guide. The sample initialization and configuration files
that are discussed in this chapter are installed when the CICS WLM code is
installed.
Suggested sequence of events

The following list provides a suggested sequence of events for verifying,
configuring, and loading CICS WLM. Note that the directory structure indicated in
the path names that are displayed in the following steps apply to the AIX . If you
have completed the code installation and planning analysis that is described in this
document, you are ready to proceed with the following steps:
1. Customize the CICS WLM configuration file /var/cicssm/repos/wlm.cfg.sample
to describe your CICS environment as a CICS WLM object model. See Loading
the configuration file on page 42 for information about loading the file after it is
customized.
2. Customize the CICS WLM initialization file /var/cicssm/repos/cicssm.config.
See Performing the initial configuration on page 34 for information about
locating the CICS WLM global application cache (WAP) after you have
customized the initialization file.
3. Ensure that the necessary modification to CICS definition files have been made.
4. Establish the exit types for the resources that are used for request routing in
your environment. On AIX , the exit types can be Distributed Program Linking
(DPL) and Dynamic Transaction Routing (DTR). See Setting up CICS WLM
user exits on page 36 and Setting up the remote resource definitions on page
35 for more information.
Describing the environment to CICS WLM

To be able to define your configuration, you must understand the underlying object
model on which CICS WLM is based. See Chapter 3, Describing the environment
to CICS WLM utility, on page 11 for a detailed discussion about this topic. A
sample object model description is contained in the file /var/cicssm/repos/
wlm.cfg.sample. This file is installed when the CICS WLM code is installed on the
AIX platform.
You can change the name for this file and supply it as an input parameter to the
command that processes it. However, the file must reside in the /var/cicssm/repos
directory. This file must be present only on the machine that contains the WAP.
The following attributes of your configuration file can be customized:
v Various distribution algorithm attributes. For example, you can assign different
weightings to short-term and long-term responses.
v A value, relative to other machines in the configuration, that represents the
processing power of each machine on which a CICS server runs.
27
v A value that identifies how many application servers are available in a CICS
system.
v The relative cost of communicating with a remote system for each CICS
Communications Definition (CD) within CICS WLM. For example, if access to one
server is over a fast communication link, while access to another server is over a
slow communications link, and other considerations are equal, the server that is
using the fast communications link is chosen.
v A value for the status of a CD. For example, it can determine whether a link is
active.
v The processing load weight that is associated with running a program or a
transaction. The load weight is determined by estimating the response time for a
work request. This estimate corresponds to the measure of the amount of
processing that the server must expend to complete the request.
It is possible to create multiple files and have CICS WLM run the most-appropriate
one for the current condition. For example, you can have one file that describes the
full configuration, and other files that omit one or more CICS systems. You can
exclude a CICS system temporarily while it is having maintenance.
CICS WLM can operate only with the CICS resources that you define to it in the
configuration file. The configuration file must define the existence and relationships
between programs and regions that the CICS WLM will manage. Customize this file
to reflect the CICS regions and any CICS Communications Definitions (CD) in your
environment as instances of SystemModel, SystemClone, Connection, and Node
objects.
The series of Resource Definitions (RD) that you define describe the resources that
can be routed. This is done by using LocalProgramModel, RemoteProgramModel,
LocalTransactionModel, and RemoteTransactionModel objects. For each of these
resource types, you specify an expected load, or response time, for the program or
transaction, and for the SystemModel object on which it is configured.
In an environment that has a Client Owning Region (COR) and one or more
Application Owning Regions (AORs), you have a CICS remote program or
Transaction Definition (TD) in the COR. You must specify a remote system in the
RD. The remote system that is named in the RD forms the default system to which
requests for running that resource are directed when CICS WLM cannot make a
routing decision. In CICS WLM, such a resource is defined by a
RemoteProgramModel or RemoteTransactionModel object. You can successfully
implement workload management without adding these remote resource entries to
the CICS WLM configuration file; however, you can do so for completeness.
Also, a series of definitions can exist that correspond to the CICS WLM algorithm.
Allow these definitions to default until you have performance statistics from your
environment. The example in Sample configuration file (wlm.cfg) on page 29
shows a configuration file in which the algorithm attributes are allowed to default.
The Routing Test example file in Configuration file for Routing Test sample code
on page 64 shows a configuration file in which the algorithm attributes are specified
for the Plex. This example shows the Plex attributes in Section 9.
Specifications for the Plex object on page 29 describes the CICS system that is
being defined as the Plex object cpx1 for CICS WLM. Sample configuration file
(wlm.cfg) on page 29 shows the configuration file that describes this object. See
28
Verifying and loading the configuration file on page 33 for a discussion about
verifying this file, and see Loading the configuration file on page 42 for information
about loading this file.
Specifications for the Plex object

This section describes how to specify a CICS configuration. In Sample
configuration file (wlm.cfg), the environment consists of a COR that routes requests
for three application programs to two attached AORs. The details are as follows:
v A CICS Client Owning Region (COR), known as CICSCOR
v Two CICS Application Owning Regions (AORs), known as CICSAOR1 and
CICSAOR2
v CICS Connections between the COR and each of the AORs
v Connections from each of the AORs to the COR
v CICS regions that are located over three machines: machine1.acme.com,
machine2.acme.com, and machine3.acme.com
v Three CICS application programs: APPLN1, APPLN2 and APPLN3. These
applications are routed from the COR to one of the AORs.
In some cases, two object declarations are required in the following CICS WLM
configuration file. The first declaration is a predeclaration; the second one is the use
of the object. This double-entry declaration is required because a single-pass parser
is used to scan the file.
The syntax that is used to declare instances of an object is
objectname.instancename. In the following example, CICSCOR is the instance of a
SystemClone object type:
SystemClones.CICSCOR
Instance names that contain nonalphanumeric characters must be enclosed within

quotation marks ( ). Object definitions must be enclosed within braces ( {} ).
The example that is shown in Sample configuration file (wlm.cfg) is partitioned by
numbered sections. These numbered sections are intended to make it easy to
reference portions of the file throughout the text. The actual file need contain only
the monospaced example text.
Sample configuration file (wlm.cfg)

Section 1: The Plex definition starts here.
The Plex is the highest defined administration level. It is defined with the
name of the cpx1. The name cpx1 is the default CICSplex name. If you use
a different Plex name, two variables must be included in the environment of
the CICS regions that are using DPL and DTR user exits. See Before you
start the CICS WLM on page 39 for information about these variables.
Plexes.cpx1
{
Section 2: The SystemModel objects are predeclared.

A SystemModel declaration is required for each type of region that exists in
the configuration. This configuration has two types: a Client Owning Region
(COR) and an Application Owning Region (AOR). This entry is a type
definition; it has no detail associated with it.
SystemModels.COR;
SystemModels.AOR;
29
Section 3: The SystemClone objects are predeclared.

A SystemClone object is defined for each region.
SystemClones.CICSCOR;
SystemClones.CICSAOR1;
Section 4: The Connection objects from the COR to each of the AORs are
predeclared.
The name that is used for the Connection object must match the one that is
used in the CICS Communications Definition (CD) to define the actual
connection to the AOR.
SystemClones.CICSCOR/Connections.AOR1;
Section 5: The Connection objects from each of the AORs back to COR are
predeclared.
connection to the COR.
SystemClones.CICSAOR1/Connections.COR1;
Section 6: The machine names are predeclared as Node objects.

The name that is specified is the one that is obtained by using the fully
qualified host name, including the domain name, for example,
Nodes."machine1.acme.com";
Section 7: A SystemImage object is predeclared for each of the CICS regions

(SystemClones) in the configuration.
A SystemImage represents an instance of a CICS region on a particular
machine. It is important that the quotation marks () are used correctly.
Nodes."machine1.acme.com/SystemImages.CICSCOR";
Nodes."machine2.acme.com/SystemImages.CICSAOR1";
Section 8: The routed application programs are predeclared as

LocalProgramModels.
The ResourceModel definitions represent the programs that are to be called
in the AORs. The entry of these definitions completes the predefinition
requirements for the WLM.
LocalProgramModels.APPLN1;
Section 9: The Relationship of the COR SystemModel to the SystemClone is

defined.
The object definitions for this Plex are started by relating the COR
SystemModel object and the SystemClone entry of CICSCOR.
SystemModels.COR
{
cloned_as -> SystemClones.CICSCOR;
}
Section 10: The Relationships of the AOR SystemModel object are defined.
The AOR SystemModel object is related to the two SystemClone objects
that are of the AOR type: CICSAOR1 and CICSAOR2. Note that two
30
instances of the AOR SystemModel objects exist. Compare this with the
single instance of the COR SystemModel object.
SystemModels.AOR
{
cloned_as ->
{
SystemClones.CICSAOR1,
SystemClones.CICSAOR2
};
}
Section 11: The attributes of the CICSCOR SystemClone object are specified.
The relationship is also declared to specify the machine on which this
SystemClone object is located.
{
factor=1.0;
maxServers=10;
health=1;
installed_on -> Nodes."machine1.acme.com";
}
Section 12: The attributes of the CICSAOR1 SystemClone object are

specified.
{
factor=1.0;
maxServers=5;
health=3;
}

specified.
{
factor=1.0;
maxServers=5;
health=1;
}
Section 14: The attributes of the Connection between CICSCOR and

CICSAOR1, known as AOR1, are defined.
With the declaration for my_other_half, only one half of the Connection is
defined. The CICS WLM itself determines that a return Connection exists
from AOR1 to COR and from AOR2 to COR. The attributes of the
Connection between CICSCOR and CICSAOR1, known as AOR1, are
defined. The relationship is also declared to indicate that the two
Connection entries (AOR1 and COR) are a pair. (These entries start the
Connection declarations.)
SystemClones.CICSCOR/Connections.AOR1
{
load=0.1;
inService=1;
my_other_half -> SystemClones.CICSAOR1/Connections.COR1;
}
31

CICSAOR2, known as AOR2, are defined.
The relationship is also declared to indicate that the two Connection entries
(AOR2 and COR) are a pair. Note that it is not necessary to define the
attributes and relationship for the other side of the Connection; that is, the
SystemClones.CICSAOR2/Connections.COR. CICS WLM builds this
automatically. (You can define it for completeness, if you want.)
{
load=0.1;
inService=1;
}
Section 16: Each of the Node objects is specified.

There are no characteristics to specify; therefore, the entries are minimal.
Nodes."machine1.acme.com"
{
}
{
}
{
}
Section 17: The SystemImage objects are assigned to the Nodes where they
are to run.
Nodes."machine1.acme.com/SystemImages.CICSCOR"
{
}
Nodes."machine2.acme.com/SystemImages.CICSAOR1"
{
}
{
}
Section 18: Plex attributes are located here.

All attributes are allowed to default for this example file. Section 9 shows
Plex attribute definitions in the example system.
Section 19: The ResourceModel objects are predeclared.
The attributes of each of the routed applications are defined. Also, it is
necessary to specify the SystemClone objects on which these applications
programs are to be found. The possible values for the dynamic attribute
are yes and no. These values must be enclosed within quotation marks.
A value of yes indicates that the resource is eligible for workload
management. A value of no indicates that the resource is not eligible for
workload management.
LocalProgramModels.APPLN1
{
load=0.7;
dynamic="yes";
configured_on -> SystemModels.AOR;
}
{
load=0.5;
dynamic="yes";
}
32
{
load=0.9;
dynamic="yes";
}
Section 20: The Plex definition is completed with the closing brace ( } ).
End the definition of Plex cpx1.
}
Verifying and loading the configuration file

Before you can start CICS WLM, you must load the customized, verified file that
describes the makeup of the CICS configuration to CICS WLM. Customization of
this file was discussed in Describing the environment to CICS WLM on page 27.
This file needs to be present only on the machine containing the WAP.
The configuration file is read by the parser and loaded into CICS WLM through
various cicswlm commands. The cicswlm verify command ensures that there are
no errors in the configuration file. This command must be run on the wlm.cfg file
before the file is loaded. This command is discussed in Verifying the configuration
file on page 41. The cicswlm load command loads a configuration file; it is
discussed in Loading the configuration file on page 42.
Note: The cicswlm configure command must be run before any other cicswlm
command. The cicswlm configure command is discussed in Performing
the initial configuration on page 34.
Customizing the initialization file

The file /var/cicssm/repos/cicssm.config must be present on all machines on
which CICS WLM components are run. The file must be identical on all machines in
which CICS WLM is installed. You can ensure that the file is identical by copying
the file or by using a shared file system.
The shipped file /var/cicssm/repos/cicssm.config is a sample and must be
updated to reflect your environment.
Note: This sample file is also stored in /usr/lpp/cicssm/repos, if you need to
return to it. (The directory structure and path names that CICS WLM uses is
the same on the AIX platform.)
The purpose of the cicssm.config file is to specify the location of the WLM
Application (WAP). You must have one and only one entry defining the location of
the WAP. For example:
wap <wap_name> <wap_host> <wap_port>
where:
v wap_name is an identifier you give to the WAP
v wap_host is the name of the host where the WAP is to run
v wap_port is the TCP/IP port used for communicating to the WAP. This port can
be any number that is not currently in use.
33
Check your /etc/services file to find an available port. You can then add the
allocated port number to the /etc/services file to ensure that others do not use it
by mistake. An example entry follows:
wap
wap1
machinex.company_name.com 9010
See Initialization file for Routing Test sample code on page 64 to review the file
cicssm.config that is used for the example WLM configuration.
Performing the initial configuration

The next steps describe the location of the WAP. The file that is used to specify the
location of the WAP to CICS WLM is named as follows:
/var/cicssm/repos/cicssm.config
The file /var/cicssm/repos/cicssm.config must be present on all machines on

which CICS WLM components are run. The file must be identical on all machines in
which CICS WLM is installed. You can ensure that the file is identical by copying
the file or by using a shared file system.
To perform the initial configuration of CICS WLM, run the cicswlm configure
command after you have edited the file /var/cicssm/repos/cicssm.config.
The process is as follows:
1. Authenticate as the user cicssm on the machine that is specified as the
location of the WAP.
2. Issue the command:
cicswlm configure wlm
CICS WLM processes the contents of the file /var/cicssm/repos/cicssm.config and

produces several files in the /var/cicssm/repos directory. The same path names and
directory structure is used on the AIX platform. These files are used subsequently
by CICS WLM to determine the location of the WAP.
Run this command on each machine in which CICS WLM is installed. If the
/var/cicssm/repos directory is allocated on a shared file system that is available to
all the machines that are involved in workload management, run this command only
on the machine in which the WAP resides. The files that are created from the
cicswlm configure command are available implicitly to all the machines that
require access to them.
command.
Modifying CICS definitions

CICS WLM must be defined for an environment in which CICS is running, and, if
databases are to be used, the standard database connections are in place. For
CICS WLM to be added to your environment, the following basic conditions are
assumed:
v Your CICS regions are set up.
v Your database is set up, and database access is established for your regions.
v Your application programs are prepared for use.
34
See the TXSeries for Multiplatforms Administration Guide for information about how
to perform these steps. See CICS setup on page 48 to review the discussion on
the CICS system setup for the Routing Test example code.
In addition, for CICS WLM to function, the following facilities must be added:
v IP Listener Definitions to TCP communications ports are needed.
v X terminal is required for use of the Routing Monitor (RMON). On the AIX
platform, AIX terminal window capability can be used for the RMON.
v
A Remote Procedure Call-based (RPC-based) CICS EPI client is required for use
of the Health Monitor (HMON).
v CICS definition modifications to the COR server and the AOR servers are
required.
v User exits (supplied by CICS WLM) must be established. See Setting up CICS
WLM user exits on page 36 for information about this topic.
The specific CICS definitions that require modification depend on your
implementation of CICS WLM. The examples that are used in this document show
the following CICS definition modifications for the COR and the AORs:
v Listener Definitions (LD)
Communications Definitions (CD)
Transaction Definitions (TD)
Program Definitions (PD)
LocalSysId
WLM-provided user exits
User Exits (supplied by CICS WLM) must be set up on client machines or on
your COR.
v Needed modifications must be made to the following CICS definitions for the
COR and the Application Owning Regions (AORs):
Listener Definitions (LD)
Communications Definitions (CD)
Transaction Definitions (TD)
Program Definitions (PD)
LocalSysId
WLM-provided User Exits
v
v
v
v
v
v
See Configuring CICSA (the COR) on page 50 and Configuring CICSB and
CICSC (the AORs) on page 51 for examples of these definition declarations.
Setting up the remote resource definitions

When a configuration uses a COR CICS routing system to direct requests for a
program to one of multiple AORs, two types of CICS definitions must exist for that
program. One definition must exist in the COR that defines a remote resource, and
a second definition must exist in the AOR that defines a local Resource Definition
for the program that actually runs in the AOR.
The remote Resource Definition in the COR must have no value for the program
path name. Also, a valid entry must be in the remote system field, which will be
used as a default if CICS WLM cannot make a routing decision. If a value for the
remote system is not supplied, CICS does not route the call.
35
The local Resource Definition in the AOR must have a valid path name that points
to the executable file for the program. This must be the same executable file on all
regions that are defined as SystemClones to WLM. The remote system field must
also be left blank.
See Configuring CICSB and CICSC (the AORs) on page 51 for examples of
implementations of these definitions.
Setting up CICS WLM user exits

CICS user exits need to be enabled for a CICS system to take part in a workload
management configuration. The exit type depends on whether the resource that is
being managed is a distributed programing link (DPL), a dynamic transaction
routing (DTR), an External Call Interface (ECI), or an External Presentation
Interface (EPI) work request. In addition, you need to ensure that the necessary
Resource Definitions exist for any programs or transactions that are being workload
managed. The topics that you must consider to enable each workload management
for each type of work request are described in the following sections: Distributed
Program Link workload management and Dynamic Transaction Routing workload
management on page 37.
Distributed Program Link workload management

A CICS system that is set up to route Distributed Program Link (DPL) requests
must have two CICS WLM resources configured on it. The programs BHGDPL and
BHGDPLSP contain the WLM-supplied user exit code for routing DPL work
requests.
CICS Program Definitions must be created for two CICS WLM programs, BHGDPL
and BHGDPLSP. The BHGDPL program must be associated with exit 50 and
BHGDPLSP program must be associated with exit 51. Use the cicsadd command
to make this association. See Configuring CICSA (the COR) on page 50 for
examples of this command. These resources must be configured on the CICS
system before the CICS system is cold started. You can use the cicscp command
to perform the cold start. (Alternatively, on the AIX platform, you can use the smit
command to perform the cold start.) The respective path names for the programs
are as follows:
v AIX
/usr/lpp/cicssm/bin/bhgdpl
/usr/lpp/cicssm/bin/bhgdplsp
v
When BHGDPL and BHGDPLSP have been configured and are in effect, CICS
WLM is called each time that an EXEC CICS LINK call is made. The subject of an
EXEC CICS LINK call must be defined to CICS for that call to succeed. If the call is
to be handled by CICS WLM, it must also be defined to CICS WLM through the
configuration file.
Note: A remote program is not a valid target for a DPL routing request. CICS WLM
does not permit chained DPL requests. When a DPL request has been
routed to a particular CICS region, all other requests within that same unit of
work are routed to the same location.
See Configuring CICSA (the COR) on page 50 for a configuration for the Routing
Test example code.
36
Note: It is possible that environment variables need to be set for your DPL work
requests to match customized names in your definition for your CICS WLM
environment. See Before you start the CICS WLM on page 39 for
information about setting these environment variables.
Dynamic Transaction Routing workload management

A CICS system that is set up to perform Dynamic Transaction Routing (DTR) must
have one CICS WLM resource configured on it. The BHGDTR program contains the
WLM-supplied user exit code for routing DTR work requests.
A CICS Program Definition must be created for BHGDTR. The BHGDTR program
must be associated with exit 25. Use the cicsadd command to make this
association. See Configuring CICSA (the COR) on page 50 for examples of this
command. The program must be configured on the CICS system before the CICS
system is cold started. You can use the cicscp command to perform the cold start.
(Alternatively, on the AIX platform, you can use the smit command to perform the
cold start.) The path name for the program is as follows:
v AIX
/usr/lpp/cicssm/bin/bhgdtr
v
Note: Entries must be made in the Transaction Definitions (TD) file to specify the
values for the RemoteName and ProgName attributes when DTR work
requests are included for routing the CICS WLM utility.
See Configuring CICSA (the COR) on page 50 for a configuration for the Routing
Test example code.
Note: It is possible that environment variables need to be set for your DTR work
requests to match customized names in your definition for your CICS WLM
environment. See Before you start the CICS WLM on page 39 for
information on setting these environment variables.
Setting environment variables for EPI routing management

To enable EPI/ECI routing on CICS for AIX , the CICS WLM-supplied user exit must
be installed, and the BHG_WCL_APPLICATION environment variable must be set
to an appropriate value in the environment file of the respective COR.
By selectively setting the BHG_WCL_APPLICATION environment variable, you can
enable WLM participation for some CORs, while disabling WLM participation for
other CORs.
The BHG_WCL_APPLICATION environment variable is set in the environment of
any COR that is to participate in workload management. The setting of the variable
must contain the name of an ApplicationModel that is defined in a verified and
loaded configuration file. For example, if the ApplicationModel is named payroll, you
need to issue the following statement in the environment file of the COR:
export BHG_WCL_APPLICATION="payroll"
By setting this environment variable, you enable the COR to access the resources
that are associated with the ApplicationModel named payroll.
37
Note: When CICS WLM is used in an environment in which cicslterm is invoked,

CICS WLM overrides any user selection from the menu of CICS systems
that is presented by cicslterm. CICS WLM selects the CICS system that is to
be used for communication with a cicslterm invocation. If the
BHG_WCL_APPLICATION environment variable is set in an environment in
which a cicslterm is invoked, CICS WLM determines the selection of the
CICS system that is to be used for communication with a cicslterm
invocation.
Defining an ApplicationModel
An ApplicationModel is defined by using a predeclaration that is followed by a full
declaration. The predeclaration is placed into the configuration file with the other
ResourceModel predeclarations. The syntax for the predeclaration is shown in the
following example:
ApplicationsModels.<application_model_name>;
where <application_model_name> is the arbitrary name that you assign to your

ApplicationModel. The name must consist of up to eight alphanumeric characters.
For example, payroll, payroll2, and group1 are all valid names for your
ApplicationModel.
The following display shows the predeclaration for the payroll example:
ApplicationsModels.<payroll>;
The following example shows the full definition of an ApplicationModel:

ApplicationModels.<application_model_name>
{
load=<load_value>;
configured_on->SystemModels.<system_model_name>;
}
where <load_value> is the response time (load) that is associated with the
application, and <system_model_name> is the name of the SystemModel object on
which the application is defined. Implicitly, all transactions that are defined on the
SystemModel object are available to the associated ApplicationModel object.
In this example,
38
Chapter 6. Starting CICS WLM for the first time

This section itemizes miscellaneous details that you must complete before you start
the CICS Workload Management (WLM) utility for the first time in your environment.
It also details the correct sequence for starting CICS WLM for the first time.
Before you start the CICS WLM

CICS WLM allocates several shared memory segments and semaphores for use
with components of CICS WLM. Successful routing requires the correct ownership
of these resources. To ensure that all the CICS WLM resources are owned by the
userid of cicssm and the group of cicssm, the CICS WLM components must
always be started by the cicssm userid.
Before you start CICS WLM for the first time, ensure that you have completed the
following details:
1. Ensure that an AIX user of cicssm is created.
2. Ensure that an administrative group of cicssm exists on each region in which
the code is installed.
3. Ensure that the cicssm userid is a member of the cicssm group and the cics
group.
4. If the CICS WLM executable files are on a shared file system, ensure that
machines that are accessing this file system have the same userid and group
numbers for the cicssm user and group.
5. Ensure that the profile for cicssm is updated and includes the directory
install_dir/cicssm/bin in the PATH statement, where install_dir is /usr/lpp on AIX .
(We assume that the directory install_dir/cics/bin/ is already in your PATH
statement.)
6. Ensure that your locale is correct by updating the profile for cicssm. For
example, to use English, ensure that the locale is set to en_US.
7. Specify the following two variables in the profile for cicssm:
BHG_ROOT=install_dir/cicssm
BHG_VAR=/var/cicssm
where install_dir is /usr/lpp on AIX .

8. Ensure that the CICS WLM files are owned by the userid cicssm and the group
cicssm:
cd install_dir/cicssm chown -R cicssm.cicssm *

Ensure that any necessary CICS customization and validation are completed as
described in Chapter 4, Preparing for CICS WLM, on page 21, for example:
v If you use a different Plex name from the default name cpx1, include the
following two variables in the environment of the CICS regions that run
Distributed Program Link (DPL), Dynamic Transaction Routing (DTR), and in the
cicssm profile file:
BHG_WCL_GROUP_NAME=xxx
BHG_WCL_xxx_CICSPLEX_NAME=cicsplexname
In this example, cicsplexname is the name that you assigned to your Plex object
in the object model configuration file, wlm.cfg. The xxx represents an arbitrary
39
v
v
v
v
v
group name that you select. It is possible to have multiple groups. If the default
Plex name cpx1 is used, these variables are not set.
Ensure that your customized CICS WLM initialization file /var/cicssm/repos/
cicssm.config is located on all machines on which CICS WLM components are
to run. This is discussed in Performing the initial configuration on page 34. (The
customization of this file is discussed in Customizing the initialization file on
page 33.)
Ensure that you have a working configuration in which DPL or DTR requests can
be successfully performed.
If CICS ECI or EPI client routing is to be enabled, ensure that the CICS
WLM-supplied user exits are installed and configured for the COR, and that the
BHG_WCL_APPLICATION environment variable is set to an appropriate value in
the environment file of the COR.
Ensure that the CICS exits are active when CICS is cold started. View the
console file in /var/cics_regions/region_name/ to verify that the CICS exits are
active.
Use the CRTE transaction to check whether it is possible to route requests
between all the required points.
Check whether the applications and all their required resources are available on
all the required CICS systems.
Perform static routing requests and verify that they complete as expected.
Initial activation sequence

The sequence for starting the components of the CICS Workload Management
(WLM) utility after performing the initial configuration ensures that the local
Workload Cache Managers (WCMs) have a global Workload Management
Application cache (WAP) to connect to when they are started. The correct initial
sequence for starting the components is:
1. Start the WAP.
2. Start the WCM or WCMs.
3. Verify the object description you created that is contained in
/var/cicssm/repos/wlm.cfg.sample. This is discussed in Verifying and loading
the configuration file on page 33. (The customization of this file is discussed in
Describing the environment to CICS WLM on page 27.)
4. Load the verified CICS WLM configuration file (wlm.cfg).
5. Cold start all Client Owning Regions (CORs) and Application Owning Regions
(AORs).
6. Ensure that all environment variables are set. See Before you start the CICS
WLM on page 39 for discussion on these variables.
7. Stop and restart the CICS Transaction Gateway Daemon that connects to the
CORs.
command. The cicswlm configure command is discussed in Performing
the initial configuration on page 34. The cicswlm verify command ensures
that no errors exist in the configuration file. This command must be run on
the wlm.cfg. file before the file is loaded.
After a WCM cache has been populated, it is possible to continue routing requests
although the WAP is not available. However, when the WAP is next started and a
configuration loaded, the contents of the WCM cache are replaced.
40
In the following sections, assume that a WAP has been defined with the name
wap1, and that the CICS WLM configuration is defined in the file
/var/cicssm/repos/wlm.cfg.
Starting a WAP
To start a WAP, follow these steps:
cicswlm start wap wap1
You can check for the presence of the WAP by issuing the command cicswlm list.
Note: Simply starting a WAP does not enable workload management. A
configuration must also be loaded into the WAP cache. See Loading the
configuration file on page 42 for more information.
Starting a WCM
To start a WCM, follow these steps:
v Authenticate as the user cicssm on the machine that is to have a WCM started.
v Issue the command:
cicswlm start wcm wap1
You can check for the presence of the WCM by issuing the command cicswlm list.
When it is started, a WCM attempts to connect to the WAP. If the WAP is not
started, the WCM attempts again to make the connection. After several attempts it
ceases retrying. In such a case: stop the WCM; start the WAP, then restart the
WCM.
Note: Plex parameters control the number of connection attempts and timeout
periods when a WCM attempts to connect to a WAP. See Specifications for
the Plex object on page 29 for more details.
Verifying the configuration file

After you have created the CICS WLM configuration file, you can have CICS WLM
read this file and check its syntax by doing the following:
1. Authenticate as the user cicssm on the machine that contains the
already-started WAP.
cd /var/cicssm/repos

cicswlm verify wlm.cfg
No checks are available to ensure that the machine names or CICS resource
names given in the configuration file actually exist. The purpose of the file parsing is
to ensure that the syntax of the file is correct and that no references exist to
undefined entries within the file. Any errors are displayed to the screen as the
standard output stream.
Chapter 6. Starting CICS WLM for the first time
41
Loading the configuration file

The cicswlm load command loads a configuration file. Run this command only on
a verified file, and only on a machine on which a WAP has already been started.
See Verifying the configuration file on page 41 for information about verifying the
CICS WLM configuration file.
After verifying the wlm.cfg configuration file, load it as follows:
1. Authenticate as the user cicssm on the machine that contains the
already-started WAP.

cicswlm load wlm.cfg wap1
Initially, the WAP and all WCM caches are empty. Data is explicitly loaded into only
the WAP cache. This is done by using the cicswlm load command. The WCM is in
communication with the WAP, and data is supplied to the WCM from the WAP on
an as-needed basis. This approach minimizes the amount of transmitted data and
avoids immediately supplying the whole configuration where it possibly is not
needed.
The first time a configuration is loaded, all the information is passed to the WLM
application. Subsequently, when a configuration is loaded, its contents are
compared with those previously supplied to WLM. Differences are forwarded by the
WLM application to the WLM cache managers to ensure that their information is
up-to-date. A small change in the configuration file results in only a small update to
the WLM application, reducing the amount of data that needs to be passed to the
WCMs.
For example, suppose you want to tell WLM that you are taking a particular
SystemClone offline. If the system is to be removed permanently, remove the entry
for the SystemClone from the configuration file. However, if this is a temporary
shutdown, just reset the value of the systems health attribute to 3, indicating its
unavailability. In either case, WLM will not route work to the system until it is
restored. Optionally, you can change the health attribute of the Connection between
the two systems. This method can be appropriate if you want to stop work from
being routed from one particular system to another.
42
Chapter 7. Testing CICS WLM

If the CICS WLM utility is not supplied with the information that is required for the
routing of a work request, the work request is routed to the default that is supplied
in the External Call Interface (ECI) and External Presentation Interface (EPI)
program or in the EXEC CICS statement. Work requests continue to be processed,
but they are not being managed by CICS WLM. It is important to ensure that the
routing decisions are being made by the CICS WLM algorithm, instead of by the
definition defaults.
One possible way to test your implementation to ensure that the routing decisions
are being made by CICS WLM, is by continually issuing routing requests, and
simultaneously starting and stopping CICS systems within the Plex. The following
list provides a suggested sequence of events for testing CICS WLM:
1. Activate the CICS WLM utility by using the steps that are detailed in Chapter 6,
Starting CICS WLM for the first time, on page 39.
2. Start a Health Monitor (HMON) on the Workload Management Application
Program cache (WAP) machine to monitor the status of the CICS systems in
the Plex.
3. Start the Routing Monitor (RMON) to view the Workload Management Cache
Manager (WCM) cache that is associated with the CICS system that handled
the routing request. (Details of the expected Plex are loaded only after the first
program or transaction is run.)
4. Issue a Distributed Program Link (DPL) or a Dynamic Transaction Routing
(DTR) request, or issue an ECI, or EPI request to be routed by CICS WLM.
Issue a work request for each type you are managing. Work with a small
number of requests.
For DPL work requests
Use CECI LINK PROGRAM from the Client Owning Region (COR). If
you use CECI, you must use the PF3 key to exit the CECI transaction,
or all subsequent work requests are routed to the CICS region that was
selected when CECI was first invoked.
For DTR work requests
Issue a transaction request from the COR. Each transaction is a
separate work request and is routed individually by CICS WLM.
For ECI/EPI work requests
Write an ECI/EPI client program that issues a single work request. The
sample ECI and EPI programs that are shipped with CICS on Open
Systems can be easily modified for this purpose. No special
considerations are required because the workload management function
that CICS WLM performs is transparent to the client program. The client
program needs only the following features:
v A formatted COMMAREA
v A call to the required server program
v Specification of a valid user ID and password
43
Using testing tools and a testing environment

It is beneficial have the workload management configured and operational when
you establish tools for testing the CICS environment. Examples of these testing
tools are discussed in Chapter 8, Creating a simple routing environment, on page
47. The minimum testing environment consists of a request driver and a suitable
CICS application.
The type of request driver depends on the type of workload management that is
deployed in your environment. Usually, a CICS ECI driver is needed for DPL
requests, and a CICS EPI driver is required for DTR requests.
The request driver issues multiple requests to provide a volume of work for CICS
WLM to manage. You can run a single instance of the request driver, or implement
multiple instances of request drivers. By specifying certain items as environment
variables, you can extend the flexibility of the request driver and allow it to be used
with multiple applications. Consider specifying these items as environment
variables:
v The CICS system to which work requests are issued
v The number of requests
v The name of the CICS resource that is being called
To verify where work requests have been routed, write a simple CICS program,
transaction, or both, that will return the name of the CICS system (LocalSysId value
specified in the CICS Resource Definition (RD) stanza) in which the program or
transaction ran. Chapter 8, Creating a simple routing environment, on page 47
shows:
v A simple program for issuing DPL work requests in Application source code for
DPL requests (called.css) on page 55
v A simple DTR program in Application source code for DTR requests (wlmt.ccs)
on page 55
v A simple ECI program in Application source code for ECI requests
(cicseciwlm.c) on page 56
v A simple EPI program in Application source code for EPI requests
(cicsepiwlm.c) on page 59
Build a test environment to introduce CICS WLM. A suggested minimum
configuration consists of one COR (routing point) and two or more Application
Owning Regions (AORs). Ideally, these are distributed among multiple machines.
Also, test with a WCM on a machine that is separate from the WAP.
See Chapter 8, Creating a simple routing environment, on page 47 for full details
on the Route Test example code and environment setup.
Starting the HMON

Health monitoring can be started and stopped on request. For the HMON to
function, the following is required:
v The client must be installed on the same machine as that which is running the
WAP and the HMON.
v The associated WAP must be active.
v A loaded configuration must exist.
44
The process is as follows:

1. Authenticate as the user cicssm on the machine that is to have an HMON
started.
2. Ensure that the environment variable CICS_HOSTS is correctly set for your
machine. (This is set in the profile file of the cicssm user.)
cicswlm start hmon wap1
While the HMON is active, it overrides any health values that are assigned to CICS
regions in the configuration file wlm.cfg. If you have set the health value of a
system to nonfunctioning, and HMON detects that it is active, HMON overrides the
configuration setting. If you want to run the system with the settings that are
registered in the configuration file wlm.cfg, HMON must not be active.
To force a particular health value for a CICS region, you must stop HMON and load
a CICS WLM configuration file that has the appropriate health value assigned. The
HMON must remain inactive during this process; therefore, the dynamic health
monitoring for the other CICS regions is no longer taking place either. Two ways
that are more advisable are available to stop routing to the region. In the CICS
WLM configuration file, either set one half of the connection to that system as being
down, or remove the CICS region.
Alternatively, the loss of a region can be detected by your system management tool.
In that case, the system management tool updates the CICS WLM configuration file
with a new health value for the affected CICS region and reloads the CICS WLM
configuration file. The updated health value is read and used in subsequent routing
decisions. This method is more complicated, but enables the use of the monitoring
component of your current systems management. This method is useful when the
loss of a region is required to trigger multiple events and your systems
management tool can do this.
Note: The Health Monitor cannot be used to monitor the health of Windows
machines. To monitor the health of a Windows machine, create a series of
configuration files in which edited values control the availability of servers.
Starting the RMON

CICS WLM provides a monitor to display the contents of a WCM cache. This
monitor shows the routing that has occurred from each WCM. Because the display
is updated dynamically, it provides an up-to-date report of routing activity. The
results that are displayed for each WCM are different, because the routing at any
two WCMs is not identical.
An X terminal environment is required to run the RMON. Alternatively, on the AIX
platform, an AIX terminal window can be used to run the RMON.
To start the RMON:
1. Authenticate as the user cicssm on the machine that contains the WCM cache
that you want to display.
2. Ensure that the environment variable DISPLAY is correctly set for your display.
cicswlm start rmon
Chapter 7. Testing CICS WLM
45
To terminate the display, close the X terminal window, or use the PF3 key.
See Appendix B, Routing Monitor displays, on page 103 for examples of screens
that the RMON displays, and a discussion about the information that they contain.
46
Chapter 8. Creating a simple routing environment

This section provides a brief example to show the creation of a simple CICS
environment that uses the CICS Workload (CICS WLM) utility. Management is
shown for the following request types:
v Distributed Program Link (DPL)
v Dynamic Transaction Routing (DTR)
v External Call Interface (ECI)
v External Presentation Interface (EPI)
The section shows the necessary CICS and CICS WLM definitions that are required
for the building of the environment. Also, it shows how to verify that routing is
successfully taking place. The techniques that are provided in this section are
aimed at a low volume of testing to establish that CICS WLM is functioning
correctly. Techniques to increase the volume and intensity are discussed in
Appendix A, Volume testing, on page 101.
This section assumes that CICS and CICS WLM have been installed on the
machine on which the simple configuration is to be built.
Note: If you want to stop routing through the CICS WLM utility and return to the
routing procedure that is performed under normal CICS processing, you
must use the cicswlm clean command to remove files from the /tmp
directory. See Cleaning up CICS WLM resources on page 70 for
information about using this command.
The sample environment

For this simple environment to be of value, a minimum of three CICS regions is
required:
v One region that issues requests
v Two regions that can handle the requests
The three CICS regions in this sample environment are called CICSA, CICSB, and
CICSC. The region named CICSA issues the DPL and DTR requests; it is known as
a TYPE1 region. The regions CICSB and CICSC can both run any DPL or DTR
requests that are routed from CICSA. These two CICS regions are known as
TYPE2 regions. CICS WLM uses the region type to determine the SystemModels
on which the CICS systems are based.
The sample environment contains four applications:
v A program that tests the routing of DPL requests. This program posts a message
in the CICS COMMAREA of the system that issues that program call; the posted
message identifies the system on which the program ran. The linked program is
known as called.
v A program that tests the routing of DTR requests. It generates a transaction that
returns a message to the screen; the message names the CICS system in which
the transaction ran. The transaction that is used is named WLMT and is
associated with a program that is known as wlmt. Both the program and
transaction are configured to run in CICSB and CICSC.
47
v A program that tests the routing of ECI requests. This program posts a message
in the CICS COMMAREA of the system that issues that program call; the posted
message identifies the system on which the program ran. The linked program is
known as called.
v A program that tests the routing of EPI requests. It generates a transaction that
returns a message to the screen; the message names the CICS system in which
the transaction ran. The transaction that is used is named WLMT and is
associated with a program that is known as wlmt. Both the program and
transaction are configured to run in CICSB and CICSC.
This sample environment can be constructed over a single machine or multiple
machines. For simplicity, a single machine is suggested. Ensure that the machine
has enough CPU and memory to support three running CICS systems, a Structured
File Server (SFS) server, and the CICS WLM components. The CICS WLM
components take little additional CPU. If the machine you have chosen can support
the necessary CICS regions and SFS server, it is an adequate environment.
A single CICS WLM Workload Management application cache (WAP) and a single
Workload Cache Manager (WCM) exist in this sample environment. These
components are on the same machine as that on which are the CICS regions.
This sample environment is assumed to have the following configuration:
v The SFS is named /.:/cics/sfs/wlmtest.
v
The CICS environment uses Remote Procedure Call-only (RPC-only).
v CICSA, CICSB, and CICSC are all implemented on a machine (Node) that is
called wlmtest.
v Each CICS region has one CICS IP listener defined. These listeners operate on
the following TCP ports: 1435 for CICSA, 1436 for CICSB, and 1437 for CICSC.
v Service names are allocated for these ports in the /etc/services file:
cicstcp1 for port 1435
Table 9 shows the communication information for the sample environment.
Table 9. Communication information for the sample environment
CICS Region
TCP Port
Service name allocated in

/etc/services
CICSA
1435
cicstcp1
CICSB
1436
cicstcp2
CICSC
1437
cicstcp3
CICS setup
The following steps are needed for the building of a suitable CICS environment:
1. Create the necessary CICS systems.
2. Prepare the CICS application programs for use.
3. Configure the necessary resources on those CICS regions.
48
CICS system setup

The specific details for creating a basic CICS environment are beyond the scope of
this document. For information about these topics, see the TXSeries for
Multiplatforms Installation Guide. The following actions give a high-level overview:
1. Create an SFS server. Use the cicscp command to create one for you.
Alternatively, on the AIX platform, you can use SMITTY to create an SFS server.
2. Create three default CICS regions: CICSA, CICSB, and CICSC.
3. Configure the necessary CICS files on the SFS server for each of the CICSA,
CICSB, and CICSC regions.
4. Ensure that each of the CICS regions can start and can be accessed. Solve any
problems that occur.
5. Stop each of the CICS regions.
Application program setup

The source code for the application programs must be created and compiled.
v The program that is used to test CICS DPL is known as called.ccs. See
Application source code for DPL requests (called.css) on page 55 for the
contents of this program.
v The program that is used to test CICS DTR is known as wlmt.ccs. See
Application source code for DTR requests (wlmt.ccs) on page 55 for the
v The program that is used to test CICS ECI is known as cicseciwlm.c. See
Application source code for ECI requests (cicseciwlm.c) on page 56 for the
v The program that is used to test CICS EPI is known as cicsepiwlm.c. See
Application source code for EPI requests (cicsepiwlm.c) on page 59 for the
Samples of the files for these source codes are included in the directory
install_dir/cicssm/sample (where install_dir is /usr/lpp on AIX ). The sample files are:
v called.ccs. The DPL back-end CICS code (should be configured in each AOR)
v wlmt.ccs. The DTR back-end CICS code (should be configured in each AOR)
v mainctrl.ccs. The front-end CICS code for DPL (should be configured in the
COR)
v cicseciwlm.c. The ECI program.
v cicsepiwlm.c. The EPI program
Compile the DPL and DTR programs by using the CICS-provided utility cicstcl:
cd /cicswlm/test/cics
cicstcl -lC called.ccs
cicstcl -lC wlmt.ccs
These required applications are compiled and ready for use.

To prepare the ECI and EPI programs:
1. Compile the two programs cicseciwlm.c and cicsepiwlm.c with the CTG libraries.
Refer to the CICS Transaction Gateway Programming Guide for information
about how to do this.
2. Ensure that the relevant CICS user exit for ECI request routing is installed.
49
3. Ensure the environment variables are correctly set. See Before you start the
CICS WLM on page 39 for discussion on these variables.
4. Ensure the BHG_WCL_APPLICATION environment variable and other variables
are correctly set. To run the sample program that is discussed in the chapter,
the variable must be set as follows:
BHG_WCL_APPLICATION="Appl1"
See Setting environment variables for EPI routing management on page 37

and Before you start the CICS WLM on page 39 for discussion on these
variables.
Configuring CICSA (the COR)

The following definitions and changes must be added to CICSA:
v A Listener Definition (LD) is required to listen for incoming requests.
v Communications Definition (CD) entries are required for communication with
CICSB and CICSC. The connection to CICSB is named B1, and the connection
to CICSC is named B2.
v A Transaction Definition (TD) entry is required for the transaction WLMT.
v Program Definitions (PD) entries are required for the programs called.
v The LocalSysId of the region must be modified from the default.
v The CICS WLM-provided CICS exits must be added.
CICS commands for configuring the COR: Issue the following CICS commands
to make the required definition changes:
This command adds a LD:
cicsadd -c ld -r CICSA LD01 TCPAddress=wlmtest TCPService=cicstcp1
This command adds a CD for CICSB:

cicsadd -c cd -r CICSA B1 ConnectionType=cics_tcp RemoteLUName=CICSB /
ListenerName=LD01 RemoteTCPAddress=wlmtest RemoteTCPPort=1436
This command adds a CD for CICSC:

cicsadd -c cd -r CICSA B2 ConnectionType=cics_tcp RemoteLUName=CICSC /
This command adds a PD for called:

cicsadd -c pd -r CICSA CALLED RemoteSysId=B1 RSLKey=public
This command adds a PD for mainctrl:

cicsadd -c pd -r CICSA MAINCTRL PathName="install_dir/cicssm/samples/mainctrl /
RSLKey=public
This command adds a TD for WLMT:

cicsadd -c td -r CICSA WLMT Dynamic=yes RemoteSysId=B1 /
RemoteName=WLMT ProgName=WLMT RSLKey=public
This command modifies the default LocalSysId:

cicsupdate -c rd -r CICSA LocalSysId=CICA
This command adds a user exit number 50 for DPL links:

cicsadd -c pd -r CICSA BHGDPL PathName=install_dir/cicssm/bin/bhgdpl /
UserExitNumber=50 Resident=yes
50
This command adds a user exit number 51 for DPL links:

cicsadd -c pd -r CICSA BHGDPLSP
PathName=install_dir/cicssm/bin/bhgdplsp /
This command adds a user exit number 25 for DTR links:

cicsadd -c pd -r CICSA BHGDTR
PathName=install_dir/cicssm/bin/bhgdtr /
Note: install_dir is /usr/lpp on AIX .
Configuring CICSB and CICSC (the AORs)

The following definitions and changes must be added to both CICSB and CICSC:
v An LD entry to listen for incoming requests.
v CD entries to communicate with CICSA. The connection to CICSA is called B1
for both CICSB and CICSC.
v A TD entry for WLMT.
v A PD entry for the program wlmt.
v A PD for the program called.
v Modify the LocalSysId of the region from the default.
CICS commands for configuring the AORs: Issue the following CICS
commands to make the required definition changes:
This command adds a TCPService of cicstcp3 for CICSB and CICSC:
cicsadd -c ld -r CICSB LD01 TCPAddress=wlmtest TCPService=cicstcp2
cicsadd -c ld -r CICSC LD01 TCPAddress=wlmtest TCPService=cicstcp3
This command adds the same CD definition for CICSB and CICSC:
cicsadd -c cd -r CICSB B1 ConnectionType=cics_tcp RemoteLUName=CICSA /
cicsadd -c cd -r CICSC B1 ConnectionType=cics_tcp RemoteLUName=CICSA /
This command adds the same definition for called for CICSB and CICSC:
cicsadd -c pd -r CICSB CALLED PathName="install_dirp/cicssm/samples/called" /
RSLKey=public
cicsadd -c pd -r CICSC CALLED PathName="install_dir/cicssm/samples/called" /
RSLKey=public

This command adds the same PD definition for wlmt for CICSB and CICSC:
cicsadd -c pd -r CICSB WLMT PathName="install_dir/cicssm/samples/wlmt" RSLKey=public
cicsadd -c pd -r CICSC WLMT PathName="install_dir/cicssm/samples/wlmt" RSLKey=public

This command adds the same TD definition for WLMT for CICSB and CICSC:
cicsadd -c td -r CICSB WLMT ProgName=WLMT RSLKey=public
cicsadd -c td -r CICSC WLMT ProgName=WLMT RSLKey=public
This command adds a LocalSysId of CICB for CICSB and a LocalSysID of CICC for
CICSC:
51
cicsupdate -c rd -r CICSB LocalSysId=CICB

cicsupdate -c rd -r CICSC LocalSysId=CICC
The configuration of the CICS regions is now complete.
CICS WLM setup

CICS WLM must be configured and verified before it can be used. The following
steps are required:
v Edit the file /var/cicssm/repos/cicssm.config to specify the location of the WAP.
An example file is given in Initialization file for Routing Test sample code on
page 64.
Note: The /var/cicssm/repos/cicssm.config path name is the same on the AIX
platform.
v Perform the initial configuration:
1. Authenticate as the user cicssm.
cicswlm configure wlm
v Create wlm.cfg, a CICS WLM configuration file that defines the object model.
This file should look like the one that is given in Configuration file for Routing
Test sample code on page 64. Ensure that the machine name supplied is the
fully qualified host name, including the domain name, for example,
v Perform the verification:
1. Authenticate as the user cicssm.
The CICS WLM configuration is created, and the verification is complete. Now, you
can start CICS WLM, and load the CICS WLM configuration file.
Ensuring that request routing works correctly without CICS WLM

Having completed the configuration of CICS and CICS WLM, you are now ready to
start CICS and CICS WLM. The sequence of events follows:
1. Cold start the CICS regions and perform the following checks:
v Ensure that no errors occurred in the startup process.
v Ensure that the cicsip processes started correctly in all CICS systems.
v Ensure that the CICS user exits 25, 50, and 51 are enabled in CICSA.
2. Ensure that it is possible to route from CICSA to each of the other two regions.
Do this by using the CICS-provided CRTE transaction from CICSA. Access
CICSA by using a cicslterm window.
3. Run the WLMT transaction from a cicslterm window that is signed onto CICSA.
4. Ensure that a message is returned that indicates the program ran in system
CICSB.
5. Run the program that has the name of called, by issuing the following command
from a cicslterm window that is accessing CICSA:
CECI LINK PROGRAM(CALLED) COMM(123456789012345) LENGTH (30)
6. Ensure that the COMM field contains a message indicating that the program ran
in system CICSB on completion.
52
7. The procedure for running an ECI request is as follows:

a. Change to the directory in which the compiled programs mentioned above
are located.
b. Issue the command:
cicseciwlm
c. Observe the message that is returned in the COMM field. This message
indicates the CICS region in which the program ran. The value is either
CICSB or CICSC, depending on the LocalSysId of the region to which the
request was routed.
8. The procedure for running an EPI request is as follows:
a. Change to the directory in which the compiled programs mentioned above
are located.
b. Issue the command:
cicsepiwlm
c. Observe the message that is returned in the COMM field. This message
indicates the CICS region in which the program ran. The value is either
CICSB or CICSC, depending on the LocalSysId of the region to which the
request was routed.
All the required CICS regions and the components of CICS WLM are started. Now,
you can issue routing requests.
Issuing routing requests using CICS WLM

To issue routing requests by using CICS WLM:
1. Authenticate as the user cicssm and issue the commands:
cicswlm start wap wap1
cicswlm start wcm wap1
export DISPLAY=<your screen ip address>
export CICS_HOSTS=wlmtest
cicswlm start hmon wap1
cicswlm start rmon
This command causes a monitor display to be started in an X terminal or AIX

terminal window that shows the contents of the WCM cache.
2. Cold start all your CICS regions.
With all the components of the system started, you can issue requests that are to
be routed under the control of CICS WLM. Four types of request can be issued:
DPL, DTR, ECI, and EPI. The DPL request is issued most easily by using the
CICS-provided CECI transaction. The DTR request is issued by running the
transaction WLMT. The ECI request is issued most easily by running the program
cicseciwlm. The EPI request is issued most easily by running the program
cicsepiwlm.
To run a DPL request:
1. Start a cicslterm window and access the CICSA system.
2. Run the following CICS transaction:
CECI LINK PROGRAM(CALLED) COMM(123456789012345) LENGTH (30)
53
3. Observe the message that is returned in the COMM field. This message
indicates the CICS region in which the program ran. The value is either CICSB or
CICSC, depending on the LocalSysId of the region to which the request was
routed.
To run a DTR request:
1. Start a cicslterm window and access the CICSA system.
2. Issue the WLMT transaction
3. Observe the message that is returned. This message indicates the CICS region
on which the transaction ran. The value is either CICSB or CICSC, depending on
the LocalSysId of the region to which the request was routed.
To run an ECI request:
1. Change to the directory in which the program is located.
2. Issue the following command several times and compare the output:
cicseciwlm
routed.
To run an EPI request:
1. Change to the directory in which the program is located.
2. Issue the following command several times and compare the output:
cicsepiwlm
routed.
Validating routing requests

When a DPL or DTR request is issued and it runs in a CICS region other than the
default assigned to it, it is easy to see that dynamic workload management is
occurring. When the request is routed to the same region as the default region, it is
not so easy to determine whether the request was routed by CICS WLM, or
whether it was allowed to default.
Using the Routing Monitor, a WCM cache monitor that is provided with CICS WLM,
is the easiest way to determine how routing decisions are made. It shows the
routing decisions that are made from all clients that share a WCM. In this example,
CICSA is the only client that is using the WCM.
Alternatively, it is possible to verify that CICS WLM is handling the routing requests
by tracing the appropriate CICS WLM components.
See Appendix B, Routing Monitor displays, on page 103 for a discussion about the
information that is displayed by the Routing Monitor screens in the actual operation
of this example system.
54
Application source code for DPL requests (called.css)

This section contains the source code for the application program that is used to
issue DPL requests in this simple environment.
Source for called.ccs
/**************************************************************
*/ NAME
: called.ccs /*
*/ /*
*/ LANGUAGE
: C with embedded CICS. /*
*/ /*
*/ SYNOPSIS
: This program is a module that is linked to
(EXEC CICS LINK ()) from a calling module.
It passes back a COMMAREA with the
SYSID of the region where it is executing.
It is used in the CICS WLM testing suite
for DPL tests. /*
*/ /*
*/ **********************************************************/*
#include <stdio.h>
#include "dfhaid.h"
#define comm_len 30
char sysid[4];
char* commarea;
void main(void)
{
EXEC CICS ADDRESS EIB(dfheiptr);
EXEC CICS ADDRESS COMMAREA(commarea);
EXEC CICS INQUIRE SYSTEM SYSID(sysid);
memset (commarea, \0, commarea_len);
memcpy(commarea, "CALLED Ran in ", 14);
memcpy(commarea+14, sysid, 4);
EXEC CICS RETURN;
}
Application source code for DTR requests (wlmt.ccs)

issue DTR requests in this simple environment.
/**************************************************************/*
*/ /*
*/ NAME
: wlmt.ccs /*
*/ /*
*/ LANGUAGE
: C with embedded CICS. /*
*/ /*
*/ SYNOPSIS
: Program to issue a message indicating
where the program ran. Used for testing DTR
requests and CICS WLM. /*
*/ /*
*/ **********************************************************/*
#include <stdio.h>
#include "dfhaid.h"
#define msg_len 20
char sysid[4];
char msg[msg_len];
int msg_size=0;
void main(void)
{
EXEC CICS ADDRESS EIB(dfheiptr);
EXEC CICS INQUIRE SYSTEM SYSID(sysid);
memset(msg, \0, msg_len);
memcpy(msg, " ==> Ran in ", 12);
memcpy(msg+12, sysid, 4);
55
msg_size = strlen(msg);
EXEC CICS SEND FROM(msg) LENGTH(msg_size);
EXEC CICS RETURN;
}
Application source code for ECI requests (cicseciwlm.c)

This section contains the source code for the ECI application program that is used
to issue DPL requests in this simple environment.
/*******************************************************************************
* NAME: cicsecic.c - CICS External Call Interface sample
* VERSION : 1.1
* SYNOPSIS This sample is based on the CICS sample program cicsecic.c (modified).
* This program takes up to two parameters:
* -- A System name to which the ECI call should be issued, default is CICSA
* -- A Program name (defined on COR, locally or remotely), default is MAINCTRL.
*
********************************************************************************
* The program reads the supplied parameters OR uses the default values.
* A synchronous call is then issued to the CICS region (COR) for the required
* program. The data returned in the COMMAREA is displayed.
********************************************************************************
*/
#include <stdio.h>
#include <stdarg.h>
#include <string.h>
#include <locale.h>
#include <locale.h>
/*
* Defines
*/
#define COMMAREA_SIZE
30
/*
* Global Variables
*/
ECI_PARMS
EciParms;
char
Server[9] = "CICSA";
char
UserID[9] = "CICSUSER";
char
Program[9] = "CALLED";
char
PassWd[9] = "";
/* FILL
/*
* Function Prototypes
*/
int
main
void
EciSync
void
Response
FILL
FILL
FILL
YOUR
IN YOUR SERVER HERE

IN YOUR USER ID HERE
IN YOUR USER ID HERE
PASSWORD HERE */
(int argC, char **argV);

(void);
(char *Call, short Rc, char *Abend);
/*
* main() - Sample Entry Point
*/
int main(int argC, char **argV)
{
puts("ECI Sample Program\n");
puts("------------------\n\n");
/*
* Pick up the locale from the environment
*/
(void)setlocale(LC_ALL,"");
if (argC < 2)
56
/*
/*
/*
IN
*/
*/
*/
{
printf("Region name must be supplied");
exit(1);
}
else
{
strncpy (Server, argV[1], 8);
if (argC > 2)
{
strncpy (Program, argV[2], 8);
}
}
printf("Using Server: [%s], Program: [%s]\n", Server, Program);
/*
* Make a syncronous link call
*/
EciSync();
} /* main */
/*
* EciSync
*
* Issue a CICS_Externalcall for an ECI_SYNC link
*/
void EciSync(void)
{
char
*Name = "ECI_SYNC";
short
Rc;
char
CommArea [COMMAREA_SIZE];
printf ("\n%s test\n", Name);
memset (CommArea, \0, COMMAREA_SIZE);
strcpy (CommArea, "
");
memset (&EciParms, 0, sizeof (ECI_PARMS));
EciParms.eci_version
EciParms.eci_call_type
memcpy(&EciParms.eci_program_name, Program,
memcpy(&EciParms.eci_userid,
UserID,
memcpy(&EciParms.eci_password,
PassWd,
memcpy(&EciParms.eci_system_name, Server,
EciParms.eci_commarea
EciParms.eci_commarea_length
EciParms.eci_extend_mode
EciParms.eci_luw_token
EciParms.eci_timeout
= ECI_VERSION_1A;
= ECI_SYNC;
8);
8);
8);
8);
= CommArea;
= COMMAREA_SIZE;
= ECI_NO_EXTEND;
= ECI_LUW_NEW;
= 0;
Rc = CICS_ExternalCall (&EciParms);
Response(Name, Rc, EciParms.eci_abend_code);
if (Rc == ECI_NO_ERROR)
{
CommArea[(COMMAREA_SIZE-1)] = \0;
printf ("CommArea Returned: %s\n", CommArea);
} /* endif */
printf ("%s test complete\n\n", Name);
return;
} /* EciSync */
/*
* Response
57
*
* Display the immediate response code from an ECI call
*
*/
void Response(char *Call, short Rc, char *Abend)
{
char
*p;
switch (Rc)
{
case ECI_NO_ERROR:
p = "ECI_NO_ERROR
";break;
case ECI_ERR_INVALID_DATA_LENGTH:
p = "ECI_ERR_INVALID_DATA_LENGTH";break;
case ECI_ERR_INVALID_EXTEND_MODE:
p = "ECI_ERR_INVALID_EXTEND_MODE";break;
case ECI_ERR_NO_CICS:
p = "ECI_ERR_NO_CICS
";break;
case ECI_ERR_CICS_DIED:
p = "ECI_ERR_CICS_DIED
";break;
case ECI_ERR_REQUEST_TIMEOUT:
p = "ECI_ERR_REQUEST_TIMEOUT
";break;
case ECI_ERR_RESPONSE_TIMEOUT:
p = "ECI_ERR_RESPONSE_TIMEOUT
";break;
case ECI_ERR_TRANSACTION_ABEND:
p = "ECI_ERR_TRANSACTION_ABEND ";break;
case ECI_ERR_EXEC_NOT_RESIDENT:
p = "ECI_ERR_EXEC_NOT_RESIDENT ";break;
case ECI_ERR_SYSTEM_ERROR:
p = "ECI_ERR_SYSTEM_ERROR
";break;
case ECI_ERR_NULL_WIN_HANDLE:
p = "ECI_ERR_NULL_WIN_HANDLE
";break;
case ECI_ERR_NULL_MESSAGE_ID:
p = "ECI_ERR_NULL_MESSAGE_ID
";break;
case ECI_ERR_THREAD_CREATE_ERROR:
p = "ECI_ERR_THREAD_CREATE_ERROR";break;
case ECI_ERR_INVALID_CALL_TYPE:
p = "ECI_ERR_INVALID_CALL_TYPE ";break;
case ECI_ERR_ALREADY_ACTIVE:
p = "ECI_ERR_ALREADY_ACTIVE
";break;
case ECI_ERR_RESOURCE_SHORTAGE:
p = "ECI_ERR_RESOURCE_SHORTAGE ";break;
case ECI_ERR_NO_SESSIONS:
p = "ECI_ERR_NO_SESSIONS
";break;
case ECI_ERR_NULL_SEM_HANDLE:
p = "ECI_ERR_NULL_SEM_HANDLE
";break;
case ECI_ERR_INVALID_DATA_AREA:
p = "ECI_ERR_INVALID_DATA_AREA ";break;
case ECI_ERR_INVALID_VERSION:
p = "ECI_ERR_INVALID_VERSION
";break;
case ECI_ERR_UNKNOWN_SERVER:
p = "ECI_ERR_UNKNOWN_SERVER
";break;
case ECI_ERR_CALL_FROM_CALLBACK:
p = "ECI_ERR_CALL_FROM_CALLBACK ";break;
case ECI_ERR_MORE_SYSTEMS:
p = "ECI_ERR_MORE_SYSTEMS
";break;
case ECI_ERR_NO_SYSTEMS:
p = "ECI_ERR_NO_SYSTEMS
";break;
case ECI_ERR_SECURITY_ERROR:
p = "ECI_ERR_SECURITY_ERROR
";break;
case ECI_ERR_MAX_SYSTEMS:
p = "ECI_ERR_MAX_SYSTEMS
";break;
case ECI_ERR_MAX_SESSIONS:
p = "ECI_ERR_MAX_SESSIONS
";break;
case ECI_ERR_ROLLEDBACK:
p = "ECI_ERR_ROLLEDBACK
";break;
default:
58
{
p = "!!!Unknown!!!";
printf ("Unknown Return Code : %d\n", Rc);
} /* endcase */
break;
} /* endswitch */
printf ("%s returned: %s\n", Call, p);
if (Rc != ECI_NO_ERROR)
{
printf("Abend code was \"%4.4s\"\n", Abend);
} /* endif */
return;
} /* Response */
Application source code for EPI requests (cicsepiwlm.c)

issue EPI requests in this simple environment.
/*********************************************************************/
* NAME:
EPI Sample 1 - cicsepiwlm.c
*
* VERSION:
1.1
*
* SYNOPSIS:
*
This sample is based on the CICS sample program cicsepi1a.c
*
This is a sample EPI application program for CICS. It takes
*
two parameters: the name of a CICS region and a transaction
*
to be run.
*
A single EPI terminal is added to the region. The supplied
*
transaction name is run (default value WLMT). The data
*
received from running the transaction is displayed.
*
*
The WLMT transaction simply does an EXEC CICS SEND of
*
"Ran in <LocalSysId>" and terminates.
*
*
This sample demonstrates simple use of the
*
following EPI functions:
/*********************************************************************/
#include <cicstype.h>
#include <stdio.h>
#include <pthread.h>
#include <locale.h>
#include <cics_epi.h>
/* Include the EPI header file */
char Transaction[5]; /* Used to hold the CICS transaction to be run */
char System[5];
/* Used to hold the CICS region to run against */
/*********************************************************************/
* This is a piece of dummy 3270 data (an ENTER AID key followed
* by a cursor position of (0,0)). It is used when starting transactions.
/*********************************************************************/
#define DUMMY_DATA ((cics_ubyte_t *)" ")
/*********************************************************************/
* Declare the functions used in this program.
/*********************************************************************/
void ErrorExit(cics_char_t *Function, cics_sshort_t Rc, cics_ushort_t
TermIndex);
void *EventThread(void *Parm);
void DisplayData(cics_ubyte_t *Data, cics_ushort_t Size);
/*********************************************************************/
/* Condition Variables and Mutexes used for thread coordination
*/
/*********************************************************************/
pthread_cond_t
TranEnded;
pthread_cond_t
TermEnded;
59
pthread_mutex_t Mutex;
cics_bool_t TranEnd_Flag = FALSE;
cics_bool_t TermEnd_Flag = FALSE;
/*********************************************************************/
/* ErrorExit() - Report errors and exit
*/
/* This function is called to report serious and unexpected EPI */
/* errors. It will then terminate the program.
*/
/*********************************************************************/
void ErrorExit(cics_char_t *Function, cics_sshort_t Rc, cics_ushort_t
TermIndex);
{
CICS_EpiSysError_t SysErr;
/* Receives EPI error info. */
fprintf(stderr, "%s() call failed ", Function);
if (Rc != CICS_EPI_ERR_FAILED)
{
fprintf(stderr, "with return code: %d\n", Rc);
}
else
{
CICS_EpiGetSysError(TermIndex, SysErr);
fprintf(stderr, "with a system error.\n");
fprintf(stderr, "Cause: %u, Error: %u, Message: %s\n",
SysErr.Cause, SysErr.Value,
(SysErr.Msg != NULL) ? SysErr.Msg : ">");
}
exit(1);
}
/*********************************************************************/
/* EventThread() - Event processing thread
*/
/* This function is run in a secondary thread and handles all the
*/
/* EPI event processing for the program. It calls CICS_EpiGetEvent()*/
/* in blocking mode to wait for the arrival of EPI events.
*/
/*********************************************************************/
void *EventThread(void *Parm)
{
cics_sshort_t Rc;
cics_ushort_t TermIndex;
/* Installed TermIndex */
CICS_EpiEventData_t EventData;
/* Receives EPI event details*/
cics_ubyte_t Data[200];
/* Receives event data */
TermIndex = *((cics_ushort_t *)Parm);
/*********************************************************************/
* This thread runs in a loop receiving and processing events until
* the final CICS_EPI_EVENT_END_TERM is received.
*/
/*********************************************************************/
do
{
/*********************************************************************/
/*
* Wait for next event.
/*********************************************************************/
EventData.Data = Data;
/* Point to space for any */
EventData.Size = sizeof(Data); /* incoming datastream */
Rc = CICS_EpiGetEvent(TermIndex,
CICS_EPI_WAIT, /* Wait for next event */
EventData);
/*********************************************************************/
*Return codes of CICS_EPI_NORMAL and CICS_EPI_ERR_MORE_EVENTS
*both mean the function completed successfully
*and obtained an EPI event.
/*********************************************************************/
if (Rc == CICS_EPI_NORMAL || Rc == CICS_EPI_ERR_MORE_EVENTS)
{
switch (EventData.Event)
{
/*********************************************************************/
* ENDTERMINAL: Nothing needs to be done here. The event
* processing loop will end.
60
/*********************************************************************/
case CICS_EPI_EVENT_END_TERM:
break;
/*********************************************************************/
* SEND: Display the data received from a transaction.
/*********************************************************************/
case CICS_EPI_EVENT_SEND:
DisplayData(EventData.Data, EventData.Size);
break;
/*********************************************************************/
* ENDTRAN: Signal the "TranEnded" condition variable to tell
*
the main thread to proceed.
/*********************************************************************/
case CICS_EPI_EVENT_END_TRAN:
pthread_mutex_lock(Mutex);
TranEnd_Flag = TRUE;
pthread_cond_signal(TranEnded);
pthread_mutex_unlock(Mutex);
break;
/*********************************************************************/
* Display a warning for unexpected events.
/*********************************************************************/
default:
printf("Unexpected event received (%d)\n", EventData.Event);
break;
}
}
else
{
ErrorExit("CICS_EpiGetEvent", Rc, TermIndex);
}
} while (EventData.Event != CICS_EPI_EVENT_END_TERM);
/*********************************************************************/
* Drop through to here when the terminal has ended. Display a
* message if the terminal ended for an unexpected reason and
* signal the "TermEnded" condition variable to tell the main thread
* to exit.
/*********************************************************************/
switch (EventData.EndReason)
{
case CICS_EPI_END_SIGNOFF:
break;
/* This is what we expect
*/
case CICS_EPI_END_FAILED:
printf("Terminal Delete ABENDed (\"%s\")\n", EventData.AbendCode);
break;
default:
printf("Unexpected terminal end (%d)\n", EventData.EndReason);
break;
}
TermEnd_Flag = TRUE;
pthread_cond_signal(TermEnded);
return;
}
/*********************************************************************/
/* DisplayData() - Show data sent from a transaction
*/
/* This function will display the data sent to the EPI from a CICS
*/
/* transaction. The first two bytes of the data are a 3270 command */
/* byte and the 3270 WCC, these are ignored.
*/
/*********************************************************************/
void DisplayData(cics_ubyte_t *Data, cics_ushort_t Size)
{
cics_ushort_t Index;
/* Loop counter */
if (Size > 0)
{
61
printf("The following message was received from CICS:\n");

printf("\"");
for (Index = 2; Index < Size; Index++)
printf("%c", Data[Index]);
printf("\"\n");
}
return;
}
/*********************************************************************/
/* main() - Sample Entry Point
*/
/* This program should be called with the name of a CICS region. If */
/* none is supplied it will exit with an error, otherwise it will
*/
/* install and EPI terminal and run the WLMT transaction. When the */
/* transaction ends the terminal is deleted.
*/
/*********************************************************************/
main(int argc, cics_char_t *argv[])
{
cics_sshort_t Rc;
/* EPI function return codes */
cics_ushort_t TermIndex;
/* EPI Terminal Index */
pthread_t Thread;
/* Secondary thread id */
/*********************************************************************/
* Check the caller supplied the name of a CICS region to be used.
* Give up if we havent got one.
/*********************************************************************/
if (argc < 2)
{
fprintf(stderr,"Region name must be supplied\n");
exit(1);
}
else
{
strncpy(System,argv[1],8);
if (argc == 3)
{
strncpy(Transaction,argv[2],4);
}
else
{
strncpy(Transaction,"WLMT",4);
}
}
/*********************************************************************/
* Pick up the locale from the environment
/*********************************************************************/
(void)setlocale(LC_ALL,"");
/*********************************************************************/
* Initialize the condition variables and mutexes used for thread
* coordination.
/*********************************************************************/
pthread_mutex_init(Mutex, pthread_mutexattr_default);
pthread_cond_init(TermEnded, pthread_condattr_default);
pthread_cond_init(TranEnded, pthread_condattr_default);
/*********************************************************************/
* Initialize the EPI.
/*********************************************************************/
Rc = CICS_EpiInitialize(CICS_EPI_VERSION_101);
if (Rc != CICS_EPI_NORMAL)
{
ErrorExit("CICS_EpiInitialize", Rc, CICS_EPI_TERM_INDEX_NONE);
}
/*********************************************************************/
* Install a terminal against the specified region.
* Specify the terminal model to avoid an unsuitable default.
/*********************************************************************/
62
Rc = CICS_EpiAddTerminal(NULL,
/* No Namespace needed */
argv[1],
/* Use region specified */
NULL,
/* Autoinstall the terminal */
"hft",
/* High function terminal*/
NULL,
/* No event notification */
NULL,
/* TermDetails not needed */
TermIndex); /*Receives new TermIndex */
{
ErrorExit("CICS_EpiAddTerminal", Rc, CICS_EPI_TERM_INDEX_NONE);
}
/*********************************************************************/
* Once the terminal is installed start up the secondary event
* processing thread. If this fails just terminate the EPI and exit.
/*********************************************************************/
if (pthread_create(Thread, pthread_attr_default,
EventThread, TermIndex) == -1)
{
fprintf(stderr, "Cannot start event processing thread.\n");
Rc = CICS_EpiTerminate();
exit(1);
}
/*********************************************************************/
* Submit the WLMT transaction and wait for it to complete. This is
* done by waiting on the "TranEnded" condition variable, signalled
* by the event thread. Some initial 3270 data must be provided so
* use the DUMMY_DATA.
/*********************************************************************/
Rc = CICS_EpiStartTran(TermIndex,
Transaction,
DUMMY_DATA,
sizeof(DUMMY_DATA)-1);
{
ErrorExit("CICS_EpiStartTran", Rc, TermIndex);
}
while (!TranEnd_Flag)
{
pthread_cond_wait(TranEnded, Mutex);
}
/*********************************************************************/
* The transaction has finished. The terminal is now deleted and the
* "TermEnded" condition variable used to wait for deletion to
* complete.
/*********************************************************************/
Rc = CICS_EpiDelTerminal(TermIndex);
{
ErrorExit("CICS_EpiDelTerminal", Rc, TermIndex);
}
while (!TermEnd_Flag)
{
pthread_cond_wait(TermEnded, Mutex);
}
/*********************************************************************/
63
* Finally terminate the EPI and the application.

* Clean up mutexes and condition variables
/*********************************************************************/
Rc = CICS_EpiTerminate();
{
ErrorExit("CICS_EpiTerminate", Rc, CICS_EPI_TERM_INDEX_NONE);
}
pthread_mutex_destroy(Mutex);
pthread_cond_destroy(TranEnded);
pthread_cond_destroy(TermEnded);
exit(0);
}
/*********************************************************************/
EOF
/*********************************************************************/
Initialization file for Routing Test sample code

This section describes a cicssm.config file that is suitable for the simple test
environment. This file defines the component list for the CICS WLM utility and is
used to drive the configuration of each component. It is input to the cicswlm
configure command.
In this configuration, a WAP named WAP1 is defined. It listens on port 9123 on the
machine that is named wlmtest.
WAP identification
The Node names must match the fully qualified host name, including the
domain name; for example, testlab125.company_name.com. In the following
example, wap identifies the Workload Management applications; wap1 is
the name; wlmtest is the Node; and 9123 is the TCP port.
wap
wap1
wlmtest
9123
Configuration file for Routing Test sample code

This section describes an environment that contains a CICS WLM configuration file
that is suitable for a simple test sample.
The example is partitioned by numbered sections. These numbered sections are
intended to make it easy to reference portions of the file throughout the text. The
actual file need contain only the monospaced example text.
This same configuration file is redisplayed without numbered sections for quick
reference in Appendix E, Code for the sample wlm.cfg, on page 117.
Section 1: The Plex definition starts here.
This configuration file has been constructed for a simple workload
management environment. The Plex is the highest administrative level
defined. It is defined with the name of the cpx1. The name cpx1 is the
default CICSplex name. If you use a different Plex name, two variables
must be included in the environment of the CICS regions. See Before you
start the CICS WLM on page 39 for information about these variables.
Plexes.cpx1
{

Two SystemModel objects must be set up: a Client Owning Region (COR)
64
system and an Application Owning Region (AOR) system. (All the contents
of the active configuration of this Plex are predeclared.)
SystemModels.TYPE1;
SystemModels.TYPE2;

SystemClones.CICSA;
SystemClones.CICSB;
SystemClones.CICSC;
predeclared.
SystemClones.CICSA/Connections.B1; SystemClones.CICSA/Connections.B2;
Section 5: The Connection objects from the AORs back to the COR are
predeclared.
SystemClones.CICSB/Connections.B1;
SystemClones.CICSC/Connections.B1;
Section 6: The machine name is predeclared as a Node object.

Nodes."wlmtest.acme.com";

Nodes."wlmtest.acme.com/SystemImages.CICSA";
Nodes."wlmtest.acme.com/SystemImages.CICSB";
Nodes."wlmtest.acme.com/SystemImages.CICSC";

LocalProgramModels and ApplicationModels.
The program called sends DPL routing requests. The program wlmt uses
the transaction WLMT to issue DTR requests.
LocalProgramModels.CALLED;
LocalTransactionModels.WLMT;
ApplicationModels.Appl1;

load_limit
connection_scale
same_limit_1
same_limit_2
same_scale_1
same_scale_2
known_adjustment
known_scale_1
known_scale_2
normalise_scale
equal_delta
health_adjustment_1
health_adjustment_2
health_adjustment_3
health_timeout
score_limit
retry_limit
reselection_limit
wcm_resend_timeout
wcm_retry_timeout
wcm_retry_limit_1
wcm_retry_limit_2
wcm_fail_timeout
autoinstall_load
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
600.0
;
1.0
;
5
;
10
;
0.0
;
0.0
;
0.05
;
0.0
;
0.0
;
0.00833
;
0.0001
;
0.0
;
10.0
;
100.0
;
120.0
;
5000.0
;
2
;
2
;
1.0
;
10.0
;
5
;
1
;
600.0
;
3.0
;
Section 10: The relationship of the COR SystemModel to the SystemClone is

defined.
65
SystemModels.TYPE1
{
cloned_as -> SystemClones.CICSA;
}
Section 11: The relationship of the AOR SystemModel is defined.

SystemModels.TYPE2
{
cloned_as ->
{
SystemClones.CICSB,
SystemClones.CICSC
};
}
Section 12: The attributes of the CICSA SystemClone object are specified.
SystemClones.CICSA
{
factor=1.0;
maxServers=5;
health=1;
installed_on -> Nodes."wlmtest.acme.com";
}
Section 13: The attributes of the CICSB SystemClone object are specified.
SystemClones.CICSB
{
factor=1.0;
maxServers=5;
health=1;
}
Section 14: The attributes of the CICSC SystemClone object are specified.
SystemClones.CICSC
{
factor=1.0;
maxServers=5;
health=1;
}
Section 15: The attributes of the Connection between CICSA and CICSB are
defined.
SystemClones.CICSA/Connections.B1
{
load=0.1;
inService=1;
my_other_half -> SystemClones.CICSB/Connections.B1;
}
Section 16: The attributes of the Connection between CICSA and CICSC are
defined.
{
load=0.1;
inService=1;
my_other_half -> SystemClones.CICSC/Connections.B1;
}
Section 17: The Node object is specified.

Nodes."wlmtest.acme.com"
{
}
66
Section 18: The SystemImages are assigned to the Nodes where they are to
run.
Nodes."wlmtest.acme.com/SystemImages.CICSA"
{
}
Nodes."wlmtest.acme.com/SystemImages.CICSB"
{
}
Nodes."wlmtest.acme.com/SystemImages.CICSC"
{
}
Section 19: The ResourceModel objects and ApplicationModel object are

predeclared.
LocalProgramModels.CALLED
{
load=0.25;
dynamic="yes";
configured_on ->
{
SystemModels.TYPE2,
};
}
LocalTransactionModels.WLMT
{
load=0.25;
configured_on ->
{
SystemModels.TYPE2
};
}
ApplicationsModels.Appl1
{
load=0.25;
configured_on->
{
SystemModels.TYPE2
};
}
Section 20: The cpx1 Plex definition is completed with the closing brace ( } ).
}
67
68

This section discusses how to use and maintain your CICS WLM environment.
Stopping a WAP
The process for starting a Workload Management Application Program cache
(WAP) was discussed in Chapter 6, Starting CICS WLM for the first time, on page
39. This section discusses how to stop a WAP.
To stop a WAP:
cicswlm stop wap wap_name
You can check whether the WAP has terminated by using the command cicswlm
list. If the WAP has not terminated, force its termination by using the cicswlm
purge wap command.
Stopping a WCM
The process for starting a Workload Management Cache Manager (WCM) was
discussed in Chapter 6, Starting CICS WLM for the first time, on page 39. This
section discusses how to stop a WCM.
To stop a WCM:
1. Authenticate as the user cicssm on the machine that contains the WCM that is
to be stopped.
cicswlm stop wcm wap_name
You can check for the presence of the WCM by issuing the command cicswlm list.
If the WCM has not stopped, force its termination by using the command cicswlm
purge wcm wap_name.
The effects of stopping and starting components

When CICS WLM has successfully routed work, it can continue to route requests
provided that the WCM cache remains in existence, even when the WAP and WCM
have been closed down. The cache can become empty or disappear for many
reasons, for example:
v The machine is rebooted.
v A cicswlm clean wlm command has been issued.
v The cache is removed in some other way.
In this condition, CICS WLM cannot accept routing requests for new resources
(programs or transactions). This limitation occurs because the holder of that
information, the WAP, is not currently active. Both the WAP and WCM must be
active, and the current configuration must be loaded, for details about new
resources to be loaded into the WCM cache.
69
It is important to understand the effects of various operations on the ability to route

work. Consider the following condition: Routing is successfully taking place. The
WCM is accidentally shutdown. The WCM is restarted, but the current configuration
is not known, so it cannot be loaded. The WCM is restarted in an attempt to correct
the problem. However, the effect of these actions is to clear the WCM cache.
Workload management stops for any CICS system that is accessing that WCM
cache. This effect is not desired. It is more desirable to allow the WCM to remain
shutdown. The following sections show the effects of various operations on the
WCM cache. The focus is on the WCM cache, because workload management
cannot occur without the availability of data.
Starting the WCM, condition 1:
The WAP and WCM have been started at some previous time. Routing
requests have been successfully issued. Then, the WAP and WCM are
closed down. Restarting the WCM causes the WCM cache contents to be
cleared, and no data is available on which routing decisions can be made.
Workload management does not occur. Requests for resources that are
intended to be routed by workload management are routed to the default
CICS system that is specified in the resource definition (RemoteSysId in the
relevant Program Definition (PD) or Transaction Definition (TD) stanza
entry). To repopulate the WCM cache, it is necessary to ensure that the
WAP is active and a valid configuration is loaded.
Starting the WAP, condition 2:
The WAP and WCM have been started at some point in the past. Routing
requests have been successfully issued. Then, the WAP and WCM are
shutdown. Starting the WAP has no effect on the WCM cache because the
WCM that owns the WCM cache is not started. However, starting the WCM
at this point causes the WCM cache to be emptied. To repopulate the WCM
cache, it is necessary to ensure that the WAP is active and a valid
configuration is loaded. Then, the first request for workload management
causes the data to be loaded into the WCM cache. Note that loading or
reloading a configuration file into the WAP clears all values in the WCM
cache; accumulated scores and routing courts are lost.
Listing active components

It is possible to list the currently active CICS WLM components on a machine by
using the cicswlm list command. This command displays any active WAP, WCM,
or HMON components. The command does not show any active Routing Monitors.
To use the cicswlm list command:
cicswlm list
The list of active CICS WLM components is displayed.
Cleaning up CICS WLM resources

This section discusses problem-solving techniques and maintenance of CICS WLM.
Specifically, the WAP and WCM caches can be emptied, and the WLM processes
can be purged. Scheduled housekeeping procedures are also discussed.
70
Emptying CICS WLM resources

To remove all the working files that are associated with CICS WLM:
1. Ensure that no routing activity is occurring.
2. Close all routing points by closing all CICS regions and CICS External Call
Interface (ECI) and External Presentation Interface (EPI) clients that are using
workload management.
cicswlm stop all
4. Verify that all components of CICS WLM have stopped. Issue the command:
ps -ef | grep bhg
5. Examine the command output to ensure that no active process is listed other
than the grep command.
cicswlm clean wlm
7. Verify that all /tmp/bhg.* files have been removed.

8. Issue the following Open Systems command to display the status of
interprocess communication facilities:
ipcs
Examine the command output to ensure no shared storage is owned by cicssm

or any semaphores.
9. If any shared storage is owned by cicssm or any semaphores, and the mode of
the resource has the leading character D, a process is still using this resource.
Find the process and stop it to release the resource.
Purging CICS WLM components

A CICS WLM component can fail to stop when a cicswlm stop command is issued.
In such a case, a more forceful command, the cicswlm purge command, is
required. This command removes the component. Following the use of the cicswlm
purge command, restart the purged component by using the cicswlm start
command.
Use the cicswlm purge command to purge a named component.
To stop a particular component, issue the cicswlm purge command:
1. Authenticate as the user cicssm on the required machine.
cicswlm purge <component_name>
Alternatively, to purge all currently running CICS WLM components on the machine
on which the command is issued:
1. Authenticate as the user cicssm on the required machine.
cicswlm purge
71
Scheduled housekeeping procedures

Scheduled housekeeping is recommended to remove the files that are created by
CICS WLM when the CICS application server terminates. Over a period of time, a
number of redundant files can accumulate on the disk.
The affected files have names of the following form:
v /var/cicssm/log/dpl.<hostname>.<identifier>.<cicsas_process_number>.trc
v /var/cicssm/log/dtr.<hostname>.<identifier>.<cicsas_process_number>.trc
v /tmp/bhg.dpl.<cicsas_process_number>.skt
Remove old versions of these files on a regular basis by using a scheduled batch
job. These files consume inodes within the file system. The number of these files
depends on factors such as:
v The number of CICS application servers
v The rate at which CICS application servers are created
v The rate at which a workload managed CICS system is recycled
Note: Removing files that are associated with a currently running CICS application
server prevents CICS WLM from handling any further requests that are
issued on that CICS application server.
72
|
|
|
|
|
|
This chapter introduces a Workload Management (WLM) configuration tool,

cicswlmcfg which can be used to quickly create and modify a WLM configuration
file. The chapter also explains the usage of the WLM configuration tool with
appropriate examples.
Following points briefly summarize what the tool can and cannot do:
|
|
|
|
|
cicswlmcfg can be used to:

v Create WLM or WAP configuration file
v Add, delete or modify any WLM configuration objects to/from the file
v Verify the WLM configuration
v List or display the WLM configuration
|
|
However, cicswlmcfg cannot:

v Load the WLM configuration file into WAP memory
v Add, delete or modify any objects in the WAP memory
|
|
|
You must make the necessary changes in the WLM configuration file using the
cicswlmcfg command and then load it into the WAP memory using the cicswlm
load command.
|
|
|
|
cicswlmcfg consists of the following parts:

v Command name
Object type
Object name
Option list
Attribute list
|
|
v
v
v
v
cicswlmcfg syntax is as follows:
|
|
cicswlmcfg [-v] command_name object_type {object_name|all} [option list]

[attribute list]
|
|
|
|
|
cicswlmcfg is associated with a set of commands and object types. Table 10 lists
the complete set of cicswlmcfg supported object types and compatible commands
to manipulate any new or existing WLM configuration. The set of commands are:
create, add, delete, modify, verify and list. The Table also gives the description of
all the object types.
Table 10. Relationship between object types and commands in cicswlmcfg
Compatible commands for the object type
Object_type Description
create add
delete
modify verify
list
|
|
wapdb
A wap configuration file

with extension (.cicssm)
Yes
No
Yes
No
No
No
wap
A wap definition in wapdb Yes
No
No
No
No
No
|
|
plexdb
WLM Configuration file

(.cfg)
No
Yes
No
Yes
No
Yes
73
Table 10. Relationship between object types and commands in cicswlmcfg (continued)
Compatible commands for the object type
Object_type Description
create add
delete
modify verify
list
|
|
plex
A Plex object within

plexdb
Yes
No
Yes
Yes
No
Yes
|
|
group
A SystemModel object in
the plex
Yes
No
Yes
Yes
No
No
|
|
|
region
A SystemClone object in
the plex or just a region
name
No
Yes
Yes
Yes
No
No
|
|
|
|
connection
A connection object with No

which two regions can
communicate. Basically it
a CD entry from COR
Yes
Yes
Yes
No
No
|
|
program
Program object, basically No

it is a PD entry
Yes
Yes
Yes
No
No
|
|
|
transaction
Transaction object,
basically it is a TD entry
Yes
Yes
Yes
No
No
|
|
From Table 10 on page 73 it is clear that you cannot create an object type such as
region or add an object type such as plexdb and so on.
Availability of cicswlmcfg on different platforms.
||
AIX
|
|
No
HP-UX
Sun Solaris
Windows
|
|
|
|
Table 11 shows the list of all options that cicswlmcfg supports. The -X, -f, -v
options do not accept any option arguments while the others do. If a mandatory
option is missing, the command fails. In such a case, the specified configuration file
will be intact and the command returns an error-code to the invoking shell.
Table 11. Options and their meaning
Option
Meaning
-d
Configuration file name (without its extension .cfg )
-l (lower case L)
Location of the configuration file
-p
Plex name
-g
Group name
-h
Host name
-r
Region name
-R
Remote region name
-S
Remote connection name (sysid)
-P
WAP port number
-X
List output requested in XML format
-f
Delete forcefully, else you will be prompted to delete
|
|
-v
Verbose for detail background processing
74
|
|
|
|
|
|
|
Return codes
cicswlmcfg can be used in script programming and can return a unique
return code to the caller. If successful, the command returns 0 and in case
of an error it returns a nonzero number. Table 16 on page 88 explains the
possible return codes and their meaning.
Creating a typical WLM configuration
|
|
This section explains the steps involved in creating a typical WLM configuration and
also includes an example of a WLM configuration.
|
|
|
|
|
|
|
|
To create a typical WLM configuration, complete the following steps:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1. Create a plexdb, by specifying WLM configuration, without its file extension. An

existing configuration file can be used but a duplicate plex will not be permitted.
2.
3.
4.
5.
6.
7.
Create a plex in plexdb.

Create one or more groups under plex.
Add one or more regions under plex by assigning a group and a host name.
Add the respective connections.
Add programs.
Add transactions.
An example of a WLM configuration for a typical scenario is shown in Figure 6 on

page 76. To create this scenario, complete the following steps:
1. Create a plex called plex1 which has four regions REGCOR, REGION01,
REGION02 and REGION03.
2. Assume there is a program called PROGRAM1 and a transaction called TRNA;
both available in the regions REGION01, REGION02 and REGION03. Let
REGCOR act as the Client Owning Region (COR) and the remaining regions as
Application Owning Region (AOR).
3. Hence, create two groups GROUP1 and GROUP2. Place the region REGCOR
into the group GROUP1 and the remaining regions into the group GROUP2.
4. Finally, add three connections C001, C002, C003 to client region REGCOR to
communicate to the application regions REGION01, REGION02 and REGION03
respectively; and let the regions REGCOR and REGION03 reside in a system
called host1.xyz.com and the other regions in another system called
host2.xyz.com.
75
|
PROGRAM1
Group1
TRN1
Group2
REGAOR01
C001
host2.xyz.com
REGCOR
C002
REGAOR02
C003
REGAOR03
Relationships
host1.xyz.com
Connections
|
| Figure 6. The WLM configuration file cfgdb1 (the absolute file name is /var/cicssm/repos/cfgdb1.cfg)
|
To generate a configuration file that simulates the scenario in Figure 6, issue the
|
following commands:
|
cicswlmcfg create plexdb cfgdb1
|
|
cicswlmcfg create plex plex1 d cfgdb1
|
|
cicswlmcfg create group GROUP1 p plex1 d cfgdb1
|
cicswlmcfg create group GROUP2 p plex1 d cfgdb1
|
|
cicswlmcfg add region REGCOR g GROUP1 h host1.xyz.com p plex1 d cfgdb1
|
|
cicswlmcfg add region REGION01 g GROUP2 h host2.xyz.com p plex1 d cfgdb1
|
|
|
|
cicswlmcfg add connection C001 r REGCOR R REGION01 S CICA p plex1 d cfgdb1
|
|
|
|
cicswlmcfg add program PROGRAM1 g GROUP2 p plex1 d cfgdb1
|
cicswlmcfg add transaction TRNA g GROUP2 p plex1 d cfgdb1
|
The commands mentioned above generate a configuration file cfgdb1.cfg under the
default directory /var/cicssm/repos, which can be overridden by the -l option. A
complete listing of the cfgdb1.cfg file can be found in Appendix F, The generated
WLM configuration file, on page 121.
|
|
|
|
|
|
Configuration commands
The following sections explain each of the commands in detail:
76
create - Creates object types
||
AIX
|
|
HP-UX
Sun Solaris
Windows
Creates one of the five object types: plexdb, plex, group, wapdb or wap.
Syntax
cicswlmcfg [-v] create plexdb plex_db_name [-l location]
cicswlmcfg [-v] create plex plex_name d plex_db_name [-l location]
|
|
cicswlmcfg [-v] create plex plex_name [plex_attribute1=plex_value1]

[plex_attribute2=plex_value2]...[l location]
|
|
cicswlmcfg [-v] create group group_name -p plex_name d plex_db_name [-l

location]
cicswlmcfg [v] create wapdb wapdb_name [-l location]
|
|
cicswlmcfg [v] create wap wap_name -d wapdb_name -h host_name -P port [-l

location]
Description
|
|
|
|
|
The create command creates the topmost WLM Plex object. However, this
command can be used to change the WLM topmost Plex attributes along with the
create command. If no values are stated, then the default attribute values are taken.
To change one or more attribute values without creating a plex, the modify
command can be used.
|
|
|
|
|
|
|
Create a plexdb, which is a text file with an extension .cfg, and some information as
its contents. After the plexdb is created, one or more plex objects can be created.
The command does not permit the creation of duplicate plex entries. It is mandatory
to specify created instances of the plex and plexdb for subsequent commands using
p and d options respectively. However, the db location can be avoided in which
case the default db location /var/cicssm/repos is taken. No other value is taken
from any environment variables.
|
|
|
|
|
|
|
|
Examples
Note: A configuration file called /var/cicssm/repos/plex01.cfg will be created.

4. To create a plexdb, plexdb01 under /tmp/testdir1, enter:
|
|
1. To create a wapdb, wapdb01 under /var/cicssm/repos, enter:

cicswlmcfg create wapdb wapdb01
2. To create a wap, wap01 in wapdb, wapdb01 /var/cicssm/repos, on host

server1.com and port 6234, enter:
cicswlmcfg create wap wap01 -d
wapdb01 -h server1.com -P 6234
3. To create a plexdb, plexdb01 under /var/cicssm/repos, enter:

cicswlmcfg create plexdb
plexdb01
plexdb01 l /tmp/testdir1
77
|
|
|
Note: A configuration file called /tmp/testdir1/plex01.cfg will be created.

5. To create a plexdb, plexdb02 under testdir1 in the current directory, enter:
|
|
|
|
Note: A configuration file called testdir1/plexdb02.cfg will be created in the

current directory.
6. To create a group, TYPE1 under the plex, plex01, enter:
|
|
Note: It is mandatory to specify the plex name, even though there is only one
plex. The default db location is assumed here (/var/cicssm/repos).
|
|
plexdb02 l testdir1
cicswlmcfg create group TYPE1 p plex01
add - Adds object types
|
|
Adds new object types such as region, connection, program, and transaction into an
existing plex under an existing plexdb.
Syntax
|
|
cicswlmcfg [-v] add region region_name -h host_name -g group_name -p

plex_name -d plex_db_name [-l location] [[region_attribute1=region_value1] ...]
|
|
cicswlmcfg [-v] add program program_name -g group_name -p plex_name -d

plex_db_name [-l location] [[program_attribute1=program_value1]...]
|
|
cicswlmcfg [-v] add transaction transaction_name -g group_name -p plex_name

-d plex_db_name [-l location] [[transaction_attribute1=transaction_value1]...]
|
|
|
cicswlmcfg [-v] add connection connection_name -r region_name -R

remote_region_name -S remote_connection_name -d plex_db_name [-l location]
[connection_attribute1=connection_value1]
Description
|
|
|
|
|
The add command adds new object types such as region, connection, program and
transaction into an existing plex under an existing plexdb. If the command
succeeds, the changes will take place, else an error will occur. Duplicate entries
cannot be added in a given plex. Also, it is mandatory that the host_name should
match with the output of the system command hostname.
|
|
|
|
|
Note that the g option is mandatory for creating new object types such as region,
connection, program and transaction. However, a region cannot be in more than
one group while a transaction and a program can be in many groups. Examples 5
and 6 in the following section show how to add more groups into program and
transaction objects.
|
|
|
Examples
|
|
|
Note: It is mandatory to specify the four options, without which the command
fails. The host name should match with the output of the system
command hostname.
2. To add a connection, C001 from a region CICSA, enter:
1. To add a region, CICSA into a plex, plex01, enter:

cicswlmcfg add region CICSA h ampere.in.ibm.com g TYPE1 -p plex01-d testdb1
78
|
|
|
|
|
|
|
|
|
|
|
|
|
|
cicswlmcfg add connection C001 -r CICSA R CICS0001 S CICA -p plex01-d

testdb1 inService=1
3. To add a program, PROGRAM1 into plex01, enter:

cicswlmcfg add program PROGRAM1 g TYPE2
-p plex01-d testdb1
4. To add a transaction, TRN1 into plex01, enter:

cicswlmcfg add transaction TRN1 g TYPE2
-p plex01-d testdb1 load=0.25
5. To add a transaction, TRN1 into the group, TYPE3, enter:

-p plex01-d testdb1
6. To add a transaction, TRN1 into the group, TYPE4, enter:

-p plex01-d testdb1
Note: After executing the last three commands, the transaction TRN1 will
belong to the groups TYPE2, TYPE3 and TYPE4.
delete - Deletes an object
||
AIX
|
|
HP-UX
Sun Solaris
Windows
Deletes an object completely or partially from the configuration file.
Windows
Syntax
cicswlmcfg [-v] delete plexdb plex_dbname [-f ] [-l location]
cicswlmcfg [-v] delete plex plex_name [-f ] -d plex_db_name [-l location]
|
|
cicswlmcfg [-v] delete group group_name -p plex_name [-f ] -d plex_db_name [-l

location]
|
|
cicswlmcfg [-v] delete region region_name -p plex_name [-g group_name] [-f ] -d

plex_db_name [-l location]
|
|
cicswlmcfg [-v] delete connection connection_name [-r region_name] -p

plex_name [-f ] -d plex_db_name [-l location]
|
|
cicswlmcfg [-v] delete program program_name -p plex_name [-g group_name] [-f

] -d plex_db_name [-l location]
|
|
cicswlmcfg [-v] delete transaction transaction_name -p plex_name [-g

group_name] [-f ] -d plex_db_name [-l location]
Description
|
|
|
|
|
|
|
The delete command deletes an object completely or partially. It always goes into
the interactive mode by asking, Are you sure you want to destroy the plex
plex_name?, and which can be bypassed with f option. If -g option is omitted,
the command deletes the respective object completely or else the object is deleted
from the respective group. The r option is mandatory to delete a connection as it
resides with a region object. Note that whenever a delete is performed, the
respective object and its references will be deleted.
79
|
|
|
|
The objects such as region, transaction and program must be in a group. If that
group is deleted, then the objects related to the group become stray objects and
WLM will ignore those objects. You must then assign another group to those stray
objects.
Examples
|
|
1. To delete plexdb, plexdb01 under default directory /var/cicssm/repos, enter:
|
|
|
|
Note: This command deletes the entire db file. All the contents cannot be
retrieved.
2. To delete plex, plex01 under /var/cicssm/repos directory, enter:
cicswlmcfg delete plexdb
cicswlmcfg delete plex plex01 -d
plexdb01 f
Note: This command deletes the specified plex object completely. Neither the
deleted plex object nor its sub objects can be retrieved.
|
|
|
|
3. To delete group, TYPE01 under the plex, plex01 in the db plexdb01, enter:
cicswlmcfg delete plex plex01 -d plexdb01 f
Note:
|
|
|
|
|
|
|
|
|
|
|
|
v This command deletes the specified group object and its reference
from the specified plex object completely. If you delete a group and if
a region or a program or a transaction belongs to that group, then that
region or program or transaction will virtually go out of the plex and
become a stray object with that plex. WLM will not take an account on
them. It is your responsibility to add those stray objects into respective
groups.
v If the db file is under a different directory, the user may specify it with
l option.
4. To delete the region CICSA from the plex, plex01 , enter:
cicswlmcfg [-v] delete region CICSA p
plex01 -d
plexdb01 f
Note: This command deletes the region CICSA and also its sub connection
objects if any. That is, if you delete a region which has already been
designated as COR, then all of its connection objects will be deleted from
the plex object.
5. To delete a connection C001 from a region CICSA, enter:
|
|
|
|
|
|
|
|
|
cicswlmcfg [-v] delete connection C001 r CICSA p
plex01 -d
plexdb01 f
6. To delete the region CICSA from the group TYPE01 under the plex plex01 ,
enter:
cicswlmcfg delete region CICSA -g TYPE01 -p
plex01 -d
plexdb01 f
Note: This command deletes the group reference of TYPE01 from the region
CICSA. The region object will be available in the specified plex, but it will
not belong to any group, as a region object cannot be in more than one
group.
Similarly, you can delete group reference from transaction or program objects.
|
|
|
|
|
|
|
plexdb01 f
modify - Modifies attributes of existing object
||
AIX
80
HP-UX
Sun Solaris
Windows
|
|
Modifies the attribute values of the existing object.
Syntax
|
|
cicswlmcfg [-v] modify plex plex_name -d plex_db_name [-l location]

[plex_attribute1=plex_value1] [plex_attribute2=plex_value2]...
|
|
cicswlmcfg [-v] modify region region_name -p plex_name -d plex_db_name [-l

location] [region_attribute1=region_value1] [region_attribute2=region_value2]...
|
|
|
cicswlmcfg [-v] modify connection connection_name -r region_name -p

plex_name -d plex_db_name [-l location ] [connect_attribute1=connect_value1]
[connect_attribute2=connect_value2]...
|
|
|
cicswlmcfg [-v] modify program program_name p plex_name -d plex_db_name

[-l location] [program_attribute1=program_value1]
[program_attribute2=program_value2]...
|
|
|
cicswlmcfg [-v] modify transaction transaction_name -p plex_name -d

plex_db_name [-l location] [transation_attribute1=transaction_value1]
[transaction_attribute2=transaction_value2]...
Description
|
|
|
|
|
|
|
The modify command modifies the attribute values of the existing object. Tables
12, 13, 14 and 15 show all the available attributes of the respective objects. Note
that the object group does not have any attributes. However it is not possible to
modify an object name. You must delete and create the same object with a different
name. The set of all attributes for each object mentioned in Table 10 can be found
in the Tables 12, 13, 14 and 15. It is not possible to modify the objects, plexdb,
wapdb, wap, and group.
|
|
|
|
|
|
|
|
|
Examples
1. To modify some of the plex attributes, enter:
cicswlmcfg modify plex plex01 retry_limit=3
wcm_retry_limit_1=4 -d plexdb01
2. To modify some of the region attributes (to increase the application servers
count), enter:
cicswlmcfg modify region CICSA -p plex01 -d plexdb01 maxServers=77
3. To modify some of the connection attributes (to disable a region), enter:

cicswlmcfg modify connection C001 r CICSA -p plex01 -d plexdb01 inService=0
Note: Now no routing will happen to the region to which this connection points
to. Setting inService=1 makes that region to be active within the plex.
|
|
|
|
verify - Checks for syntax errors
||
AIX
|
|
Checks for any syntax errors in the configuration file.
HP-UX
Sun Solaris
Windows
81
Syntax
cicswlmcfg [-v] verify plexdb plexdb_name [-l location]
Description
|
|
|
|
|
After you successfully create a WLM configuration file, it must be verified prior to its
usage. The verification command uses the backend WLM command cicswlm
verify. Note that the verify command will not issue any warning such as this region
does not belong to any group and so on. The cicswlm command always looks for
the configuration file to be in the /var/cicssm/wlm directory.
|
|
|
However, cicswlmcfg expects the WLM configuration file to have an extension .cfg
and in the command line mention the configuration file without this extension and
location of the file can be mentioned in l option.
Examples
|
|
To verify a WLM configuration, plexdb01.cfg under /var/cicssm/repos, enter:
|
|
cicswlmcfg verify plexdb plexdb01
list - Lists available configuration files
||
AIX
|
|
HP-UX
Sun Solaris
Windows
Helps to list available configuration files as well as the plex information.
Syntax
cicswlmcfg [-v] list plexdb all [-l location]
cicswlmcfg [-v] list wapdb all [-l location]
cicswlmcfg [-v] list plex {all| plex_name} d plexdb_name [-l location]
Description
|
|
|
|
The list command finds the available configuration files. You can list the WAP
related configuration files by specifying the object wapdb and WLM related
configuration files by specifying the object plexdb. You can also list the contents of
a given plex by specifying the object as plex.
|
|
|
Examples
|
|
|
|
|
Note: It lists all the *.cicssm file under the respective location.
2. To list all existing WAP configurations under /tmp/test1, enter:
1. To list all existing WAP configurations, enter:

cicswlmcfg v list wapdb all
cicswlmcfg v list wapdb all l /tmp/test1
3. To list all existing WLM configurations under /tmp/test1, enter:

cicswlmcfg v list plexdb all -l /tmp/test1
82
|
|
|
|
|
|
|
|
Note: It lists all the *.cfg file under the respective location.
4. To list the contents of all plexes in a plexdb, plexdb01 under /tmp/test1, enter:
cicswlmcfg [-v] list plex all d plexdb01 -l location
5. To list the contents of a plex plex01 in a plexdb, plexdb01 under /tmp/test1,

enter:
cicswlmcfg [-v] list plex plex01
d plexdb01 -l location
Configuring WLM with IBM TXSeries Administration Console
|
|
|
|
|
|
The TXSeries Administration Console can be used to create and modify the WLM
configuration file. The Web interface available compliments the cicswlmcfg
command explained earlier in the chapter. It can be used to:
v Create or delete plex databases
v Create, modify or delete plexes, groups, transactions, connections and programs
v View the attributes of all the objects
|
|
|
|
If the operating system on which TXSeries is installed supports WLM, a separate

WLM link will appear in the left navigation pane as shown in Figure 7.
|
|
|
|
Figure 7. IBM TXSeries Administration Console WLM Configuration
To configure a WLM plex database, complete the following steps:
83
Expand WLM and click Plex Databases. A list of all the available plex databases in
the default plex database directory along with the respective plexes are displayed in
the WLM Plex Databases pane as shown in Figure 8.
|
|
|
|
|
|
| Figure 8. IBM TXSeries Administration Console Plex Database list
|
Click the name of the Plex object that you want to configure. All the objects
|
available in the plex are displayed in the work area as shown in Figure 9 on page
|
85.
|
|
84
|
|
|
|
|
|
|
Figure 9. IBM TXSeries Administration Console Plex Objects
To modify an object, click the name and edit the list of values of the attributes that
you want to change and click the Submit button.
The Plex Attributes
|
|
|
|
The Tables in this section explain the set of all attributes that will appear in a typical
WLM configuration. Table 12 shows the complete set of plex attributes, their type
and default values. All these attributes can be modified using a modify command or
their values be overridden while creating a plex.
Table 12. Attributes and defaults for a Plex configuration
Attribute
Default
Description
|
|
load_limit
600
Maximum load that is used in a WLM

algorithm
|
|
connection_scale
Parameter that is used in a WLM

algorithm
|
|
same_limit_1
Number of entries for short-term

performance
|
|
same_limit_2
10
Number of entries for long-term

performance
same_adjustment
0.1
Same system bias
|
|
same_scale_1
Importance of last systems short-term

performance
85
Table 12. Attributes and defaults for a Plex configuration (continued)
Attribute
Default
Description
|
|
same_scale_2
Importance of last systems long-term

performance
known_adjustment
0.05
Bias towards previously-used system
|
|
known_scale_1

short-term performance
|
|
known_scale_2

long-term performance
normalise_scale
Used to round scores
equal_delta
Margin for resolving equal scores
health_adjustment_1
health_adjustment_2
10
health_adjustment_3
100
|
|
health_adjustment_4
1000
Bias toward systems for health=4 (Not

supported)
|
|
health_adjustment_5
10000
Bias toward systems for health=5 (Not

supported)
health_timeout
120
Delay before restarting a failed system
|
|
session_scale_1
1.0
The scale for sessions from EPI,

cicsterm, cicsteld (Not supported)
|
|
session_scale_2
2.0
The scale for sessions from ECI, DPL,

DTR
|
|
load_scale_1
0.0
The scale for sessions from EPI,

cicsterm, cicsteld (Not supported)
|
|
load_scale_2
1.0
The scale for sessions from ECI, DPL,

DTR
|
|
score_limit
5,000
Maximum score that is allowable for a

system
|
|
retry_limit
Number of times to retry a system before

trying another system
|
|
|
reselection_limit
Number of systems to reselect before

giving up, when failure recovery is in
operation
|
|
wcm_resend_timeout
Timeout for messages from WCM to

WAP
|
|
wcm_retry_timeout
10
Timeout for reconnection attempts from

WCM to WAP
|
|
wcm_retry_limit_1

initially
|
|
wcm_retry_limit_2

following a communication failure
|
|
wcm_fail_timeout
600
Time in seconds to lock out a system

that has had a failure
|
|
|
autoinstall_load
Increase in response time because of

ECI autoinstall
86
The Region Attributes
|
|
|
Table 13 shows the complete set of region attributes, their type and default values.
All these attributes can be modified through a modify command or their values be
overridden while adding a region.
Table 13. Attributes and defaults for a region object
Attribute
Default
Description
|
|
|
|
factor
A measure of the systems

capacity to do work relative
to the other systems in the
WLM environment.
|
|
|
maxServers
The maximum number of

application servers that is
defined for the CICS system.
|
|
|
|
|
health
The state of the systems

health:
v 1= Excellent
v 3= Very poor or offline
The Connection Attributes
|
|
|
Table 14 shows the complete set of region attributes, their type and default values.
All these attributes can be modified through a modify command or their values be
overridden while adding a connection.
Table 14. Attributes and defaults for a connection object
Attribute
Default
Description
|
|
|
|
|
|
|
load
0.1
The weighting factor that is

applied to the object that is
using this Connection.
Increasing this number
biases the WLM algorithm
away from the connected
system.
|
|
|
|
|
|
|
|
|
|
|
|
|
inService
A switch to specify whether

this Connection object is
currently enabled (1) or not
(0). Note that both
Connections must be
inService for routing to occur
between two systems. The
user can set this to 0 to block
the requests to that region.
Setting to 1 allows WLM to
send more requests to that
region.
|
|
|
|
The Program/Transaction Attributes

Table 15 on page 88 shows the complete set of region attributes, their type and
default values. All these attributes can be modified through a modify command or
their values be overridden while adding a program/transaction.
87
Table 15. Attributes and defaults for a program/transaction object
Attribute
Default
Description
|
|
|
|
|
|
|
|
|
load
0.25
An estimate (in response

time seconds) for the
duration of a request of this
resource, on a system with
the attribute value of
factor=1.0. Transaction
response times vary from
instance to instance, so this
is only an estimated figure.
|
|
|
|
|
dynamic
no
Programs only- a switch

(yes/no) to specify if this
program can be dynamically
routed.
|
|
cicswlmcfg return codes
|
|
|
The Table 16 shows the possible return codes from this tool. This tool can be used
in scripts programming and the return code can be used to find the cause of the
tool failure.
Table 16. cicswlmcfg return codes and their meaning
Exit code
Description
Command successful
|
|
Invalid command: It should be any one of create, delete, list, verify, add,
modify
Invalid object: It should be any one of wap, wapdb and so on.
|
|
Object argument is missing, an argument has to be passed to this object

type.
all is a reserved word and it is mandatory for listing plexdb or wapdb
Invalid option or the tool does not understand this option.
|
|
The user has specified an invalid option argument, probably missing

argument for the previous option.
Invalid attribute or the tool does not understand this attribute.
|
|
The user has specified an invalid attribute value; for example dynamic
attribute takes yes or no and so on.
Valid option but repeatedly used.
10
Valid option but used in the wrong place.
11
Valid attribute but used in the wrong place.
12
Valid attribute but repeatedly used.
13
The user has not specified a valid attribute value. Attribute value missing.
14
The user has specified an existing db name for create db command.
15
Could not locate the specified db_name under the db_location.
16
The user has not specified the db_name.
17
Could not locate the specified db_location.
18
The user has not specified the db_location.
19
The region already exists in the back end, no more duplicates.
88
Table 16. cicswlmcfg return codes and their meaning (continued)
Exit code
Description
20
The specified region does not belong to the specified group.
21
The specified region not found in the configuration file.
22
The region declaration not found in the configuration file.
23
The user has not specified the region name in the command.
24
The specified remote region was not found in the configuration file.
25
The user has not specified the remote region name in the command
26
The specified remote connection not found in the configuration file
|
|
27
The user has not specified the remote connection name of remote region in
the command.
28
The connection already exists in the back end, no more duplicates.
29
The specified connection not found in the configuration file.
30
The user has not specified the connection name in the command.
31
The group already exists in the back end, no more duplicates.
32
The specified group not found in the configuration file.
33
The user has not specified the group name in the command.
34
The program already exists in the back end, no more duplicates.
35
The specified program not found in the configuration file.
36
The specified program not found in the specified group.
37
The user has not specified the program name in the command.
38
The transaction already exists in the back end, no more duplicates.
39
The specified transaction not found in the configuration file
40
The specified program not found in the specified group.
41
The user has not specified the transaction name in the command.
42
The specified host not found in the configuration file.
43
The user has not specified the host name in the command.
44
Not used (reserved for future)
45
The user has not specified the port in the command.
46
The plex already exists in the back end, no more duplicates.
47
Plex not found in the back end.
48
The user has not specified the plex in the command.
49
The WLM command bhgwlmload not found.
50
The WLM dictionary not found.
51
The WLM dictionary corrupted.
52
The region or program or transaction does not belong to any group.
53
The input configuration file has an unexpected string or character.
|
|
54
The output configuration file has an unexpected string or character,

generated configuration file.
|
|
55
The plex object name has an invalid character, it should be

[alpha][alphanumeric]*
56
The configuration file is invalid, as it may not have correct signature.
89
Table 16. cicswlmcfg return codes and their meaning (continued)
Exit code
Description
|
|
57
The specified region does belong to the another group, hence cannot be
added into a specified group.
58
The valid option was unable to find its respective argument value.
|
|
59
The user has specified no to the delete command query. The delete
command was stopped.
60
The user attempts to set an attribute while listing or deleting an object.
61
The user has specified a region name with more that 8 characters.
62
The user has specified a connection name with more that 4 characters.
63
The user has specified a transaction name with more that 4 characters.
64
The user has specified a program name with more that 8 characters.
|
|
|
|
65
A generic exception, better to set the trace and resubmit the command for
further analysis.
90
Chapter 11. Adding resources to WLM

To add a new program or CICS system to an existing CICS WLM configuration, you
must perform several tasks:
v You must perform the necessary CICS configuration. You might have to add a
new application to an existing CICS system, or create a new CICS system on
which the application is to be located.
v You must ensure that connectivity is working correctly. The job of CICS WLM is
to tell a transaction or program where to run, based on the configuration
information that is supplied to it. It cannot correct configuration problems. For
example:
Ensure that the CICS system can be reached from the Client Owning Region
(COR).
Ensure that new programs or transactions are assigned to a default remote
CICS system, and that the applications run correctly against the CICS system.
Modify the Resource Definition (RD) in the COR to point to each of the
regions in which the application can run in turn (by changing the RemoteSysId
parameter of the RD), and ensure that the application runs correctly in those
regions (AORs).
v You must update the CICS WLM configuration to reflect the new CICS resources.
v You must load the CICS WLM caches with the updated information.
The following sections discuss how to add resources to a CICS WLM configuration
file and make those new definitions active. The first section describes how to add a
program; the second section describes how to add a new CICS system.
Adding a new program

The following steps show the tasks that you must do to add a new program to CICS
WLM and bring the change into effect. For example, a new program called newprog
is to be added to an existing AOR in the CICS WLM configuration called
/var/cicssm/repos/wlm.cfg. This program is being added to the CICS WLM
configuration that is supplied in Sample configuration file (wlm.cfg) on page 29.
To add a new program:
1. Add the application program to the required AORs, and add the CICS Program
Definition (PD).
2. Add a PD in the COR, assigning a default AOR for the CICS system to which
requests are to be routed. In CICS terms, this is a remote PD.
3. Authenticate as the user cicssm on the machine that contains the Workload
Management Application Program cache (WAP).
4. Edit the file /var/cicssm/repos/wlm.cfg:
a. Create the ResourceModel LocalProgramModels.newprog, and place it
adjacent to the other predeclarations of LocalProgramModels. This
statement is the predeclaration of newprog. Section 19 shows the code
example for the predeclaration of ResourceModel objects.
b. The following entry shows an example for newprog:
91
LocalProgramModels.newprog
{
load=0.25;
dynamic="yes";
You must ensure that the correct syntax is used for this statement, including
the mixed case, quotation marks (), and braces ({}). The load value
corresponds to the response time of the program. The value dynamic="yes"
is required in order to specify that the program is to be managed by CICS
WLM.
Save the file.
c. Issue the command:
d. Ensure that the configuration is verified without any errors.

e. Start the WAP and Workload Cache Manager (WCM), if they are not already
started.
f. Load the new configuration into the WAP cache. Issue the command:
Note: The new program does not appear in the WCM cache display until a
request has been issued to route that program from within the COR or
a CICS External Call Interface (ECI) or External Presentation Interface
(EPI) client.
Adding a new CICS system

The following steps show the tasks that you must do to add a new CICS system to
CICS WLM and bring the change into effect. The CICS system is being added to
the CICS WLM configuration file in Sample configuration file (wlm.cfg) on page 29.
It is named /var/cicssm/repos/wlm.cfg. Assume the following information for this
example:
v The new system is called CICSAOR3, which is an AOR on a Node called
machine4.acme.com.
v The COR uses the Connection name of AOR3 to access CICSAOR3.
v CICSAOR3 uses a Connection name of COR1 to access the COR.
v CICSAOR3 is another instance of the SystemModel AOR.
To add a new CICS system:
1. Create the CICS system.
2. Add all the necessary resources and applications, including the CICS
Communications Definition (CD) stanza entries. Ensure that CICS connectivity
works between regions; that is, that the AOR can be accessed from the COR.
3. Test from the COR to ensure that the applications work correctly.
4. Authenticate as the user cicssm on the machine that contains the WAP.
5. Edit the file /var/cicssm/repos/wlm.cfg:
a. Create the object SystemClones.CICSAOR3, and place it with the other
SystemClone definitions. Section 3 shows examples of predeclarations for
SystemClone objects.
92
b. Create the object SystemClones.CICSCOR/Connections.AOR3, and place it

with the predeclarations for the Connection objects for the Connection into
the COR to CICSAOR3. Section 4 shows examples of predeclarations for
these objects.
c. Create the object SystemClones.CICSAOR3/Connections.COR1, and place it
adjacent to the similar definitions. This predeclares the Connection in
CICSAOR3 to the COR. Section5 shows examples of predeclarations for
these objects.
d. Create the statement Nodes."machine4.acme.com"; and place it with the
code that declares the other nodes. This predeclares machine4.acme.com.
You must use the quotation marks () to enclose the details of the object
instance. Section 6 shows examples of predeclarations for these objects.
e. Create the statement Nodes."machine4.acme.com/SystemImages.CICSAOR3";
and place it with the other SystemImages declarations. This predeclares
which SystemImage is to be on machine4.acme.com. You must use the
quotation marks () to enclose the details of the object instance. Section 7
shows examples of predeclarations for these objects.
f. Modify the expansion of the SystemModels.AOR statement. Add a
SystemClones.CICSAOR3 statement. Section 10 shows examples of
predeclarations for these objects:
SystemModels.AOR
{
cloned_As ->
{
};
}
g. Add a definition to describe the CICS system CICSAOR3. To do this, add

the definition alongside the similar definitions. Section 12 and Section 13
show examples of predeclarations for similar objects. Section 13.01 shows
the predeclarations for this object:
{
factor=1.0;
maxservers=5;
health=1;
}
The factor attribute describes the processing speed of the machine on

which the CICS system is running relative to the other systems. It has a
default value of 1.0. No definite rules control how to determine this value.
The ratios are intended to indicate the relative processing capabilities of
the different machines in your configuration. For example, the SPECint
performance of a machine can possibly form the basis of your ratios. If
your configuration is based on the use of identical machines, set all the
ratios to 1.
The maxservers attribute describes the number of application servers with
which the CICS system is configured.
The health attribute describes the status of the CICS system. A value of 1
indicates that the CICS system is available; a value of 3 indicates that it is
not available.
h. You must define the Connection for the new CICS system from the COR.
The reverse Connection does not need to be defined to CICS WLM. Add
the following definition adjacent to the similar definitions. Section 14 and
93
Section 15 show examples of predeclarations for similar objects. Section

15.01 shows the predeclaration for this object:
{
load=0.1;
inservice=1;
}
i. You must define the Node on which the new CICS system is to be run. To
do this, add the following definition with those for the other Nodes. Section
16 shows the predeclaration for this object:
{
}
j. You must tell CICS WLM on which system the new CICS system is to run.
To do this, add the following statement with the similar definitions. Section
17 shows the predeclaration for these objects:
{
}
Notice that the LocalProgramModel objects that are to be configured on the

new CICS system have not been explicitly defined in the process for adding
the new CICS system. This is because LocalProgramModel definitions are
implicitly inherited from the system type. The new CICS system is of the
type AOR; therefore, it automatically has all the programs that are
configured on that SystemModel.
If all the programs that are defined on the existing SystemModel are not
desired on the new SystemModel, the new SystemModel must not be
derived from the existing one. A new SystemModel entry must be defined.
Ensure that the syntax of all statements is observed, including the mixed
case, quotation marks (), and braces ({}).
6. Issue the commands:
7. Ensure that the configuration is verified without any errors.

8. Start the WAP and WCM, if they are not already started.
9. Load the new configuration into the WAP cache. Issue the command:
10. Start the Routing Monitor and verify that the new CICS system is included in
the list of regions that is displayed in the monitor. After the monitor has started,
press Enter. CICSAOR3 is displayed on the list of available regions.
The new configuration is shown in A sample configuration of the WLM definition
with added resources on page 95. The added definitions are highlighted by the
indicator <== Added.
The example that is shown in A sample configuration of the WLM definition with
added resources on page 95 is partitioned by numbered section headings. These
headings are provided to make it easy to reference portions of the file throughout
the text. The actual file contains only the monospaced example text, without
numbered headings.
94
A sample configuration of the WLM definition with added resources

Section 1: The WLM Plex definition with added resources starts here.
The Plex is the highest definition level. It is defined with the name of the
cpx1. The name cpx1 is the default CICSplex name. If you use a different
Plex name, two variables must be included in the environment of the CICS
regions that are using Distributed Program Link (DPL) and Dynamic
Transaction Routing (DTR) user exits. See Before you start the CICS
WLM on page 39 for information about these variables. The added
resources are highlighted by the indicator: <== Added.
Plexes.cpx1
{

A SystemModel declaration is required for each type of region that exists in
the configuration. This configuration has two types: a Client Owning Region
(COR) and an Application Owning Region (AOR). This entry is a type
definition; it has no detail associated with it. (All Contents of the active
configuration for this Plex are predeclared.)
SystemModels.COR;
SystemModels.AOR;

A SystemClone object is defined for each region.
SystemClones.CICSCOR;
SystemClones.CICSAOR3; <== Added
predeclared.
connection to the AOR.
SystemClones.CICSCOR/Connections.AOR3; <== Added
Section 5: The Connection objects from each of the AORs back to the COR
are predeclared.
connection to the COR.
<== Added
Section 6: The machine names are predeclared as Node objects.

The name that is specified is the one that is obtained by using the fully
qualified host name, including the domain name; for example,
Nodes."machine4.acme.com"; <== Added

A SystemImage represents an instance of a CICS region on a particular
machine. It is important that the quotation marks () are used correctly.
95
Nodes."machine1.acme.com/SystemImages.CICSCOR";
Nodes."machine4.acme.com/SystemImages.CICSAOR3"; <== Added

LocalProgramModels.
The ResourceModel definitions represent the programs that are to be called
in the AORs. The entry of these definitions completes the predeclaration
requirements for the WLM.
LocalProgramModels.newprog;
<== Added
Section 9: The Relationship of the COR SystemModel to the SystemClone is

defined.
The object definitions for this Plex are started by relating the COR
SystemModel object and the SystemClone entry of CICSCOR.
SystemModels.COR
{
cloned_as -> SystemClones.CICSCOR;
}
Section 10: The Relationships of the AOR SystemModel object are defined.
The AOR SystemModel object is related to the three SystemClone objects
that are of the AOR type: CICSAOR1, CICSAOR2, and CICSAOR3. Notice
that three instances of the AOR SystemModel objects exist. Compare this
with the single instance of the COR SystemModel object.
SystemModels.AOR
{
cloned_as ->
{
SystemClones.CICSAOR2, <== Modified to add ","
SystemClones.CICSAOR3 <== Added
};
}
Section 11: The attributes of the CICSCOR SystemClone object are specified.
{
factor=1.0;
maxServers=10;
health=1;
}

specified.
{
factor=1.0;
maxServers=5;
health=3;
}
96
Section 13: The attributes of the CICSAOR2 SystemClone object are specified.
{
factor=1.0;
maxServers=5;
health=1;
}
Section 13.01: The attributes of the CICSAOR3 SystemClone object are

specified.
SystemClone object is located. This whole section is newly added from the
original code sample that is shown in Sample configuration file (wlm.cfg)
on page 29.
SystemClones.CICSAOR3 <== Added
{ <== Added
factor=1.0; <== Added
maxServers=5; <== Added
health=1; <== Added
installed_on -> Nodes."machine4.acme.com"; <== Added
} <== Added

CICSAOR1 are defined.
With the declaration for my_other_half, only one half of the Connection is
defined. The CICS WLM itself determines that a return Connection exists
from AOR1 to COR and from AOR2 to COR. The attributes of the
Connection between CICSCOR and CICSAOR1, known as AOR1, are
defined. The relationship is also declared to indicate that the two
Connection entries (AOR1 and COR) are a pair. (These entries start the
Connection declarations.)
{
load=0.1;
inService=1;
}

The relationship is also declared, to indicate that the two Connection entries
attributes and relationship for the other side of the Connection; that is the
automatically. (You can define it for completeness, if you want.)
{
load=0.1;
inService=1;
}
Section 15.01: Also, the attributes of the Connection between CICSCOR and
The relationship is also declared, to indicate that the two Connection entries
attributes and relationship for the other side of the Connection; that is the
97
automatically. (You can define it for completeness, if you want.) This whole
section is newly added from the original code sample that is shown in
Sample configuration file (wlm.cfg) on page 29.
SystemClones.CICSCOR/Connections.AOR3 <== Added
{ <== Added
load=0.1;
<== Added
inService=1;
<== Added
} <== Added
<== Added
Section 16: Each of the Node objects is specified.

{
}
{
}
{
}
<== Added
{
<== Added
}
<== Added
Section 17: The SystemImages are assigned to the Nodes where they are to
run.
Nodes."machine1.acme.com/SystemImages.CICSCOR"
{
}
{
}
{
}
{
<== Added
}
<== Added
<== Added

This example allows all attributes to default. Section 9 shows Plex attribute
definitions in the example system.
Section 19: The ResourceModel objects are predeclared.
The attributes of each of the routed applications are defined. Also, it is
necessary to specify the SystemClone objects on which these applications
programs are to be found. The possible values for the dynamic attribute
are yes and no. These values must be enclosed within quotation marks. A
value of yes indicates that the resource is eligible for workload
management. A value of no indicates that the resource is not eligible for
workload management. The added program newprog is shown here. (These
entries start the declaration of ResourceModel objects.)
{
load=0.7;
dynamic="yes";
}
{
load=0.5;
dynamic="yes";
98

}
{
load=0.9;
dynamic="yes";
}
LocalProgramModels.newprog <== Added
{
<== Added
load=0.25;
<== Added
dynamic="yes";
<== Added
configured_on -> SystemModels.AOR; <== Added
} <== Added
Section 20: The Plex definition is completed with the closing brace ( } ).
End the definition of Plex cpx1 with the added resources.
}
99
100
Appendix A. Volume testing

This appendix describes a technique that provides the increased volume of
throughput that is required for stress testing.
To ensure correct functioning when throughput is at high volumes, create CICS
client applications (External Call Interface or External Presentation Interface) that
can generate multiple Distributed Program Link (DPL) or Dynamic Transaction
Routing (DTR) requests. A useful implementation of such a tool relies on the use of
environment variables to specify entities like the following:
v The program or transaction that is to be called on the CICS server
v The data that is to be sent with the request
v The number of transactions to run
v The delay between receiving one transaction and sending another; that is, user
think time
The benefit of this approach is that it makes the programs more flexible. Key
parameters in the program can be influenced without the need to recompile the
program each time.
Using Korn Shell scripts is also recommended to control the execution of External
Call Interface (ECI) or External Presentation Interface (EPI) programs on the
platform. Scripts provide an easy way to run multiple instances of the appropriate
ECI or EPI programs.
See the ECI and EPI samples that are shipped with the CICS Universal Client and
CICS Transaction Gateway for more information about how to write an ECI or EPI
program.
101
102
Appendix B. Routing Monitor displays

The CICS WLM Routing Monitor (RMON) provides a real-time display of the
contents of a Workload Cache Manager (WCM) cache. This section summarizes the
information that is provided with the CICS WLM RMON. This monitor shows the
routing that has taken place from each WCM. Because the display is updated
dynamically, it provides an up-to-date report of routing activity. The results displayed
for each WCM are different, because the routing at any two WCMs is not identical.
An X terminal or terminal window environment is required in order to run the
RMON.
To start the RMON:
1. Authenticate as the user cicssm on the machine that contains the WCM cache
that you want to display.
2. Ensure that the environment variable DISPLAY is correctly set for your display.
cicswlm start rmon
Figure 10 shows the initial display screen of the RMON:
Figure 10. The RMON display of available Plexes
The RMON display of available Plexes

Figure 10 displays the list of available Plexes within CICS WLM. In this case, a
single Plex called cpx1 is shown.
Press the Enter key. Figure 11 on page 104 shows the next screen display:
103
Figure 11. The RMON display of CICS regions available to WLM
The RMON display of available regions

Figure 11 displays the CICS regions that are known to CICS WLM. The SCORE
column indicates the level of outstanding work against each of the CICS systems.
The H column indicates the health of the CICS system. The SESSIONS column is
not used. The columns that are labeled ST AVERAGE and LT AVERAGE display
the short-term and long-term performance of each CICS system. These
performance indicators are a measure of the relative performance of requests that
are routed to those regions.
The row that has no value in the NAME column and a health value of 9 shows
those routing decisions that have defaulted. That is, CICS WLM, for whatever
reason, was not able to make a routing decision. It is possible that the requested
resource was not defined to CICS WLM, or no region was healthy enough to
receive a routing request.
Press the PF4 key to display the next screen, Figure 12 on page 105:
104
Figure 12. The RMON display showing the distribution of routed requests
The RMON display of routed requests distribution

Figure 12 shows the distribution of routed requests. The NAME column shows the
names of the CICS systems that are known to CICS WLM. The SELECTION
column shows how many routing requests CICS WLM has sent to each of the
systems. The DEFAULTED column shows how many requests were sent to the
region by default. The NORMAL column indicates how many requests completed
successfully. The SYS FAIL column indicates how many requests failed to be routed
to the region because the region could not be contacted. The RES FAIL column
indicates how many requests failed to be routed because a CICS resource was not
available. The ABEND column shows how many requests abended in the region to
which they were routed. The RETRY column shows requests that were resent
because the original request failed. Note that this feature is not available with
Distributed Program Links (DPL) or Dynamic Transaction Routing (DTR) work
requests.
The row of figures that has no name represents those requests for which CICS
WLM was not able to make a routing decision. Such requests use the system that
is specified in the RemoteSysId parameter of the Program or Transaction Definition.
No values are in the row for CICSA because CICSA is the routing point, and no
requests are sent to it. All requests are outbound from CICSA to CICSB or CICSC.
If you press PF4 again, information similar to that shown in Figure 13 on page 106
is displayed. This screen shows the programs or transactions that have been
routed. The LOAD value indicates the expected response time for the program or
transaction. The LOAD value is specified in the CICS WLM configuration file.
Appendix B. Routing Monitor displays
105
Figure 13. The RMON display of routed programs and transactions
The RMON display of routed programs and transactions

If you press PF4, you return to Figure 11 on page 104. The operations of Figure 11
on page 104, Figure 12 on page 105, and Figure 13 proceed in sequence.
Note: When the RMON is started before any routing request has been issued, no
resource model information is displayed. This information is loaded only
when a request for that resource is issued from CICS.
To terminate the display, close the X terminal window or use the PF3 key.
Determining routing outcome

To ensure that CICS WLM is making routing decisions rather than allowing requests
to default, issue a request and examine Figure 11 on page 104, Figure 12 on page
105, and Figure 13 of the CICS WLM RMON.
Figure 11 on page 104 shows to which region the request was routed. If all is well,
no row of figures with a health of 9 appears. This row does not appear until a CICS
WLM has been unable to make a routing decision.
Expect Figure 12 on page 105 to display entries under the SELECTED and
NORMAL columns. Again, a column without a name indicates that routing decisions
are not being made by CICS WLM.
If routing is not taking place as expected, examine your environment to ensure that
it is correctly set up. Refer to Appendix C, Troubleshooting, on page 107.
106
Appendix C. Troubleshooting
This section helps you to determine the cause of problems in which work requests
are not being routed correctly.
For a CICS request to be successfully routed by CICS WLM, the following
conditions must exist:
1. The WAP is started successfully.
2. The WCM is started on the Node where the routing is to take place.
3. The WCMs are communicating successfully with the WAP.
4. When a DPL request is needed, these conditions exist:
v The CICS region has been configured successfully with the CICS
WLM-supplied user exits 50 and 51 installed on it.
v The relevant CICS region has been cold started.
5. When a DTR request is needed, these conditions exist:
6.
7.
8.
9.
v The CICS client has been configured successfully with the CICS
WLM-supplied user exit 50 installed on it.
v The relevant CICS region has been cold started.
When an Client ECI request is needed, these conditions exist:
v The CICS client has been configured successfully with the CICS
v If a Plex object has a name other than the default, cpx1, the environment
variables, BHG_WCL_GROUP_NAME and
BHG_WCL_xxx_CICSPLEX_NAME must be set. See Before you start the
CICS WLM on page 39 for discussion about setting these variables.
When an Client EPI request is needed, these conditions exist:
v The CICS region has been configured successfully with the CICS
v If a Plex object has a name other than the default, cpx1, the environment
variables, BHG_WCL_GROUP_NAME and
BHG_WCL_xxx_CICSPLEX_NAME must be set. See Before you start the
CICS WLM on page 39 for discussion about setting these variables.
v The environment variable BHG_WCL_APPLICATION must contain the name
of a valid, defined, and active ApplicationModel object. See Defining an
ApplicationModel on page 38 for discussion on this topic.
All the required resource definitions are in place, and connectivity between
CICS systems functions as expected.
A CICS WLM configuration file has been created, verified, and loaded by use of
the appropriate cicswlm commands.
Validate that these conditions exist as an initial step in problem-solving. See the
following sections for additional help in diagnosing problems:
v How to determine whether the WAP is started on page 108
v How to determine whether the WCM is started on page 108
v How to determine whether the user exits are in place on page 109
v How to validate the CICS environment on page 109
v How to check the configuration file on page 110
v Additional problem diagnosis on page 110
107
How to determine whether the WAP is started

To determine if a WAP is started successfully, take these steps:
v Issue a cicswlm list command on the machine on which the WAP is located.
If the output of this command does not display the WAP, issue a cicswlm
start wap command.
If the start command fails, use the messages it produced to solve the
problem.
v Examine the file /var/cicssm/log/wap.<wap_name>.msg
The following message indicates a successful start:
BHGWAP4704I Initialization completed successfully, awaiting messages
If this message is not found, some common problems are as follows:

- The CICS WLM configuration has not completed successfully.
- The file /var/cicssm/repos/wap.<wap_name> is not present.
- The host name that is contained in the file /var/cicssm/repos/
wap.<wap_name> is not the fully qualified host name of the machine on
which the WAP is running. Modify the host name in this file, and rerun the
cicswlm configure wlm command.
- The port number that is contained in the file /var/cicssm/repos/
wap.<wap_name> is not a valid port or is allocated already. Modify the port
number in this file, and rerun the cicswlm configure wap command.
To obtain additional information about WAP problems:
- Enable the environment variables BHG_WAP_TRACE_LEVEL and
BHG_WAP_COMMS_TRACE_LEVEL.
- Reissue the cicswlm start wap command.
- Format the trace that is produced in file /var/cicssm/log/
wap.<wap_name>.trc.
How to determine whether the WCM is started

To determine whether the WCM is started successfully:
v Issue a cicswlm list command on the machine on which the WCM is located.
If the output of this command does not display the WCM, issue a cicswlm
start wcm command.
If the start command fails, use the messages that it produced to solve the
problem.
v Examine the file /var/cicssm/log/wcm.<host_name>.msg
The following message indicates a successful start:
BHGWCM4601I Initialization completed successfully, awaiting messages
If this message is not found, some common problems are as follows:

- The WCM cannot communicate with the WAP. Ensure that the WAP is
running. If the WAP and WCM are on separate machines, ensure that you
can ping the WAP machine from the WCM machine. The WCM does not
immediately fail ; it makes several attempts to establish communications.
- The CICS WLM configuration has not completed successfully.
- The file /var/cicssm/repos/wap.<wap_name> is not present on the machine
on which the WCM is being started. This file must be accessible to all
machines within a CICS WLM configuration.
108
- The host name that is contained in the file /var/cicssm/repos/

wap.<wap_name> is not the fully qualified host name of the machine on
which the WAP is running. Modify the host name in this file, and rerun the
cicswlm configure wlm command.
- The port number that is contained in the file /var/cicssm/repos/
wap.<wap_name> is not a valid port or is allocated already. Modify the port
number in this file, and rerun the cicswlm configure wap command.
- Examine the file /var/cicssm/log/wcm.<host_name>.msg. Check for the
following message:
BHGWCM4021I NEW_CACHE_MANAGER message sent
This message indicates that the WCM has sent a message to the WAP
announcing the existence of a new WCM.
- Examine the file /var/cicssm/log/wap.<wap_name>.msg. Check for the
following message:
BHGWAP4020I NEW_CACHE_MANAGER message received
This message indicates that the WAP has received a message from the
WCM announcing the existence of a new WCM. Some possible problems
can be:
v The machines that are holding the WAP and the WCM cannot
communicate using TCP/IP.
v The WCM is communicating with a machine other than the one on which
the WAP is running.
v The WAP is not listening on the correct port number.
How to determine whether the user exits are in place

For DPL requests, consider the following:
v Check the message file console.nnnn on every region on which workload
management is to occur. Look for the message:
ERZ015042W...Program BHGDPL now associated with user exit 50....\
ERZ015042W... BHGDPLSP now associated with user exit 51
If this message is missing, correct the problem and restart the CICS system by
using a cold start.
For DTR requests, consider the following:
v Check the message file console.nnnn on every region where workload
management is to take place. Look for the following message:
ERZ015042W...Program BHGDTR now associated with user exit 25
If this message is missing, correct the problem and restart the CICS system by
using a cold start.
How to validate the CICS environment

Before using CICS WLM is manage work requests, ensure that each type of work
request that is to be workload managed is working correctly using the native CICS
processing.
109
Ensure that all requests can be run successfully on all AORs. Check all resource
definitions in the COR to ensure the RemoteSysIds for any resource (program for a
DPL request or transaction for a DTR request) that is remotely accessed has been
reassigned.
Ensure that ECI or EPI requests are completed successfully on the COR, and
hence routed to one of the AORs.
When DTR routing is to be done, you must ensure that the following details are
specified for the Transaction Definition in CICS:
v Dynamic=yes
v RemoteSysId-<default_system>
v RemoteName=<transaction_remote_name>
v ProgName=<first_program_of_transaction_in_remote_system>
How to check the configuration file

Check the syntax of a CICS WLM configuration file by using the cicswlm verify
command.
Ensure that the resource names that are specified in the file exactly match the
names that are used with CICS. Specifically, check the following names:
v SystemClone names must match the CICS region names.
v SystemImage names must match the CICS region names.
v Node names are the fully qualified host names.
v The connection names that are specified in the SystemClone/Connections
definitions are the same names as the names that are used in the CICS
Communications definitions.
v The names that are given for the LocalProgramModels and
LocalTransactionModels match the names that are given for the corresponding
resource names in the CICS AORs.
v The Dynamic=yes value is specified for any CICS program that is designated for
use by a DPL or ECI work request.
Additional problem diagnosis

I am issuing a request to CICS and it is failing to run. What can be wrong?
Check whether the Plex information is in the cache on the routing machine.
This is simple to check. Start a CICS WLM Routing Monitor in a window on
the host on which the WLM cache manager and the routing CICS system
(for example) are running. The first screen of the CICS WLM Routing
Monitor shows a list of the Plexes that are stored in the cache. If no Plexes
are listed, the problem is caused by the way the configuration information is
specified or distributed by the WLM components (the Workload
Management Application Program cache (WAP) and the Workload
Management Cache Manager (WCM)). If one or more Plexes are listed, the
problem is caused by the way the request is being issued to CICS.
No Plexes have been listed by the cicswlm start rmon command. What can be
wrong?
Check the following:
1. Is a WLM application running? Are any errors in its log files?
2. Is a WLM cache manager running? Are any errors in its log files?
110
3. When you loaded the configuration file, were any errors generated?
Check the log files for the wlmload component, in addition to the
console messages.
4. Is the Node on which the cache manager is running specified in the
configuration file? Is it specified correctly? For example, is the host
name the fully qualified host name, including the domain name; for
example, testlab125.company_name.com?
5. If the Node is specified correctly, does the SystemClone that defines the
routing CICS system have the same name in the configuration file as
the CICS system name itself?
If all the above are in order, try stopping the WLM components and retrying
with a higher trace level. The message files (files with the .msg suffix) can
be viewed directly. The trace files (files with the .trc suffix) must be
formatted with the cicswlm format command. Although the trace files
contain information that is intended to be read by IBM customer service
personnel, the information also can be helpful to system administrators.
If a problem has occurred with the communications between the WLM
processes, state information can remain that is preventing communications
from being reestablished. The cicswlm clean wlm command can help to
clean up this remaining information. Be aware that this command cleans all
shared memory resources that are being used by CICS WLM cache files
and socket files. It also removes log files that are more than one day old.
At least one Plex is listed by the cicswlm start rmon command. What can be
wrong?
If the Plex information is getting to the WCMs cache, the WLM distribution
mechanism is working. Some of the things that can be causing are as
follows:
1. Is the CICS system from which you are routing configured to drive the
relevant user exit program? Check the CICS regions console.msg file to
see whether messages in the CICS system startup indicate that the
programs BHGDPL and BHGDPLSP are being associated with user
exits 50 and 51 for Distributed Program Link (DPL) requests. For
Dynamic Transaction Routing (DTR) requests, the BHGDTR program
must be associated with user exit 25.
2. Are any log files called dpl.* being produced, that have any errors
listed? (The fact that an empty file exists is useful to know; it shows that
the BHGDPL program is being initialized).
3. Is the name of the routing CICS system that is listed in the
SystemClones list shown by the Routing Monitor? If not, check its
specification in the configuration file.
4. Are the Connections between the SystemClone objects that represent
the routing CICS system and the target SystemClones correctly
defined? Is the InService attributes for these objects set to a value of 1?
Does the Routing Monitor indicate that the target SystemClones are
healthy (1 is healthy, 3 is unhealthy)? If the CICS WLM Routing Monitor
shows a list of healthy system clones, but no ResourceModels are
shown on the next screen, either a CICS request has not reached the
WLM code, or a request has been received for a resource that cannot
be found. If the latter is the case, check the WAPs log. This log can
detect a message flow to the WLM application to try to discover
information about the requested resource.
5. Is the CICS Program Definition correct if you are performing a DPL? Is
a remote sysid specified that is to be used as a default if WLM cannot
111
find a system to use? Can that program be successfully routed if WLM

is not active? Ensure that dynamic = "yes" is specified in the CICS
configuration file for the program.
I observe that routing is taking place, but it is always choosing the same
system, or is never using a particular system. What can be wrong?
In the latter case, this can be the correct behavior of the WLM
load-balancing algorithm. The algorithm is designed to minimize the
response time for a piece of work. If it can be done best by sending all
requests to one system that is not overloaded, this can be the correct thing
to do. Spreading work around a lightly loaded network means that, in some
cases, unnecessary connections are established between regions, so the
algorithm can choose to route in an apparently unbalanced way.
However, it is possible that routing is being done incorrectly. It can be that
all requests are going to the default CICS system because WLM has not
been able to find any other valid target CICS system. One method of
forcing CICS WLM to route away from this default CICS system is to stop
the HMON, then change the value for the health of the CICS system that is
being selected to a poor value (3 for example) in the CICS WLM
configuration file. Then, save the configuration file and reload it into the
WAP by using the cicswlm load command, and observe any difference.
At this point, CICS WLM should be routing to a different CICS system. If
not, a problem is likely. Check the logs and the output from the cicswlm
start rmon command. If all the routing decisions are going to the default
CICS system, and all SystemClones are healthy, connected, and providing
the required resource, contact your IBM customer support organization.
I still have not found the problem; where else can I look?
CICS WLM produces several message, trace, and console files during its
execution. These files provide useful sources of information about what is
happening in the different components of CICS WLM. See Appendix D,
Directory structure created by installing CICS WLM, on page 113 for more
information.
112
Appendix D. Directory structure created by installing CICS

WLM
Installation of the CICS Workload Management (WLM) utility requires the following
space requirements:
Table 17. Space requirements for installing CICS WLM
Directory
Space requirement
/usr
25 MB
/tmp (or some other file system, to

temporarily store the tar file)
25 MB
/var
1 MB
Two directory structures are used by CICS WLM. They are install_dir/cicssm (where
install_dir is /usr/lpp on AIX ) and /var/cicssm. The install_dir/cicssm directory
contains the shipped code and samples. It contains only code; it has no data that is
associated with a workload management configuration. The /var/cicssm directory
structure contains information that relates to an instance of a CICS WLM
configuration. CICS WLM uses the same directory structure on the AIX platform.
The install_dir/cicssm directory consists of the following subdirectories:
Table 18. Directory structure for the install_dir/cicssm directory
Subdirectory
Description
/bin
CICS WLM executable files
/lib
CICS WLM libraries
/msg
CICS WLM message catalog
/samples
Sample CICS WLM exit and other code
The /var/cicssm directory consists of the following subdirectories:

Table 19. Directory structure for the /var/cicssm directory
Subdirectory
Description
/data
Required for CICS WLM definitions
/log
Trace and message files for various

components
/repos
Descriptions of the CICS configuration, and

the locations of the WAP and WCM
Files created by CICS WLM

CICS WLM creates three main types of files:
v Message files
v Trace files
v Console files
The message file records the significant events in the life of the component with
which it is associated; it contains data in text format. Message files are associated
113
with the Workload Management Application Program cache (WAP), Workload

Management Cache Managers (WCMs), Health Monitor (HMON), and Routing
Monitor (RMON).
The trace file records the significant events in the life of the component with which it
is associated. It contains trace data that is written in a compressed format. The
trace file must be formatted by using the BHGTRFMT utility. CICS WLM
environment variables control the level of tracing that occurs within a component.
When the default level of trace is in effect, the trace files are empty, unless a
significant component failure occurs.
The console file records the significant events in the life of the component with
which it is associated; it contains data in text format. Console files are associated
only with the WAP.
Files in the /var/cicssm/log directory

The directory /var/cicssm/log is the primary location for CICS WLM log files.
Message and trace files are written for the WAP and WCM. These files contain
messages that show the processing that the WAP and WCM have performed. In
addition, a console file is associated with both the WAP and WCM.
The WAP message, trace, and console file names are in the following forms:
wap.<wap_name>.msg
wap.<wap_name>.trc
wap.<wap_name>.console
Examples of these file names are:

wap.wap1.msg
wap.wap1.trc
wap.wap1.console
The WCM message, trace, and console file names are in the following forms:
wcm.<hostname>.msg
wcm.<hostname>.trc
wcm.<wap_name>.<hostname>.console

wcm.machine1.acme.com.msg
wcm.machine1.acme.com.com.trc
wcm.wap1.machine1.acme.com.console
When workload management is enabled in a CICS system on , one or more files

are associated with each CICS application server in that system. For example, a
CICS system that is managing Distributed Program Link (DPL) requests has a
message file and a trace file that is associated with each CICS application server.
These files contain information that relates to routing requests that are made within
the associated CICS application server.
The DPL message and trace file names are in the following forms:
dpl.<hostname>.<identifier>.<cicsas_process_number>.msg
dpl.<hostname>.<identifier>.<cicsas_process_number>.trc

dpl.machine1.acme.com.0000000209.0000016090.msg
dpl.machine1.acme.com.0000000209.0000016090.trc
114
Files in the /tmp directory

A number of CICS WLM-related files are allocated within the /tmp directory. These
files are used for a variety of purposes, as shown in Table 20:
Table 20. File structure created by CICS WLM in the /tmp directory
File name
Description
bhg.active.wap.<wap_name>
Indicates that the named WAP is active
bhg.active.wcm.<wap_name>
Indicates that the named WCM is active
bhg.dpl.<cicsas_process_number>.skt
A socket file that is used by CICS WLM
bhg.wap.<wap_name>.shm
A file that is used to map the shared memory

that is used for the WAP cache
bhg.wcm.<wap_name>.shm

that is used for the WCM cache
bhg.wcm.skt
A socket file that is used by CICS WLM
bhg.wlmload.shm

that is associated with the WLM load process
Note: When each trace file reaches a particular size (by default, 100,000 bytes), it
is renamed to its current_ name.old. A new trace file, current_name, is then
allocated and written to.
Appendix D. Directory structure created by installing CICS WLM
115
116

This appendix displays the CICS WLM configuration file that is used for the simple
test sample. It is redisplayed without the commented sections for quick reference.
The commented display is shown in Configuration file for Routing Test sample
code on page 64.
This Plex is defined with the name of the cpx1. The name cpx1 is the default
CICSplex name. If you use a different Plex name, two variables must be included in
the environment of the CICS regions that are using Distributed Program Links
(DPL) and Dynamic Transaction Routing (DTR) user exits. See Before you start the
CICS WLM on page 39 for information on these variables.
Plexes.cpx1
{
SystemModels.TYPE1;
SystemModels.TYPE2;
SystemClones.CICSA;
SystemClones.CICSB;
SystemClones.CICSC;
SystemClones.CICSA/Connections.B1;
SystemClones.CICSA/Connections.B2;
SystemClones.CICSB/Connections.B1;
SystemClones.CICSC/Connections.B1;
Nodes."wlmtest.acme.com";
Nodes."wlmtest.acme.com/SystemImages.CICSA";
Nodes."wlmtest.acme.com/SystemImages.CICSB";
Nodes."wlmtest.acme.com/SystemImages.CICSC";
LocalProgramModels.CALLED;
LocalTransactionModels.WLMT;
LocalProgramModels.CICSECIWLM;
LocalProgramModels.CICSEPIWLM;
ApplicationModels.Appl1
session_scale_1
= 1.0
;
session_scale_2
= 2.0
;
load_scale_1
= 0.0
;
load_scale_2
= 1.0
;
load_limit
= 600.0
;
connection_scale
= 1.0
;
same_limit_1
= 5
;
same_limit_2
= 10
;
same_adjustment
= 0.10
;
same_scale_1
= 0.0
;
same_scale_2
= 0.0
;
known_adjustment
= 0.05
;
known_scale_1
= 0.0
;
known_scale_2
= 0.0
;
normalise_scale
= 0.00833
;
equal_delta
= 0.0001
;
health_adjustment_1 = 0.0
;
;
;
;
;
health_timeout
= 120.0
;
score_limit
= 5000.0
;
retry_limit
= 2
;
reselection_limit
= 2
;
wcm_resend_timeout
= 1.0
;
wcm_retry_timeout
= 10.0
;
wcm_retry_limit_1
= 5
;
wcm_retry_limit_2
= 1
;
wcm_fail_timeout
= 600.0
;
117
autoinstall_load
= 3.0
SystemModels.TYPE1
{
cloned_as -> SystemClones.CICSA;
}
SystemModels.TYPE2
{
cloned_as ->
{
SystemClones.CICSB,
SystemClones.CICSC
};
}
SystemClones.CICSA
{
factor=1.0;
maxServers=5;
health=1;
}
SystemClones.CICSB
{
factor=1.0;
maxServers=5;
health=1;
}
SystemClones.CICSC
{
factor=1.0;
maxServers=5;
health=1;
}
{
load=0.1;
inService=1;
my_other_half -> SystemClones.CICSB/Connections.B1;
}
{
load=0.1;
inService=1;
my_other_half -> SystemClones.CICSC/Connections.B1;
}
Nodes."wlmtest.acme.com"
{
}
Nodes."wlmtest.acme.com/SystemImages.CICSA"
{
}
Nodes."wlmtest.acme.com/SystemImages.CICSB"
{
}
Nodes."wlmtest.acme.com/SystemImages.CICSC"
{
}
LocalProgramModels.CALLED
{
load=0.25;
dynamic="yes";
configured_on ->
118
{
SystemModels.TYPE2,
};
}
LocalTransactionModels.WLMT
{
load=0.25;
configured_on ->
{
SystemModels.TYPE2
};
}
}LocalProgramModels.CICSECIWLM
{
load=0.25;
dynamic="yes";
configured_on ->
{
SystemModels.TYPE2,
};
}LocalProgramModels.CICSEPIWLM
{
load=0.25;
dynamic="yes";
configured_on ->
{
SystemModels.TYPE2,
};
}ApplicationModels.Appl1
{
load=0.25;
configured_on->
{
SystemsModels.TYPE2;
};
}
119
120
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Appendix F. The generated WLM configuration file

The appendix shows the WLM configuration generated through the steps mentioned
in chapter 10. The first four lines in the WLM configuration file is used internally.
You are advised not to alter those contents.
//Created by CICS WLM CONFIG:fb009ab2-fd22-11db-a7f2-0002557600e3.
// This configuration file is generated from the WLM tool cicswlmcfg.
// please do not edit this file manually.
// Date and Time of create: 20070718.153046
// Version of cicswlmcfg
: @(#)WLMCFG,Wed Jul 18 15:30:05 PAKDT 2007,
TXSeries 6.2.0.0 r000-L070718
Plexes.plex1
{
//The SystemMode Declarations...
SystemModels.GROUP1;
SystemModels.GROUP2
//The SystemClones Declarations...
SystemClones.REGCOR;
SystemClones.REGION01;
SystemClones.REGION02;
SystemClones.REGION03
//The Nodes Declarations...
Nodes."host1.xyz.com";
Nodes."host2.xyz.com";
// The SystemImage Declarations ....
Nodes."host1.xyz.com/SystemImages.REGCOR";
Nodes."host1.xyz.com/SystemImages.REGION03";
// The SystemClones Connections Declarations ....
SystemClones.REGCOR/Connections.C001;
SystemClones.REGION01/Connections.CICA;
// The LocalProgramModels Declarations ....
LocalProgramModels.PROGRAM1;
// The LocalTransactionModels Declarations ....
LocalTransactionModels.TRNA;
// The Plex Attributes ....
autoinstall_load = 3.0;
connection_scale = 1.0;
equal_delta = 0.0001;
health_adjustment_1 = 0.0;
health_timeout = 120.0;
known_adjustment = 0.05;
known_scale_1 = 0.0;
known_scale_2 = 0.0;
load_limit = 600.0;
121
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
load_scale_1 = 0.0;
load_scale_2 = 1.0;
normalise_scale = 0.00833;
reselection_limit = 2;
retry_limit = 2;
same_adjustment = 0.10;
same_limit_1 = 5;
same_limit_2 = 10;
same_scale_1 = 0.0;
same_scale_2 = 0.0;
score_limit = 5000.0;
session_scale_1 = 1.0;
session_scale_2 = 2.0;
wcm_fail_timeout = 600.0;
wcm_resend_timeout = 1.0;
wcm_retry_limit_1 = 5;
wcm_retry_limit_2 = 1;
wcm_retry_timeout = 10.0;
// The SystemMode Definitions ....
SystemModels.GROUP1
{
cloned_as->{
SystemClones.REGCOR
};}
SystemModels.GROUP2
{
cloned_as->{
SystemClones.REGION01,
SystemClones.REGION02,
};}
// The SystemClones Definitions ....
SystemClones.REGCOR
{
factor = 1.0;
health = 1;
maxServers = 25;
installed_on->Nodes."host1.xyz.com";
}
{
factor = 1.0;
health = 1;
maxServers = 25;
}
{
factor = 1.0;
health = 1;
maxServers = 25;
}
{
factor = 1.0;
health = 1;
maxServers = 25;
}
// The SystemClones Connections Definitions ....
SystemClones.REGCOR/Connections.C001
{
inService = 1;
122
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
load = 0.1;
my_other_half->SystemClones.REGION01/Connections.CICA;
}
{
inService = 1;
load = 0.1;
}
{
inService = 1;
load = 0.1;
}
// The Nodes Definitions ....
Nodes."host1.xyz.com/SystemImages.REGCOR"{}
Nodes."host1.xyz.com/SystemImages.REGION03"{}
// The LocalProgramModels Declarations ....
LocalProgramModels.PROGRAM1
{
dynamic = "yes";
load = 0.25;
configured_on->
{
SystemModels.GROUP2
};
}
// The LocalTransactionModels
LocalTransactionModels.TRNA
{
load = 0.25;
configured_on->
{
SystemModels.GROUP2
};
}
}
Definitions ....
Appendix F. The generated WLM configuration file
123
124
Appendix G. Complete list of CICS WLM commands

This sections lists all CICS WLM commands.
Command
Parameters
Description
cicswlm configure
<config_file>
This command must be run

before any other cicswlm
command is run.
cicswlm list
none
This command displays any

active WAP, WCM, or HMON
components.
cicswlm load
wlm.cfg <wap_name>
This command loads a

configuration file. Run it only
on files that have been
verified, and run it only after
a WAP has already been
started.
cicswlm purge
all, wap, wcm, hmon, process This command purges the

<id>, or none
component that is named by
the parameter. Or, to purge
all WLM components, issue
the command with no
parameters.
cicswlm start
wap <wap_name> , wcm <

wap_name>, rmon, hmon
This command starts the

WLM component that is
named by the parameter.
cicswlm stop
wap <wap_name> , wcm

<wap_name>, hmon
This command stops the

WLM component that is
named by the parameter.
cicswlm stop all
none
This command stops all WLM

components.
cicswlm verify
<wlm_config_file>
This command ensures that

no errors exist in a
configuration file.
cicswlm clean
wlm
This command clears all

shared memory resources
that are being used by WLM
cache files and socket files. It
also removes log files that
are more than one day old.
cicswlm format
wap.<wap_name>.trc
This command formats the

output of trace files (files
having the .trc suffix).
125
126
Appendix H. Glossary of CICS WLM terms

Algorithm distribution approach
A method that is employed by CICS WLM to determine the optimal region
for performing a processing request. The optimal selection is based on a
composite of customizable variables whose values are derived from
continuous monitoring of the environment.
AOR
The acronym for Application Owning Region.
Application Owning Region (AOR)

A region within a CICS WLM environment that can process work requests.
No code needs to be installed on the AOR machines; however, Listener
Definitions (LD), Communications Definitions (CD), Transaction Definitions
(TD), Program Definitions (PD), and modifications to the regions
LocalSysId must be made on the AOR machine. The CICS WLM utility uses
the standard, established database connectivity to process work requests.
ApplicationModel
An abstract representation that groups resources that are used for the
workload management of CICS EPI requests when the CICS EPI client is
assigned to a particular application. It refers to a SystemModel object and
enables access to all LocalTransactionModel resources that are defined on
the SystemModel object.
Attribute
A specific value, such as response time, that is associated with an object
that is defined to the CICS WLM utility.
CICSplex
Another name for the Plex object. All other objects that are defined for the
CICS WLM utility are contained within a Plex.
CICS WLM
An acronym for CICS Workload Management utility.
CICS Workload Management utility
A stand-alone tool that optimizes the distribution of processing tasks in a
CICS environment that has two or more regions that can process work
requests. It is designed to work in an existing, configured CICS for system
that has been defined to the utility through configuration files. It can process
requests of the following types: Distributed Program Link (DPL), Dynamic
Transaction Routing (DTR), External Presentation Interface (EPI), External
Call Interface (ECI), and data-dependant routing.
Client Owning Region (COR)
A region on a CICS for machine within the environment defined to the CICS
WLM utility that is designated to receive incoming work requests and
determine the optimal resource for processing the request. A local workload
cache manager (WCM), a workload client (WCL), and user exit codes
(supplied by the utility) must be installed on the machine. In addition,
Listener Definitions (LD), Communications Definitions (CD), Transaction
Definitions (TD), Program Definitions (PD), and modifications to the regions
LocalSysId must be made on the COR machine. A CICS WLM system can
be figured without designating a COR by directly installing a WCM, WCL,
and user exit codes on each client machine that accesses the CICS WLM
system.
127
Contents
Object types that are contained within the definition of an object that is
made for the CICS WLM utility.
Connection
An abstract representation of the communication links between CICS
systems in an environment that is set up for use of the CICS WLM utility.
COR
The acronym for Client Owning Region.
Data-dependent routing
The ability to make a decision to route a work request to a particular server
based on data that is associated with that item of work. This is usually done
by looking at some portion of the CICS COMMAREA.
Health Monitor (HMON)
An optional component of the CICS WLM utility that reports on the status of
object models that are defined in the CICS WLM environment. It uses three
reporting levels: Level 1, the region is up and can be contacted; Level 2,
the region is not up, but the host on which the region runs can be
contacted; and Level 3, neither the region, or the machine on which it runs,
can be contacted. The HMON must be installed on the same machine as is
the WAP; no code is installed on remote machines to use the HMON
component.
HMON
The acronym for the Health Monitor component of the CICS WLM.
LocalProgramModel
An abstract representation in CICS WLM configuration file that corresponds
to the Program Definition that is used for running a program.
to the Transaction Definition that is used for running a transaction. Usually,
this object contains a pointer to a locally running program.
Node
An abstract representation of an individual host on which CICS systems can

be installed. Within a configuration for CICS WLM, Nodes must be defined
using the fully qualified host name, including the domain name.
Object Model
An abstract representation of the resources in your CICS system that can
be defined for use by the CICS WLM utility. The resources that can be
represented include: regions, connections between regions, programs that
are being routed between regions, transactions that are being routed
between regions, data-dependent routing considerations, and machines on
which CICS regions are running.
Partition data
A portion of data defined within a Partition object that identifies the values
to be used from a work request when making a data-dependent routing
decision.
Partition object
An abstract representation that is used to specify a subset of SystemClone
objects that is to be used as potential destinations for data-dependent
routing.
Plex
128
The highest grouping of CICS resources that is defined to the CICS WLM
utility. It is also called a CICSplex. All other objects that are defined for the
CICS WLM utility are contained within a Plex.
Relationship
An object that defines a connection to some other object that is defined to
the CICS WLM utility.
RemoteProgramModel
An abstract representation ina CICS WLM configuration file that
corresponds to the Remote Definition of a CICS resource. This definition is
placed onto a Client Owning Region to identify a program that is running on
an Application Owning Region in a CICS WLM environment. It is for
informational purposes only and does not play a part in routing decisions.
to the Remote Definition of a CICS resource. This definition is placed onto a
Client Owning Region to identify a program that is running on an Application
Owning Region in a CICS WLM environment. It is for informational
purposes only and does not play a part in routing decisions.
ResourceModel objects
An abstract representation of the CICS programs and transactions that can
be routed by using the CICS WLM utility.
RMON
The acronym for the Routing Monitor component of CICS WLM.
Routing Monitor (RMON)
A component of the CICS WLM that tracks activity in the WCM caches. It
shows the routing decisions that are made for requests from all clients that
are sharing the WCM. RMON is installed on the same machine as is the
WAP.
Separation object
An abstract representation that is used in an environment that is defined to
a CICS WLM utility that groups several Partition objects to enable
data-dependent routing.
SystemClone object
An abstract representation of a particular type of a CICS region. The
SystemClone definition corresponds precisely to the SystemModel definition
that it represents.
SystemImage object
A representation that is placed on a Node object to indicate the presence of
a SystemClone object.
SystemModel object
An abstract representation of a generic type of a CICS region. A
SystemClone object is defined based on a specific instance of a
SystemModel object.
WAP
The acronym for CICS Workload Management Global Application Cache.
WCL
The acronym for CICS Workload Management Client.
WCM
The acronym for CICS Workload Management Local Cache Manager.
Workload Management Global Application Cache (WAP)

The global cache that holds all configuration information defining the CICS
environment that is defined for inclusion in workload management routing
determinations. The WAP initially populates the local caches (WCM) and
Appendix H. Glossary of CICS WLM terms
129
updates the WCMs when any change is made to the configuration that is
defined to the utility. The WAP is usually installed on a High Availability
node on a CICS for machine.
Workload Management Local Cache Manager (WCM)
The local cache that is populated and updated by the WAP. It resides on
any machine in the system where a routing decision is made. WCMs can
be installed on a single region on a single node; on one or more regions on
a single node; or on Client machines.
Workload Management Client (WCL)
The WCL receives the incoming processing request and searches the WCM
for information about the status of the AORs; it applies the algorithm that is
designed to optimize the routing determination, and it forwards the request
to the WAP when the WCM does not have the required information.
130
Notices
This information was developed for products and services offered in the U.S.A. IBM
may not offer the products, services, or features discussed in this document in other
countries. Consult your local IBM representative for information on the products and
services currently available in your area. Any reference to an IBM product, program,
or service is not intended to state or imply that only that IBM product, program, or
service may be used. Any functionally equivalent product, program, or service that
does not infringe any IBM intellectual property right may be used instead. However,
it is the users responsibility to evaluate and verify the operation of any non-IBM
product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you any
license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
DOCUMENT AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OR CONDITIONS OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express
or implied warranties in certain transactions, therefore, this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the document. IBM may make improvements and/or
changes in the product(s) and/or the program(s) described in this publication at any
time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those
Web sites. The materials at those Web sites are not part of the materials for this
IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes
appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of
enabling: (i) the exchange of information between independently created programs
131
and other programs (including this one) and (ii) the mutual use of the information
which has been exchanged, should contact:
IBM Corporation
ATTN: Software Licensing
11 Stanwix Street
Pittsburgh, PA 15222
U.S.A.
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this document and all licensed material available
for it are provided by IBM under terms of the IBM International Program License
Agreement or any equivalent agreement between us.
Any performance data contained herein was determined in a controlled
environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those
products, their published announcements or other publicly available sources. IBM
has not tested those products and cannot confirm the accuracy of performance,
compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those
products.
All statements regarding IBMs future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples may include
the names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
If you are viewing this information softcopy, the photographs and color illustrations
may not appear.
Trademarks and service marks

The following terms are trademarks or registered trademarks of the IBM Corporation
in the United States, other countries, or both:
Advanced Peer-to-Peer Networking
AS/400
CICS/400
132
AIX
CICS
CICS/6000
CICS/ESA
CICS/MVS
CICS/VSE
CICSPlex
C-ISAM
Database 2
DB2
DB2 Universal Database
GDDM
IBM Registry
IBM
IMS
Informix
Language Environment
MVS
MVS/ESA
OS/390
OS/2
OS/400
RACF
RETAIN
RISC System/6000
RS/6000
SOM
Systems Application Architecture
System/390
TXSeries
TCS
VisualAge
VSE/ESA
VTAM
WebSphere
z/OS
Domino, Lotus, and LotusScript are trademarks or registered trademarks of Lotus

Development Corporation in the United States, other countries, or both.
ActiveX, Microsoft, Visual Basic, Visual C++, Visual J++, Visual Studio, Windows,
Windows NT, and the Windows 95 logo are trademarks or registered trademarks
of Microsoft Corporation in the United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Acucorp and ACUCOBOL-GT are registered trademarks of Acucorp, Inc. in the
United States, other countries, or both.
Pentium is a trademark of Intel Corporation in the United States, other countries,
or both.
This software contains RSA encryption code.
Other company, product, and service names may be trademarks or service marks
of others.
Notices
133
134
Index
A
add
command 78
adding
CICS system 92
program 91
resource 91
adding resource
sample 95
Administration
Console 83
affinities
environment 25
analysis
information-gathering
AOR
sample 51
applications
setup 49
attributes
connection 87
objects 12
plex 85
program 87
region 87
transaction 87
21
B
benefits
C
cache
WAP cache 6
WCM 6
CICS definitions
establishing 27
modify 34
CICS system
adding 92
CICSplex
cpx1 28
cicssm
environment variables
group 39
PATH 39
userid 39
cicssm.config
initialization file 8
cicswlmcfg
command 73
return codes 88
Client Owning Region
COR 47
command
add 78
command (continued)
cicswlmcfg 73
delete 79
list 82
modify 80
verify 81
command list 125
commands
configuration 76
WLM commands 8
Communications Definitions
sample 48
components
definitions 5
install 24
list 70
plan location 24
start 69
stop 69
configuration
WLM 75
configuration commands 76
configuration file
customizing 21, 27
defining resources 11
environment definition 11
load 42
multiple 28
sample 64
verify 41
wlm.cfg 8
connection
attributes 87
Connection
object 16
Console
Administration 83
contents
objects 12
COR
Client Owning Region 47
sample 50
customizing
configuration file 21, 27
initialization file 21, 27, 33
39
D
database definitions
requirements 25
default naming
Plex naming 39
defining resources
configuration file 11
delete
command 79
directory structure
installation 113
135
displays
RMON 104
Distributed Program Links
DPL 36
DPL
Distributed Program Links 36
issue request 53
source code 55
user exits 8
DTR
Dynamic Transaction Routing 37
issue request 54
source code 55
user exits 8
Dynamic Transaction Routing
DTR 37
E
ECI
issue request 54
source code 56
user exits 8
empty resources 71
environment
high-level review 21
requirements 25
sample 47
environment definition
environment example
single machine 23
using Windows Client 22
environment variables
cicssm 39
EPI
issue request 54
source code 59
user exits 8
establish
Resource Definitions 35
user exits 36
establishing
CICS definitions 27
user exits 27
F
flow of work request
planning concept 24
forced health value
HMON 45
functions 1
Health Monitor
HMON 7
hierarchy
object model 13
high-level review
environment 21
HMON
forced health value
Health Monitor 7
start 44
global cache
cache 6
group
cicssm 39
45
I
information-gathering
analysis 21
initial activation sequence 40
initial configuration
WAP 34
initial start 39
initialization file
cicssm.config 8
customization 21
customizing 27, 33
sample 64
install
components 24
installation
directory structure 113
space requirements 113
issue request
DPL 53
DTR 54
ECI 54
EPI 54
L
list
command 82
components 70
load
verify 33
loader
parser 9
local cache
cache 6
LocalProgramModel
object 17
object 17
136
modify
CICS definitions
command 80
user exits 34
34
multiple
configuration file
28
N
Node
object
16
O
object
Connection 16
LocalProgramModel 17
LocalTransactionModel 17
Node 16
Plex 13
RemoteProgramModel 17
RemoteTransactionModel 17
ResourceModel 17
SystemClone 15
SystemImage 16
SystemModel 15
object model 12
hierarchy 13
objects
attributes 12
contents 12
relationships 12
P
parser
loader 9
PATH
cicssm 39
placing
WAP 33
plan location
components 24
planning concept
flow of work request 24
Planning considerations 3
plex
attributes 85
Plex
CICSplex 28
object 13
Plex naming
default naming 39
program
adding 91
attributes 87
purge resources 71
R
region
attributes 87
relationships
objects 12
RemoteProgramModel
object 17
object 17
requirements
environments 25
resource
adding 91
Resource Definitions
establish 35
ResourceModel
object 17
return codes
cicswlmcfg 88
RMON
displays 104
Routing Monitor 7
start 45
Routing Monitor
RMON 7
S
sample
adding resource 95
AOR 51
Communications Definitions
COR 50
environment 47
initialization file 64
start 52
WAP 52
scheduled housekeeping 72
setup
applications 49
single machine
environment example 23
source code
DPL 55
DTR 55
ECI 56
EPI 59
space requirements
installations 113
start
components 69
HMON 44
RMON 45
sample 52
start WAP
WAP 41
start WCM
WCM 41
stop
components 69
WAP 69
WCM 69
SystemClone
object 15
48
Index
137
SystemImage
object 16
SystemModel
object 15
wlm.cfg
work requests
validate 54
Workload Management Client
WCL 6
T
testing 43
volume 101
transaction
attributes 87
troubleshooting 107
U
user exits
DPL 8
DTR 8
ECI 8
EPI 8
establish 36
establishing 27
modify 34
userid
cicssm 39
using Windows Client
environment example
22
V
validate
work requests 54
verify
command 81
load 33
volume
testing 101
W
WAP
initial configuration 34
placing 33
sample 52
start 41
stop 69
WAP cache
cache 6
WCL
Workload Management Client
WCM
start 41
stop 69
WCM cache
cache 6
WLM
configuration 75
WLM commands
commands 8
138
SC34-6638-02

Spine information:
Version 6.2
SC34-6638-02

TXSeries For Multiplatforms Using CICS Workload Management Version 6.2

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

TXSeries For Multiplatforms Using CICS Workload Management Version 6.2

Загружено:

Авторское право:

Доступные форматы

TXSeries for Multiplatforms

Using CICS Workload Management

TXSeries for Multiplatforms

Using CICS Workload Management

Third Edition (January 2008)

Chapter 1. Understanding CICS WLM . . . . . . . . . . . . . .

Chapter 2. Components of WLM . . . . .

Chapter 3. Describing the environment

CICS WLM utility

Chapter 4. Preparing for CICS WLM . . . . .

Chapter 5. Customizing CICS WLM to your environment

Copyright IBM Corp. 1999, 2008

Customizing the initialization file . . . . . . . . . . .

Chapter 6. Starting CICS WLM for

the first time .

Chapter 8. Creating a simple routing environment . . . . . .

Chapter 9. Using and maintaining CICS WLM

Chapter 7. Testing CICS WLM . . . . . .

Chapter 10. CICS WLM configuration tool-cicswlmcfg

TXSeries for Multiplatforms: Using CICS Workload Management

list - Lists available configuration files . . . . .

Chapter 11. Adding resources to WLM . . . .

Appendix A. Volume testing . . . . . . . . . . . . . . . . . . . 101

Appendix D. Directory structure created

Appendix E. Code for the sample wlm.cfg

Appendix F. The generated WLM configuration file . . . . . . . . . . 121

TXSeries for Multiplatforms: Using CICS Workload Management

Environmental changes introduced through the use of CICS WLM . . . . . . . . . . . . . 2

Copyright IBM Corp. 1999, 2008

TXSeries for Multiplatforms: Using CICS Workload Management

A road map for Using CICS Workload Management . . . . . . . . . . . . . . . . . . xi

Copyright IBM Corp. 1999, 2008

TXSeries for Multiplatforms: Using CICS Workload Management

About this book

Who should read this book

Understanding CICS Workload Management...

Chapter 1, Understanding CICS WLM, on

Learn about WLM components

Chapter 2, Components of WLM, on page 5

Learn about the CICS WLM object model

Chapter 3, Describing the environment to

Preparing for CICS Workload Management...

Chapter 5, Customizing CICS WLM to your

See a sample CICS WLM Plex configuration

Sample configuration file (wlm.cfg) on page

See the steps for initial activation of CICS

Chapter 6, Starting CICS WLM for the first

Get information about testing your

Chapter 7, Testing CICS WLM, on page 43

See a simple WLM environment for testing

Chapter 8, Creating a simple routing

Using CICS Workload Management...

Chapter 9, Using and maintaining CICS

Learn about the WLM configuration tool cicswlmcfg

Chapter 10, CICS WLM configuration

Learn about adding new resources to your

Chapter 11, Adding resources to WLM, on

Learn about volume testing

Appendix A, Volume testing, on page 101

Table 1. A road map for Using CICS Workload Management (continued)

Learn about troubleshooting

Appendix C, Troubleshooting, on page 107

Examine the file structure created by CICS