DemoSubmit A Job Stream

Front cover
Deployment Guide Series: IBM Tivoli Workload Scheduler V8.4 and IBM Tivoli Dynamic Workload Broker V1.2
Deployment best practices and scheduling scenarios Planning and architecture Case studies and planning for engagement
Vasfi Gucer Giuseppe Grammatico Martin Lisy Michael A Lowry
ibm.com/redbooks
International Technical Support Organization Deployment Guide Series: IBM Tivoli Workload Scheduler V8.4 and IBM Tivoli Dynamic Workload Broker V1.2 May 2008
SG24-7528-00
Note: Before using this information and the product it supports, read the information in Notices on page xxiii.
First Edition (May 2008) This edition applies to IBM Tivoli Workload Scheduler V8.4 and IBM Tivoli Dynamic Broker V1.2.
Copyright International Business Machines Corporation 2008. All rights reserved. Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv The team that wrote this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv Become a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxvii Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxvii Part 1. Concepts and architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Chapter 1. Workload scheduling overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1 Market trends and directions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.2 Business solutions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3 IBM Tivoli Workload Automation portfolio . . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.4 Tivoli Workload Automation in action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 1.4.1 Tivoli Workload Automation integration with IBM products . . . . . . . . 15 Chapter 2. Tivoli Workload Scheduler concepts and architecture . . . . . . 17 2.1 Introduction to Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.2 Overview of Tivoli Workload Scheduler. . . . . . . . . . . . . . . . . . . . . . . . . . . 18 2.3 Overview of Tivoli Dynamic Workload Broker . . . . . . . . . . . . . . . . . . . . . . 18 2.4 Tivoli Workload Scheduler architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . 19 2.4.1 The Tivoli Workload Scheduler network . . . . . . . . . . . . . . . . . . . . . . 20 2.4.2 Tivoli Workload Scheduler workstation types . . . . . . . . . . . . . . . . . . 24 2.4.3 Tivoli Workload Scheduler topology . . . . . . . . . . . . . . . . . . . . . . . . . 25 2.4.4 Tivoli Workload Scheduler components . . . . . . . . . . . . . . . . . . . . . . 26 2.4.5 Tivoli Workload Scheduler plan. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 2.5 Tivoli Workload Scheduler advanced customization . . . . . . . . . . . . . . . . . 33 2.5.1 Global options parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 2.5.2 Local options parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 2.6 Tivoli Workload Scheduler batch processing process flow . . . . . . . . . . . . 45 2.6.1 Scenarios for this book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Copyright IBM Corp. 2008. All rights reserved.
iii
2.7 Sizing of typical Tivoli Workload Scheduler deployments . . . . . . . . . . . . . 50 2.8 What is new in Tivoli Workload Scheduler V8.4 . . . . . . . . . . . . . . . . . . . . 51 Chapter 3. Tivoli Dynamic Workload Broker concepts and architecture . 53 3.1 Topological view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 3.2 Server components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 3.2.1 Resource Repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 3.2.2 Resource Advisor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 3.2.3 Job Dispatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 3.2.4 Job Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 3.2.5 Allocation Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 3.3 Tivoli Dynamic Workload Broker agent . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 3.3.1 Agent components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 3.3.2 Agent subcomponents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 3.4 Common Agent Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 3.4.1 Agent Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 3.4.2 Common Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 3.4.3 Interaction between Tivoli Dynamic Workload Broker and Common Agent Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 3.5 Job and resource definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 3.5.1 Job definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 3.5.2 Resource definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 3.6 Tivoli Dynamic Workload Broker user interfaces. . . . . . . . . . . . . . . . . . . . 77 3.6.1 Tivoli Dynamic Workload Console . . . . . . . . . . . . . . . . . . . . . . . . . . 77 3.6.2 Command-line interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 3.6.3 Job Brokering Definition Console . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 3.7 Useful tips for working with job definitions. . . . . . . . . . . . . . . . . . . . . . . . . 84 3.7.1 Comfort approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 3.7.2 Security approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 3.7.3 Job Brokering Definition Console enhancements . . . . . . . . . . . . . . . 87 3.8 Security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 3.8.1 Encrypted communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 3.8.2 Firewall support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 3.8.3 Authentication mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 3.8.4 Authorization roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 3.8.5 Single sign-on enablement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 3.8.6 Recommended security best practices after installation . . . . . . . . . 113 3.9 Tivoli Dynamic Workload Broker auditing . . . . . . . . . . . . . . . . . . . . . . . . 114 3.9.1 Tivoli Dynamic Workload Broker audit capabilities . . . . . . . . . . . . . 115 3.9.2 Configuring the auditing properties . . . . . . . . . . . . . . . . . . . . . . . . . 115 3.9.3 Audit trail file name convention . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 3.9.4 Important security note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
iv
IBM Tivoli Workload Scheduler V8.4 and IBM Tivoli Dynamic Workload Broker V1.2
3.10 Web services interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 3.11 Physical location of Tivoli Dynamic Workload Broker components . . . . 119 3.11.1 Locations of server components . . . . . . . . . . . . . . . . . . . . . . . . . . 119 3.11.2 Locations of agent components . . . . . . . . . . . . . . . . . . . . . . . . . . 121 3.11.3 Location of certificates and private keys . . . . . . . . . . . . . . . . . . . . 122 3.12 What is new in Tivoli Dynamic Workload Broker 1.2 . . . . . . . . . . . . . . . 124 3.13 Combined Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker solution architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 Part 2. Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Chapter 4. Installation and configuration . . . . . . . . . . . . . . . . . . . . . . . . . 131 4.1 Software and hardware requirements for Tivoli Workload Scheduler . . . 132 4.2 Tivoli Workload Scheduler software requirements . . . . . . . . . . . . . . . . . 132 4.2.1 Supported operating systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 4.3 Tivoli Dynamic Workload Broker hardware and software requirements . 135 4.4 Supported operating systems for other Tivoli products . . . . . . . . . . . . . . 135 4.5 Our Tivoli Workload Automation environment . . . . . . . . . . . . . . . . . . . . . 136 4.6 Installing and configuring Tivoli Workload Scheduler V8.4 . . . . . . . . . . . 137 4.6.1 Tivoli Workload Scheduler V8.4 installation . . . . . . . . . . . . . . . . . . 137 4.6.2 Installing Tivoli Dynamic Workload Console V8.4 . . . . . . . . . . . . . . 154 4.6.3 Installing Tivoli Job Scheduling Console V8.4 . . . . . . . . . . . . . . . . 163 4.7 Installing and configuring Tivoli Dynamic Workload Broker V1.2 . . . . . . 168 4.7.1 IBM Tivoli Dynamic Workload Broker V1.2 installation . . . . . . . . . . 169 4.7.2 Installing IBM DB2 Universal Database V9.1 . . . . . . . . . . . . . . . . . 184 4.7.3 Installing WebSphere Application Server V6.1 . . . . . . . . . . . . . . . . 197 4.7.4 Installing Job Brokering Definition Console V1.2 . . . . . . . . . . . . . . 205 4.8 Installing Tivoli Dynamic Workload Console V8.4 on an existing WebSphere Application Server V6.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 Chapter 5. Demonstration scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 5.1 Tivoli Workload Scheduler quick-start demonstration . . . . . . . . . . . . . . . 220 5.1.1 Create a job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 5.1.2 Create a new job from an existing job . . . . . . . . . . . . . . . . . . . . . . . 224 5.1.3 Create a job stream containing multiple jobs . . . . . . . . . . . . . . . . . 226 5.1.4 Schedule a job stream for automatic submission . . . . . . . . . . . . . . 234 5.1.5 Submit a job stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 5.1.6 Submit an ad hoc job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 5.1.7 Browse a job log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 5.2 Tivoli Workload Scheduler custom reports demonstration . . . . . . . . . . . 248 5.3 IBM Tivoli Dynamic Workload Broker V1.2 scenario . . . . . . . . . . . . . . . . 255 5.3.1 Resource optimization scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Contents
5.4 Tivoli Workload Scheduler V8.4 and Tivoli Dynamic Workload Broker V1.2 integration scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 5.4.1 Configuring Tivoli Workload Scheduler Bridge in the Tivoli Workload Scheduler environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 5.4.2 Integration scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Chapter 6. Event driven workload automation . . . . . . . . . . . . . . . . . . . . . 269 6.1 Event driven workload automation highlights . . . . . . . . . . . . . . . . . . . . . 271 6.2 Event driven workload automation logical design . . . . . . . . . . . . . . . . . . 271 6.2.1 The event driven workload automation concept . . . . . . . . . . . . . . . 272 6.2.2 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 6.2.3 Event rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 6.2.4 Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 6.2.5 Event providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 6.2.6 Action providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 6.3 Event driven workload automation implementation details . . . . . . . . . . . 284 6.3.1 Event driven workload automation topology . . . . . . . . . . . . . . . . . . 284 6.3.2 Event driven workload automation: high availability . . . . . . . . . . . . 287 6.3.3 Event driven workload automation: security . . . . . . . . . . . . . . . . . . 287 6.3.4 Event rule deployment process. . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 6.3.5 Communication among the event processor and agents . . . . . . . . 292 6.3.6 Important files and directories on the event processor . . . . . . . . . . 293 6.3.7 Important files and directories on the workstations . . . . . . . . . . . . . 294 6.3.8 Event providers implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 6.4 Working with event driven workload automation . . . . . . . . . . . . . . . . . . . 297 6.4.1 User interfaces interacting with event driven workload automation 298 6.4.2 Logging in to the Tivoli Dynamic Workload Console . . . . . . . . . . . . 298 6.4.3 Navigation to event driven workload automation portlets . . . . . . . . 299 6.4.4 Creating rules using the rule editor . . . . . . . . . . . . . . . . . . . . . . . . . 300 6.4.5 Changing the rule status to Complete . . . . . . . . . . . . . . . . . . . . . 324 6.4.6 Deploying and activating a rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 6.4.7 Querying the rule instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 6.4.8 Querying the triggered actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 6.4.9 Querying the Operator messages . . . . . . . . . . . . . . . . . . . . . . . . . . 336 6.4.10 Linking the Job Scheduling Console and the Tivoli Dynamic Workload Console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 6.4.11 Useful command-line interface commands . . . . . . . . . . . . . . . . . . 338 6.4.12 Event driven workload automation related global options . . . . . . . 340 6.4.13 Event driven workload automation related local options . . . . . . . . 342 6.4.14 Creating generic plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 6.4.15 Defining new events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 6.4.16 Tivoli Enterprise Console integration in detail . . . . . . . . . . . . . . . . 345
vi
6.5 Event driven workload automation demonstration . . . . . . . . . . . . . . . . . 360 6.5.1 Scenario 1: Simple notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360 6.5.2 Scenario 2: Trigger TWS Agents status . . . . . . . . . . . . . . . . . . . . . 389 6.5.3 Scenario 3: Submit a Job Stream when FTP transfer completes . . 397 6.5.4 Scenario 4: Trigger a shopping online transaction . . . . . . . . . . . . . 397 Part 3. Generic branch job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 Chapter 7. Generic branch job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 7.2 Branch job functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 7.2.1 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406 7.2.2 Branch job capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 7.2.3 Branch job design advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 7.3 Sample scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412 7.3.1 Scenarios based on condition type . . . . . . . . . . . . . . . . . . . . . . . . . 413 7.3.2 Simple branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 7.3.3 Long branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418 7.3.4 Multiple branch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 7.3.5 Parent abend. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427 7.3.6 Complex branch scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 7.3.7 Complex branch - Pattern . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432 7.3.8 Complex branch - negated pattern . . . . . . . . . . . . . . . . . . . . . . . . . 437 7.3.9 Complex branch - Pattern within pattern row . . . . . . . . . . . . . . . . . 442 7.3.10 Pattern within pattern row - negated . . . . . . . . . . . . . . . . . . . . . . . 447 7.3.11 Complex branch - Numeric value comparison . . . . . . . . . . . . . . . 452 7.3.12 Complex scenario - multiple conditions. . . . . . . . . . . . . . . . . . . . . 458 7.3.13 Additional string parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465 7.3.14 Scenarios based on action type . . . . . . . . . . . . . . . . . . . . . . . . . . 466 7.3.15 Pause/Release actions scenario . . . . . . . . . . . . . . . . . . . . . . . . . . 467 7.3.16 Multiple pause/release scenario . . . . . . . . . . . . . . . . . . . . . . . . . . 476 7.3.17 Signal action scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 7.3.18 Important scenario notes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 7.4 Working with the branch job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488 7.4.1 Branch job prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 7.4.2 Branch job shell script installation . . . . . . . . . . . . . . . . . . . . . . . . . . 489 7.4.3 Branch job definition and signal job definition in the database . . . . 493 7.4.4 Placing the branch job into the job stream . . . . . . . . . . . . . . . . . . . 503 7.4.5 Using the ABEND job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 7.4.6 Passing the input parameters to the branch job . . . . . . . . . . . . . . . 509 7.5 Working with the branch job parameters. . . . . . . . . . . . . . . . . . . . . . . . . 509 7.5.1 Putting a parameter into job stream Comments field . . . . . . . . . . . 511 7.5.2 Parameters reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
Contents
vii
7.5.3 Case sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 7.5.4 Sample condition examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520 7.6 Important notes about the branch job . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 7.7 Sample scenarios installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 7.7.1 Installation packages content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 7.7.2 Installation on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 7.7.3 Installation on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 7.8 Generic branch job script source code . . . . . . . . . . . . . . . . . . . . . . . . . . 545 Chapter 8. Installation of Cygwin onto a Windows master . . . . . . . . . . . 547 8.1 Selected installation approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549 8.2 Downloading Cygwin from the Cygwin Web site . . . . . . . . . . . . . . . . . . . 549 8.3 Transferring the installables to the master . . . . . . . . . . . . . . . . . . . . . . . 561 8.4 Performing the Cygwin installation on the master domain manager . . . . 562 8.5 Testing the Cygwin functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568 Part 4. Planning for a client engagement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 Appendix A. Planning for a client engagement . . . . . . . . . . . . . . . . . . . . 571 Services engagement preparation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572 Implementation skills . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572 Available resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572 Solution scope and components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 Basic solution definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574 Advanced solution definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574 Services engagement overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 Executive Assessment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576 Demonstration system setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577 Hardware and software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578 Analyze solution tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579 Creating a contract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Estimating time and activities of the engagement . . . . . . . . . . . . . . . . . . . . . 582 Perform environmental analysis and plan tasks . . . . . . . . . . . . . . . . . . . . 582 Plan the solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584 Implement the solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 Close the engagement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 Appendix B. Sample Statement of Work for a Tivoli Workload Automation solution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587 Building an operating system deployment solution . . . . . . . . . . . . . . . . . . . . 588 Executive summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 Solution description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 Assumptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589 Business Partner responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589
viii
Client responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589 Staffing estimates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 Testing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 Deliverables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591 Completion criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591 Appendix C. Generic branch job source code . . . . . . . . . . . . . . . . . . . . . 593 Appendix D. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615 Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615 Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616 System requirements for downloading the Web material . . . . . . . . . . . . . 616 How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616 Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617 Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619 IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619 Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619 Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 How to get Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
Contents
ix
Figures
1-1 1-2 1-3 1-4 1-5 1-6 2-1 2-2 2-3 2-4 IBM Tivoli Workload Automation portfolio . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Workload infrastructure solution scenario . . . . . . . . . . . . . . . . . . . . . . . . . 10 Tivoli Workload Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Tivoli Dynamic Workload Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 IBM Tivoli LoadLeveler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Enterprise Workload Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 An example Tivoli Workload Scheduler network with only one domain . . 21 Tivoli Workload Scheduler network with three domains . . . . . . . . . . . . . . 22 A multi-tiered Tivoli Workload Scheduler network. . . . . . . . . . . . . . . . . . . 23 A Tivoli Workload Scheduler network with the Job Scheduling Console client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 2-5 Tivoli Workload Scheduler interprocess communication with application server subsystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 2-6 JnextPlan creates the plan file for each production day . . . . . . . . . . . . . . 31 2-7 The distribution of the plan (Symphony file) in a Tivoli Workload Scheduler network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 2-8 Tivoli Workload Scheduler process flow . . . . . . . . . . . . . . . . . . . . . . . . . . 46 3-1 Tivoli Dynamic Workload Broker topology . . . . . . . . . . . . . . . . . . . . . . . . 56 3-2 Tivoli Dynamic Workload Broker server architecture . . . . . . . . . . . . . . . . 59 3-3 Job Execution Agent - architecture and interaction with server . . . . . . . . 67 3-4 Resource Advisor Agent - architecture and interaction with server . . . . . 69 3-5 Communication between the Tivoli Dynamic Workload Broker server and an agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 3-6 Resource wizard in Tivoli Dynamic Workload Console . . . . . . . . . . . . . . . 76 3-7 Tivoli Dynamic Workload Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 3-8 Job Brokering Definition Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 3-9 Context assistant - Computers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 3-10 Context assistant - Logical resources . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 3-11 Search for matching resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 3-12 Communication networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 3-13 Communication networks and used certificates . . . . . . . . . . . . . . . . . . . 97 3-14 Sample - interaction with firewalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 3-15 Client to server authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 3-16 Browser-ISC-TDWB server authentication w/ separate user registries 103 3-17 TDWB/TWS environment leveraging single sign-on . . . . . . . . . . . . . . . 106 3-18 Server Connection within Tivoli Dynamic Workload Console . . . . . . . . 108 3-19 Authentication with no shared user registry . . . . . . . . . . . . . . . . . . . . . 110 3-20 Authentication with shared user registry without single sign-on . . . . . . 111
xi
3-21 Authentication with shared user registry and single sign-on . . . . . . . . . 112 3-22 List of server components (WebSphere Management Console) . . . . . 120 3-23 A Tivoli Workload Scheduler network with subordinate Tivoli Dynamic Workload Broker agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 4-1 Installation setup language window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 4-2 Welcome window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 4-3 Installation choice window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 4-4 Type of Instance window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 4-5 The user name and password window . . . . . . . . . . . . . . . . . . . . . . . . . . 142 4-6 The workstation configuration window . . . . . . . . . . . . . . . . . . . . . . . . . . 144 4-7 Installation directory window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 4-8 Database selection window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 4-9 Database installation action window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 4-10 DB2 installation information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 4-11 DB2 database configuration window. . . . . . . . . . . . . . . . . . . . . . . . . . . 152 4-12 Summary window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 4-13 DB2 installation script selection window . . . . . . . . . . . . . . . . . . . . . . . . 154 4-14 Language selection window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 4-15 TDWC welcome window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 4-16 Installation choice window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157 4-17 Installation directory window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 4-18 Type of installation window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 4-19 Advanced Installation window 1 of 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 4-20 Advanced Installation window 2 of 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 4-21 Advanced Installation window 3 of 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 4-22 Administrative user credential window . . . . . . . . . . . . . . . . . . . . . . . . . 161 4-23 wasadmin roles window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 4-24 Summary window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 4-25 Successful installation window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 4-26 Language selection window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 4-27 Welcome window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 4-28 Installation directory window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 4-29 Shortcut window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 4-30 Summary window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 4-31 InstallShield finish window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 4-32 IBM Tivoli Dynamic Workload Broker launchpad . . . . . . . . . . . . . . . . . 169 4-33 Language selection window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 4-34 IBM Tivoli Dynamic Workload Broker welcome window . . . . . . . . . . . . 170 4-35 Installation directory window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 4-36 Installation choice window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 4-37 Custom installation window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 4-38 Database selection window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 4-39 Database connection box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
xii
4-40 4-41 4-42 4-43 4-44 4-45 4-46 4-47 4-48 4-49 4-50 4-51 4-52 4-53 4-54 4-55 4-56 4-57 4-58 4-59 4-60 4-61 4-62 4-63 4-64 4-65 4-66 4-67 4-68 4-69 4-70 4-71 4-72 4-73 4-74 4-75 4-76 4-77 4-78 4-79 4-80 4-81 4-82
Database customization window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 Application Server connection window . . . . . . . . . . . . . . . . . . . . . . . . . 177 Tivoli Dynamic Workload Broker port selection window . . . . . . . . . . . . 178 Tivoli Agent Manager information window . . . . . . . . . . . . . . . . . . . . . . 179 Advanced installation information window 1 of 2 . . . . . . . . . . . . . . . . . 179 Advanced installation information window 2 of 2 . . . . . . . . . . . . . . . . . 180 Restart Application Server window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 Installation summary window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 Summary of completed steps window. . . . . . . . . . . . . . . . . . . . . . . . . . 183 Installation Completed window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 DB2 Setup launchpad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 Db2 Setup Wizard window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Installation type window 1 of 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Installation type window 2 of 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Installation directory window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 User information window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 Instance configuration window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Instance configuration window 1 of 3 . . . . . . . . . . . . . . . . . . . . . . . . . . 191 Instance configuration window 2 of 3 . . . . . . . . . . . . . . . . . . . . . . . . . . 192 Instance configuration window 3 of 3 . . . . . . . . . . . . . . . . . . . . . . . . . . 192 DB2 tools catalog window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 SMTP Server configuration window . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 Operating system security window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Summary installation window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 Setup completed window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Welcome launchpad window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Welcome wizard window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Installation directory window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 Security enablement window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 Installation summary window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202 Installation result window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 First Step window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 Server started window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Language selection window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 Welcome installation window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 Installation directory window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 Summary installation window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 Installation completed window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 Welcome launchpad window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 Language selection window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 TDWC welcome window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 Installation choice window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 Identify WebSphere Application Server installation window . . . . . . . . . 213
Figures
xiii
4-83 WebSphere Update installer location window. . . . . . . . . . . . . . . . . . . . 214 4-84 Administrative credential window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 4-85 Wasadmin roles window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216 4-86 Summary window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 4-87 Successful installation window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 5-1 Creating a new job definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 5-2 Creating a new job definition: General properties . . . . . . . . . . . . . . . . . . 222 5-3 Creating a new job definition: Task properties . . . . . . . . . . . . . . . . . . . . 223 5-4 Creating a new job definition from an existing job definition . . . . . . . . . . 224 5-5 Creating a new job definition from an existing job definition: General properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225 5-6 Creating a new job stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226 5-7 Creating a new job stream: General properties . . . . . . . . . . . . . . . . . . . 227 5-8 Creating a new job stream: adding the first job to the job stream . . . . . . 228 5-9 Adding the first job to the job stream. . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 5-10 Creating a new job stream: one job created . . . . . . . . . . . . . . . . . . . . . 230 5-11 Creating a job stream: two jobs successfully added to the job stream . 231 5-12 Adding a dependency between two jobs in a job stream . . . . . . . . . . . 232 5-13 A job stream with two jobs and a dependency between the jobs . . . . . 233 5-14 Switching the job stream editor to the Run Cycle View. . . . . . . . . . . . . 234 5-15 Adding a run cycle to a job stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235 5-16 Adding a daily run cycle to select a job stream for execution every day of the week . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 5-17 Run Cycle View: displaying the effect of a run cycle. . . . . . . . . . . . . . . 237 5-18 Submitting a job stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 5-19 Submitting a job stream: finding the job stream to submit . . . . . . . . . . 240 5-20 The TEST-STREAM-1 job stream in the Ready status. . . . . . . . . . . . . 241 5-21 The TEST-STREAM-1 job stream in the Successful status . . . . . . . . . 241 5-22 The two jobs in TEST-STREAM-1, both in the Successful status. . . . . 241 5-23 Submitting an ad hoc job. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 5-24 Submitting an ad hoc job: General properties. . . . . . . . . . . . . . . . . . . . 244 5-25 Submitting an ad hoc job: Task properties . . . . . . . . . . . . . . . . . . . . . . 245 5-26 Browsing a job log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 5-27 Browsing a job log: the job log window . . . . . . . . . . . . . . . . . . . . . . . . . 247 5-28 Customize and generate reports for Tivoli Workload Scheduler . . . . . . 248 5-29 Creating a new task that generates a custom TWS Job Run Statistics Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 5-30 Creating a Job Run Statistics Report task: entering the basic task information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 5-31 Creating a Job Run Statistics Report task: configuration of the report header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251 5-32 Creating a Job Run Statistics Report task: specifying filter criteria . . . . 252 5-33 Running a newly-created custom report task . . . . . . . . . . . . . . . . . . . . 253
xiv
5-34 Running a custom report task: specifying scheduling engine details . . 254 5-35 Excerpt from the output of the custom report task . . . . . . . . . . . . . . . . 255 5-36 Logical resource view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 5-37 Hardware requirements view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 5-38 Software requirements view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 5-39 Job submission view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 5-40 Job instances view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 5-41 New Workstation window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 5-42 Logical resource view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 5-43 Job Brokering Definition Console view . . . . . . . . . . . . . . . . . . . . . . . . . 264 5-44 Physical memory assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 5-45 Job definition window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 5-46 Run cycle definition window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 5-47 Run cycle view window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 6-1 Event driven workload automation concept . . . . . . . . . . . . . . . . . . . . . . 272 6-2 Event rule life cycle - numbered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 6-3 Event rule life cycle schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 6-4 Event driven workload automation - topological view . . . . . . . . . . . . . . . 285 6-5 Tivoli Dynamic Workload Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299 6-6 Navigation to event driven workload automation portlets . . . . . . . . . . . . 300 6-7 Event Rule editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 6-8 Event rule General Information pane . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 6-9 Adding new objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 6-10 Working with object properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304 6-11 Events pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 6-12 Event correlation conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308 6-13 Event pane Correlate on option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 6-14 Actions pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311 6-15 Actions Pane - Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 6-16 Link between the selected object and Properties pane. . . . . . . . . . . . . 315 6-17 Properties pane for Event objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 6-18 Multiple filters -positive logic OR relationship . . . . . . . . . . . . . . . . . . . 318 6-19 Multiple filters -negative logic AND relationship . . . . . . . . . . . . . . . . . 318 6-20 Properties pane for Action objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 6-21 Using variables in the rule editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322 6-22 Changing rule status to Complete inside the rule editor . . . . . . . . . . . . 324 6-23 Getting list of defined event rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 6-24 Event rule list. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 6-25 Changing rule status to Complete outside the rule editor. . . . . . . . . . 326 6-26 Rule in Complete status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327 6-27 Active rule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 6-28 Querying the event rule instances -1 . . . . . . . . . . . . . . . . . . . . . . . . . . 330 6-29 Querying the event rule instances - 2 . . . . . . . . . . . . . . . . . . . . . . . . . . 330
Figures
xv
Querying the event rule instances -3 . . . . . . . . . . . . . . . . . . . . . . . . . . 331 Working with instance list - 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 Working with instance list - 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 Working with instance list - 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 Working with instance list - 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 Querying triggered actions - 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 Querying triggered actions - 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 Querying triggered actions - 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Querying triggered actions - 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Querying operator messages - 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 Querying operator messages - 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 Querying operator messages - 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 Linking the Job Scheduling Console and the Tivoli Dynamic Workload Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 6-43 Sample mapping of custom attributes. . . . . . . . . . . . . . . . . . . . . . . . . . 353 6-44 Simple notification scenario - 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 6-45 Simple notification scenario - 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 6-46 Simple notification scenario - 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 6-47 Simple notification scenario - 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 6-48 Simple notification scenario - 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366 6-49 Simple notification scenario - 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 6-50 Simple notification scenario - 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367 6-51 Simple notification scenario - 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 6-52 Simple notification scenario - 9 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 6-53 Simple notification scenario - 10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 370 6-54 Simple notification scenario - 11 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 6-55 Simple notification scenario - 12 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 6-56 Simple notification scenario - 13 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 6-57 Simple notification scenario - 14 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 6-58 Simple notification scenario - 15 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 6-59 Simple notification scenario - 16 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 6-60 Simple notification scenario - 17 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 6-61 Simple notification scenario - 18 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 6-62 Simple notification scenario - 19 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 6-63 Simple notification scenario - 20 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 6-64 Simple notification scenario - 21 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 6-65 Simple notification scenario - 22 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 6-66 Simple notification scenario - 23 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 6-67 Simple notification scenario - 24 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 6-68 Simple notification scenario - 25 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 6-69 Simple notification scenario - 26 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 6-70 Simple notification scenario - 27 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382 6-71 Simple notification scenario - 28 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
6-30 6-31 6-32 6-33 6-34 6-35 6-36 6-37 6-38 6-39 6-40 6-41 6-42
xvi
6-72 Simple notification scenario - 29 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 6-73 Simple notification scenario - 30 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 6-74 Simple notification scenario - 31 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 6-75 Simple notification scenario - 32 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385 6-76 Simple notification scenario - 33 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 6-77 Simple notification scenario - 34 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 6-78 Simple notification scenario - 35 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 6-79 Simple notification scenario - 36 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 6-80 FTA scenario - 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 6-81 FTA scenario - 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 6-82 FTA scenario - 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 6-83 FTA scenario - 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394 6-84 FTA scenario - 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 6-85 FTA scenario - 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 7-1 Purpose of the branch job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 7-2 Terms related to job stream definition . . . . . . . . . . . . . . . . . . . . . . . . . . . 408 7-3 Terms related to job stream run (concrete job stream instance). . . . . . . 409 7-4 Simple branch (SUCC) definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 7-5 Simple branch (SUCC) final status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 7-6 Simple branch (SUCC) commented joblog . . . . . . . . . . . . . . . . . . . . . . . 415 7-7 Simple branch (ABEND) definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 7-8 Simple branch (ABEND) final status . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 7-9 Simple branch (ABEND) joblog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 7-10 Long branch (SUCC) definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 7-11 Long branch(SUCC) final status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 7-12 Long branch(ABEND) final status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 7-13 Multiple branch jobs within one job stream . . . . . . . . . . . . . . . . . . . . . . 425 7-14 Parent abend (SUCC) definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428 7-15 Parent abend (SUCC) final status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428 7-16 Pattern scenario - definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 7-17 Pattern scenario final status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 7-18 Negated Pattern scenario definition . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 7-19 Negated Pattern scenario final status . . . . . . . . . . . . . . . . . . . . . . . . . . 439 7-20 Pattern within pattern row definition . . . . . . . . . . . . . . . . . . . . . . . . . . . 443 7-21 Pattern within pattern row final status . . . . . . . . . . . . . . . . . . . . . . . . . . 444 7-22 Pattern within pattern row negated definition . . . . . . . . . . . . . . . . . . . . 448 7-23 Pattern within pattern row negated final status . . . . . . . . . . . . . . . . . . . 449 7-24 Numeric comparison branch definition . . . . . . . . . . . . . . . . . . . . . . . . . 454 7-25 Numeric comparison branch final status . . . . . . . . . . . . . . . . . . . . . . . . 455 7-26 Complex condition definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 7-27 Complex condition final status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461 7-28 Pause/Release action definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 7-29 Pause/Release action status after first branch job . . . . . . . . . . . . . . . . 471
Figures
xvii
7-30 Pause/Release action after second branch job. . . . . . . . . . . . . . . . . . . 473 7-31 Multiple pause/release scenario definition . . . . . . . . . . . . . . . . . . . . . . 478 7-32 Signal action definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 7-33 Signal action state after the signal job . . . . . . . . . . . . . . . . . . . . . . . . . 482 7-34 Signal action state after the subsequent branch job . . . . . . . . . . . . . . . 484 7-35 Branch job definition on UNIX master domain manager - 1 . . . . . . . . . 495 7-36 Branch job definition on UNIX master domain manager - 2 . . . . . . . . . 496 7-37 Branch job definition on Windows master domain manager - 1 . . . . . . 498 7-38 Branch job definition on Windows master domain manager - 2 . . . . . . 499 7-39 Branch job suffix within the branch job alias . . . . . . . . . . . . . . . . . . . . . 504 7-40 Common placing of the branch job into the job stream. . . . . . . . . . . . . 505 7-41 Setting the flag Requires Confirmation for the first branch job . . . . . . . 507 7-42 Placing jobs into the job stream for the SIGNAL action scenario . . . . . 508 7-43 Parameters for multiple branch jobs within one job stream . . . . . . . . . 510 7-44 Sample scenarios - job definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 7-45 Sample scenarios - job stream definitions . . . . . . . . . . . . . . . . . . . . . . 537 7-46 Sample scenarios - job definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 7-47 Sample scenarios - job stream definitions . . . . . . . . . . . . . . . . . . . . . . 545 8-1 Cygwin home page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 8-2 Downloading the installation program . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 8-3 Selecting the directory for Cygwin bundle . . . . . . . . . . . . . . . . . . . . . . . . 553 8-4 Windows warning message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 8-5 Cygwin setup - 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554 8-6 Cygwin setup - 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555 8-7 Cygwin setup - 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556 8-8 Cygwin setup - 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557 8-9 Cygwin setup - 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 8-10 Cygwin setup - 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 8-11 Cygwin setup - 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560 8-12 Cygwin setup - 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561 8-13 Cygwin installation on master - 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562 8-14 Cygwin installation on master - 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 8-15 Cygwin installation on master - 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564 8-16 Cygwin installation on master - 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565 8-17 Cygwin installation on master - 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566 8-18 Cygwin installation on master - 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 8-19 Cygwin installation on master - 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
xviii
Tables
2-1 2-2 3-1 3-2 3-3 3-4 3-5 3-6 3-7 3-8 4-1 4-2 4-3 4-4 5-1 6-1 6-2 6-3 Options for tuning job processing on a workstation . . . . . . . . . . . . . . . . . 48 Maximum tweaked scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Command-line interface command list . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 List of Tivoli Dynamic Workload Broker authorization roles . . . . . . . . . . 104 Default server paths on Windows platform . . . . . . . . . . . . . . . . . . . . . . . 120 Default server paths on UNIX and Linux platforms . . . . . . . . . . . . . . . . . 121 Default agent paths on the Windows platform . . . . . . . . . . . . . . . . . . . . 121 Default agent paths on UNIX and Linux platforms . . . . . . . . . . . . . . . . . 122 Keystores for client network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Keystores for the agent network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Supported operating systems: abbreviations used . . . . . . . . . . . . . . . . . 132 Supported operating systems for the TWS engine . . . . . . . . . . . . . . . . . 133 Tivoli Workload Automation environment . . . . . . . . . . . . . . . . . . . . . . . . 136 Default ports used during installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Logical resource assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Events generated by the Tivoli Workload Scheduler Object Monitor . . . 281 Events generated by the File Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 Group membership necessary for event driven workload automation portlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 6-4 Tivoli Workload Scheduler security file objects for EDWA . . . . . . . . . . . 290 6-5 Important EIF related files and directories on event processor . . . . . . . . 293 6-6 Location of event and action plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 6-7 Important EIF related files and directories on workstations . . . . . . . . . . 295 6-8 Important monman configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 6-9 Conmon extensions: managing event driven workload automation . . . . 339 6-10 Composer extensions: managing event driven workload automation . . 339 6-11 Planman extensions: managing event driven workload automation . . . 339 6-12 General event driven workload automation related Global options. . . . 340 6-13 TEC Event Forwarder global options . . . . . . . . . . . . . . . . . . . . . . . . . . 340 6-14 Mail Sender global options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 6-15 Message Logger related Global options . . . . . . . . . . . . . . . . . . . . . . . . 342 6-16 Local options related to the event driven workload automation . . . . . . 342 7-1 Input parameters for the negative branch job scenario . . . . . . . . . . . . . . 430 7-2 Input parameters for the pattern job scenario . . . . . . . . . . . . . . . . . . . . . 436 7-3 Input parameters for the pattern job scenario . . . . . . . . . . . . . . . . . . . . . 441 7-4 Input parameters for the pattern within pattern row scenario . . . . . . . . . 446 7-5 Input parameters for negated pattern within pattern row scenario . . . . . 451 7-6 Input parameters for the Numeric comparison scenario . . . . . . . . . . . . . 457
xix
7-7 Input parameters for the complex condition scenario . . . . . . . . . . . . . . . 464 7-8 Input parameters for the pause/release scenario . . . . . . . . . . . . . . . . . . 475 7-9 Input parameters for the signal action scenario . . . . . . . . . . . . . . . . . . . 486 7-10 Parameters reference table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 7-11 Arithmetical operators explanation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 8-1 Solution task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576 8-2 Solution demonstration tasks for Tivoli Workload Scheduler . . . . . . . . . 577 8-3 Solution demonstration tasks for Tivoli Dynamic Workload Broker. . . . . 577 8-4 Skill adjustment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 8-5 Estimated time in hours for identified tasks. . . . . . . . . . . . . . . . . . . . . . . 582 8-6 Technical requirement: gathering sample questions. . . . . . . . . . . . . . . . 583 8-7 Time line estimates for implementation activities . . . . . . . . . . . . . . . . . . 585
xx
Examples
3-1 Submitting a job from the command-line interface . . . . . . . . . . . . . . . . . . 81 3-2 Default audit properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 6-1 Test of communication between TWS and TEC - successful . . . . . . . . . 347 6-2 Test of communication between TWS and TEC - unsuccessful . . . . . . . 347 6-3 Checking the TEC related global options . . . . . . . . . . . . . . . . . . . . . . . . 347 6-4 TWSEvent class available with the FP01 . . . . . . . . . . . . . . . . . . . . . . . . 348 6-5 Adjusted TWSEvent class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 6-6 Determining the current rulebase name . . . . . . . . . . . . . . . . . . . . . . . . . 351 6-7 Sample TEC rule used handling of custom attributes mapping . . . . . . . 354 6-8 Sample TEC rule working with the TWS event type . . . . . . . . . . . . . . . . 355 6-9 Determining the current rulebase name . . . . . . . . . . . . . . . . . . . . . . . . . 356 6-10 Determining the current rulebase name . . . . . . . . . . . . . . . . . . . . . . . . 358 6-11 Determining the current rulebase path . . . . . . . . . . . . . . . . . . . . . . . . . 358 6-12 Simple notification scenario - incoming e-mail . . . . . . . . . . . . . . . . . . . 387 7-1 Long branch (SUCC) joblog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420 7-2 Long branch (ABEND) joblog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 7-3 Parent abend (SUCC) joblog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429 7-4 Parent abend scenario parameters definition . . . . . . . . . . . . . . . . . . . . . 430 7-5 Pattern scenario joblog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 7-6 Pattern scenario parameters definition . . . . . . . . . . . . . . . . . . . . . . . . . . 436 7-7 Negated Pattern joblog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 7-8 Pattern scenario parameters definition . . . . . . . . . . . . . . . . . . . . . . . . . . 441 7-9 Example of parents joblog - 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 7-10 Example of parents joblog - 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 7-11 Pattern within pattern row branch joblog . . . . . . . . . . . . . . . . . . . . . . . . 444 7-12 Pattern scenario parameters definition . . . . . . . . . . . . . . . . . . . . . . . . . 446 7-13 Pattern within pattern row branch joblog . . . . . . . . . . . . . . . . . . . . . . . . 449 7-14 Negated pattern within pattern scenario parameters definition . . . . . . . 451 7-15 Example of parents joblog numeric value comparison . . . . . . . . . . . . . 453 7-16 Numeric comparison branch joblog. . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 7-17 Numeric comparison scenario parameters definition . . . . . . . . . . . . . . 457 7-18 Complex condition joblog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462 7-19 Complex condition scenario parameters definition . . . . . . . . . . . . . . . . 464 7-20 Pause/Release action - joblog of the 1st branch job. . . . . . . . . . . . . . . 472 7-21 Pause/Release action - joblog of the 1st branch job. . . . . . . . . . . . . . . 474 7-22 Pause/Release scenario parameters definition. . . . . . . . . . . . . . . . . . . 475 7-23 Signal action joblog of the 1st branch job . . . . . . . . . . . . . . . . . . . . . . . 483 7-24 Signal action - joblog of the 2nd branch job . . . . . . . . . . . . . . . . . . . . . 485
xxi
7-25 7-26 7-27 7-28 7-29 7-30 7-31 7-32 7-33 7-34 7-35 7-36 7-37 7-38 7-39 7-40 7-41 7-42 7-43
Complex condition scenario - parameters definition . . . . . . . . . . . . . . . 486 Content of the installation package for UNIX platforms . . . . . . . . . . . . 490 Content of the installation package for Windows platforms . . . . . . . . . 492 UNIX branch job definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500 Windows branch job definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 Sample parameter set put inside the separators . . . . . . . . . . . . . . . . . 512 Sample parameters definition for job stream with two branch jobs . . . . 512 Separator syntax for SIGNAL jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 Parameter index - incremental counter . . . . . . . . . . . . . . . . . . . . . . . . . 515 Parameter index - incremental counter . . . . . . . . . . . . . . . . . . . . . . . . . 516 Pause/Release scenario - parameters definition . . . . . . . . . . . . . . . . . 520 Single pattern search - parameters definition . . . . . . . . . . . . . . . . . . . . 521 Negated pattern search - parameters definition . . . . . . . . . . . . . . . . . . 521 Multiple pattern search - parameters definition . . . . . . . . . . . . . . . . . . . 522 Pattern search with numeric comparison - parameters definition . . . . . 523 Pattern search with numeric comparison - parameters definition . . . . . 523 Combination of pattern search / pause action - parameters definition . 524 Signal action combined with pattern search - parameters definition . . . 525 Combination of complex condition and pause action - parameters definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 7-44 Multiple branch jobs within one job stream - parameters definition . . . 527 7-45 Content of the installation package for UNIX platforms . . . . . . . . . . . . 532 7-46 Sample scenarios installation - UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . 534 7-47 Content of the installation package for Windows platforms . . . . . . . . . 538 7-48 Setting Cygwin path and launching bash . . . . . . . . . . . . . . . . . . . . . . . 540 7-49 Sample scenarios installation - Windows . . . . . . . . . . . . . . . . . . . . . . . 541 8-1 bash command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568 C-1 Generic branch job source code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594
xxii
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 user's 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. 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 PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 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 publication. 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. 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. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples 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. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs.
xxiii
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol ( or ), indicating US registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both: Redbooks (logo) AIX 5L AIX DB2 Universal Database DB2 Enterprise Workload Manager i5/OS IBM LoadLeveler Netcool OS/400 PartnerWorld Passport Advantage Redbooks System x System z Tivoli Enterprise Console Tivoli Management Environment Tivoli TME WebSphere z/OS
The following terms are trademarks of other companies: SAP R/3, SAP, and SAP logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries. Oracle, JD Edwards, PeopleSoft, Siebel, and TopLink are registered trademarks of Oracle Corporation and/or its affiliates. AMD, AMD Opteron, the AMD Arrow logo, and combinations thereof, are trademarks of Advanced Micro Devices, Inc. EJB, J2EE, Java, JavaScript, Solaris, and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Internet Explorer, Microsoft, Windows Server, Windows Vista, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Itanium, Intel logo, Intel Inside logo, and Intel Centrino logo are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Other company, product, or service names may be trademarks or service marks of others.
xxiv
Preface
IBM Tivoli Workload Scheduler and IBM Tivoli Dynamic Workload Broker are key products in the comprehensive, on demand IBM Tivoli Workload Automation portfolio. Tivoli Workload Scheduler is the IBM centralized job scheduler for distributed, mainframe, and end-to-end environments that allows you to do batch scheduling based on a calendar. Tivoli Dynamic Workload Broker extends Tivoli Workload Automation capabilities by providing dynamic optimization of workload processing based on the performance of the scheduling infrastructure and workload demands. In this easy-to-follow IBM Redbooks publication, we cover different scheduling scenarios with Tivoli Workload Scheduler V8.4 and Tivoli Dynamic Workload Broker V1.2 in distributed environments. We also discuss best practices for designing and implementing a scheduling solution for small, medium, and enterprise accounts. Finally, we cover the sales engagement planning for a Tivoli Workload Automation portfolio, including a sample statement of work. The primary audience for this section is Business Partners and pre-sales Systems Engineers working in this area. This book is a major reference for IT Specialists and IT Architects working in the Tivoli Workload Automation area.
The team that wrote this book

This book was produced by a team of specialists from around the world working at the International Technical Support Organization, Austin Center. Vasfi Gucer is a Project Leader at the ITSO, Austin Center. He worked for IBM Turkey for 10 years and has been with the ITSO Austin Center since January 1999. He has more than 12 years of experience in the areas of systems management, networking hardware, and software on mainframe and distributed platforms. He has worked on various Tivoli customer projects as a Systems Architect and Technical Project Manager. He writes extensively and teaches IBM classes worldwide on Tivoli software. He is also an IBM Certified Senior IT Specialist.
xxv
Giuseppe Grammatico is a Software Support Specialist working for Italy IMT in the Tivoli Customer Support team within IBM Global Technology Services. He has been working for IBM since 2002 and has strong skills in several Tivoli Product suites. During these years he has been involved in several projects implementing Tivoli solutions for IBM Clients in Italy, especially for Tivoli Workload Scheduler, Tivoli Management Framework, Tivoli Storage Manager, Tivoli Directory Servers, and Tivoli Identity Manager. In April 2006, Giuseppe was awarded a Professional Certification from IBM for Tivoli Workload Scheduler V8.2 Martin Lisy has been working for IBM since 1995. He is a Systems Management Specialist in the area of the Tivoli Enterprise Management Solutions. Martin has worked on various Tivoli customer projects as the Solution Designer and Implementor. His area of expertise is Tivoli Workload Scheduler, for which he has created various scripting functions that enhance the product capabilities. Martin is an IBM Certified Deployment Professional for Tivoli Workload Scheduler V8.2 and V8.3, an IBM Certified Deployment Professional for Tivoli Identity Manager V4.6, and an IBM Certified Deployment Professional for Tivoli Enterprise Console V3.9. He works with IBM enablement teams in the area of Workload Automation, where he is focusing on hands-on training development. Martin also participates on requirements definitions for new releases of Tivoli Workload Automation suite. He also develops Tivoli certification tests in this area. Martin holds an engineering degree in Computer Science from VSB-Technical University of Ostrava. Michael A Lowry is an IBM-certified consultant and instructor based in Stockholm, Sweden. He has 12 years of experience in the IT services business and has been with IBM since 1996. Michael studied engineering and biology at the University of Texas. He has seven years of experience with Tivoli Workload Scheduler and has extensive experience with IBM network and storage management products. He is also an IBM Certified AIX Support Professional. Thanks to the following people for their contributions to this project: Arzu Gucer International Technical Support Organization, Austin Center Jackie Biggs and Warren Gill IBM USA Arcangelo Di Balsamo, Silvia Bellucci, Vinicio Bombacino, Paolo Deidda, Xavier Giannakopoulos, Domenico Di Giulio, Franco Mossotto, Monica Ross, Andrea Tortosa IBM Italy
xxvi
Bohuslav Bezecny CEZData, s.r.o. Pavel Fruhauf PPF banka a.s.
Become a published author

Join us for a two- to six-week residency program! Help write a book dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You will have the opportunity to team with IBM technical professionals, Business Partners, and Clients. Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you will develop a network of contacts in IBM development labs, and increase your productivity and marketability. Learn more about the residency program, browse the residency index, and apply online at: ibm.com/redbooks/residencies.html
Comments welcome
Your comments are important to us! We want our books to be as helpful as possible. Send us your comments about this book or other IBM Redbooks in one of the following ways: Use the online Contact us review Redbooks form found at: ibm.com/redbooks Send your comments in an e-mail to: redbooks@us.ibm.com Mail your comments to: IBM Corporation, International Technical Support Organization Dept. HYTD Mail Station P099 2455 South Road Poughkeepsie, NY 12601-5400
Preface
xxvii
xxviii
Part 1
Part
Concepts and architecture

In this part, we introduce the Tivoli Workload Automation portfolio, focusing on the concepts and architectures of Tivoli Workload Scheduler V8.4 and Tivoli Dynamic Workload Broker V1.2 products.
Chapter 1.
Workload scheduling overview

IBM Tivoli Workload Scheduler and IBM Tivoli Dynamic Workload Broker are two key components in the comprehensive IBM workload automation portfolio. Before discussing these products specifically, and how to use them together in a combined solution, we thought it is best to give an overview of workload scheduling in general and the products that comprise the IBM workload automation family. In this chapter, we cover the following topics: Market trends and directions on page 4 Business solutions on page 5 Tivoli Workload Automation in action on page 7
1.1 Market trends and directions

The number of organizations replacing manual, time-consuming workload tasks with automated capabilities continues to increase at a rapid pace. This is done with good reason. When performed manually, these tasks can quickly overwhelm IT staff, increase overall costs, and have a negative effect on service level agreements (SLA). The adoption of Grid computing for business applications is expanding in various sectors, such as insurance, manufacturing, and financial industries. The Grid computing environment is a complex environment for business solutions that requires workload automation, job scheduling, and processing. It is complex to address the need for a central point of control to prioritize, manage, and integrate workloads with data for enterprise jobs. In addition to this complexity is the requirement to match computing resources to workload requests in a dynamic fashion without human intervention. Accuracy, efficiency, and flexibility are difficult to maintain. The market is evolving into a virtual computing environment where clustering, scheduling, and managing workload automation are needed within this virtual environment. Service execution becomes important for delivering operational services to the IT infrastructure and the enterprise. Traditional management tools such as a job scheduler, load balancer, and cluster manager can automate some of these activities. However, these tools leave IT organizations without the ability to automate, dynamically manage, or optimize service execution activities end-to-end across the enterprise. While the service execution process is straightforward, it is exceptionally difficult to manage. Management tools must be able to support business processes, enable planned changes to business processes and the IT infrastructure, adapt to unplanned changes in the IT infrastructure, maximize workload velocity, optimize the utilization of IT resources, adhere to stringent SLAs, and ensure compliance. Additional difficulties arise from trying to manage complex, heterogeneous applications and systems as well as processes across organizational silos. Finally, IT organizations that are already limited in resources must somehow deal with a growing number of mixed, interdependent, and often unpredictable workloads that need to be scheduled in real-time, near-real-time, or batch modes. Enterprises are embracing the service-oriented architecture (SOA) common programming methodology to provide business applications across heterogeneous platforms, operating systems, and data sources. There is the need to provide a batch-on-grid solution to improve business efficiency, utilize resources, reduce costs, and achieve service level agreements for job execution.
Workload automation solutions should be supported by SOA, an open framework that enables IT organizations to easily build, deploy, and integrate business and IT workload processes. SOA can be key to dynamically reconfiguring the delivery of services according to business demand, helping to foster innovation and better align IT to business goals. SOA also enables open interfacing for the simplified integration of workload automation into the application and systems management paradigms. As the market evolves, the requirements for a job scheduling solution evolve too. The traditional scheduling that uses a calendar-based production workload planning and batch job execution is changing. Business needs for new scheduling requirements for platform or application agnostic scheduling, a single consolidated view of all scheduling points, event-based scheduling, and the use of virtualization with Grid computing technology exists today. These requirements will continue to evolve into a service-based scheduling. These requirements follow a process-driven model within a dynamic topology that uses service-oriented architecture integration or adapters based on standards such as Web services. These challenges can be effectively addressed by a dynamic end-to-end workload automation solution that provides a virtual point of control to implement standardized service execution processes and support a SOA. Solutions should be designed to respond quickly to service demands and changes in the IT environment, balance computing costs and service levels, and improve utilization of IT capacity. The right management tools should be able to: Support business processes and policies. Enable planned changes to business processes and the IT infrastructure. Adapt to unplanned incidences in the IT infrastructure. Maximize workload velocity. Optimize the utilization of IT resources. Adhere to stringent service level agreements (SLAs). Ensure adherence to compliance and governance requirements.
1.2 Business solutions

Automating resource-intensive tasks like production workload scheduling will help reduce IT management complexity and lower your overall total cost of ownership (TCO). End-to-end workload automation helps you manage and coordinate up to hundreds of thousands of workloads by executing the correct workload at the correct time and in the correct sequence. By automating workloads, you can significantly increase throughput into existing IT resources while meeting strict service level agreements (SLAs) and easing compliance requirements. So as you automate repeatable processes, you can capture best
Chapter 1. Workload scheduling overview
practices and expertise, and then you can execute processes in a consistent, error-free manner. The benefits of this solution provide an efficiency to business processes for your enterprise. The results are increasing customer satisfaction, reducing or eliminating complaints from Business Partners, improving the brand or company image, increasing sales that positively impact the bottom line, and allowing the business to be more competitive or flexible in your industry. IBM Tivoli Workload Automation solutions enable you to centrally manage IT workloads with complex dependencies that span multiple applications, systems, and business units, which include mainframe, distributed, Grid, and high-performance computing environments. As a result, you can dynamically route workloads to the best available resources, in real time and in line with changing business demands.
1.3 IBM Tivoli Workload Automation portfolio

The IBM Tivoli Workload Automation solutions are designed to fit a wide range of enterprise requirements and needs. The IBM Tivoli Workload Automation family of products allows IT organizations to establish a virtual control point to build and automate a consistent, predictable, and scalable service execution process across the enterprise. These products consolidate enterprise-wide batch and event-triggered workloads that span multiple applications and systems, helping IT organizations efficiently control and manage cross-enterprise workloads. The Tivoli Workload Automation portfolio includes:
IBM Tivoli Workload Scheduler and IBM Tivoli Workload Scheduler for z/OS provide advanced workload planning and choreography services,
along with extensive calendar and event-triggering services for real-time, near-real-time, and batch workloads. They include open Java 2 Enterprise Edition (J2EE) and Web services interfaces to allow IT organizations to consolidate custom applications and services into the service execution process. They also include IBM Tivoli Dynamic Workload Console, which provides a single, Web-based point of control for the entire workload automation network, including the ability to manage workloads by exception, initiate actions, and generate reports. Tivoli Workload Scheduler for z/OS end-to-end is an additional scheduling feature of Tivoli Workload Scheduler and Tivoli Workload Scheduler for z/OS. With this feature, you can use the two scheduler products together to schedule workloads from your z/OS system and run jobs in both mainframe and distributed environments.
IBM Tivoli Workload Scheduler for Applications extends Tivoli Workload

Scheduler software by providing extensive awareness and interfacing to SAP, People Soft, and Oracle business applications. This allows IT organizations to consolidate ERP application workloads into the service execution process.
IBM Tivoli Dynamic Workload Broker further extends Tivoli Workload

Scheduler by matching and routing workloads to the best available resources in an on demand manner. Dynamic brokering is based on critical workload and critical path analysis, load requirements, IT resource availability, and business policies.
IBM Tivoli Workload Scheduler LoadLeveler delivers the ideal solution for
high-performance computing environments, such as financial modeling, research, or biotechnology simulations. It can be integrated with Tivoli Workload Scheduler networks through Tivoli Workload Scheduler for Virtualized Data Centers to allow enterprises to consolidate high-performance computing workloads with the service execution process.
IBM Tivoli Workload Scheduler for Virtualized Data Centers provides integration between IBM Tivoli Workload Scheduler and the Open Grid Services Architecture.
1.4 Tivoli Workload Automation in action

The IBM Tivoli Workload Automation portfolio provides a solution that combines the strengths of various products. This could be thought of as the Tivoli workload management solution set. This technical overview describes various product features and functions for the Tivoli Workload Automation portfolio for distributed solutions. The four products for distributed solutions reviewed in this section are Tivoli Workload Scheduler, Tivoli Dynamic Workload Broker, Tivoli Workload Scheduler LoadLeveler, and Enterprise Workload Manager, as shown in Figure 1-1 on page 8. Note: Enterprise Workload Manager is not a Tivoli branded product.
IBM Software Group | Tivoli software
Tivoli workload automation portfolio for distributed solutions
W orkload Scheduler
Batch scheduling, calendaring Workload planning Orchestration of jobs Centralized systems management Deadline scheduling
Dynamic W orkload Broker

Manages workload based on resource allocation policy
LoadLeveler
Enterprise W orkload Manager

Allocates resources in real time Meet business goals by policy Service contracts
Manages jobs across compute nodes
Parallel job scheduling Workload is defined by the Load balancing requirements of the job Jobs are assigned based on policy Resource pools are automatically detected Resource metering
QoS enforcement Job monitoring and control Thread level priorities Execution monitoring
Figure 1-1 IBM Tivoli Workload Automation portfolio
Tivoli Workload Scheduler is the centralized job scheduler that allows you to do batch scheduling based on a calendar. You would plan the workload with dependencies between jobs within a job stream over a future time period. This software will then execute, also known as orchestrate, these job streams and allow centralized management for successful or exception handling for unsuccessful job execution. If necessary, due to workload delays, deadline scheduling can be handled by the software. Tivoli Workload Scheduler can be specified to suppress, continue, or cancel a job or job stream processing for the desired results. Tivoli Dynamic Workload Broker manages the workload submitted to it based on a resource allocation policy. A policy is defined by the workload administrator by criteria of available resources. The Tivoli Dynamic Workload Broker server software determines what hardware has the available resources required by the job. Clustered systems pooled together have Tivoli Dynamic Workload Broker agents that communicate with the server. These agents automatically detect the current state of resources. The server then determines the system with the agent
that has the resources based on the policy requirements for the job. The job is assigned and run on this resource. When completed, the agent communicates the job status back to the server. Tivoli Workload Scheduler LoadLeveler (LoadLeveler) is a parallel scheduling system that matches each job's processing needs and priority with available resources and special instructions for maximum resource utilization. It can track the total resources used by each serial or parallel job and offers several reporting options to track jobs and utilization by user, group, account, or type over a specified time period. LoadLeveler offers job checkpointing and suspension with optional job cancellation, hold, and re-queue. These capabilities provide great flexibility in defining real-time job and resource priority control. It delivers tight control of resources so that it can limit the use of individual machines to specific times, users, or job classes, or can use machines only when the keyboard and mouse are inactive. LoadLeveler also provides a single point of control for effective workload management, offers detailed accounting of system utilization for tracking or chargeback, and supports high availability configurations. Enterprise Workload Manager is an implementation of policy-based performance management. The scope of management is a set of servers that you logically group into what is called an Enterprise Workload Manager Management Domain. The set of servers included in the Management Domain has some type of relationship, for example, the set of servers supporting a particular line of business. The line of business may consist of multiple business processes spread across a few servers or a thousand servers. There is a management focal point for each Enterprise Workload Manager Management Domain, called the Enterprise Workload Manager domain manager. The domain manager coordinates policy actions across the servers, tracks the state of those servers, and accumulates performance statistics on behalf of the domain. On each server (operating system) instance in the management domain there is a thin layer of Enterprise Workload Manager logic installed called the Enterprise Workload Manager managed server. From one perspective, the managed server layer is positioned between applications and the operating system. The managed server layer understands each of the supported operating systems, gathering resource usage and delay statistics known to the operating system. A second role of the managed server layer is to gather relevant transaction-related statistics from middleware applications. The application middleware implementations, such as WebSphere Application Server, understand when a piece of work starts and stops, and the middleware understands when a piece of work has been routed to another server for processing, for example, when a Web server routes a servlet request to a WebSphere Application Server.
The managed server layer dynamically constructs a server-level view describing relationships between transaction segments known by the applications with resource consumption data known by the operating system. A summary of this information is periodically sent to the domain manager, where the information is gathered together from all the servers in the Management Domain to form a global view. See Figure 1-2.
Workload Infrastructure Solution Scenario

generate_customer_price_list
1 2 3
The stream of work is required to execute in the predefined order, on certain days (for example two days before the end of each billing cycle), and in a limited amount of time Each task, or job can run on any system that is configured with its application(s)
Figure 1-2 Workload infrastructure solution scenario
10
Let us use a workload infrastructure solution scenario to understand how a job is handled differently using the Tivoli Workload Automation portfolio for distributed systems. The generate_customer_price_list is a stream of work made up of a series of jobs. This stream of work has a predefined order for which the jobs are required to run on a certain day in a limited amount of time. A job will run on a system that is configured with the resources and data to run the application software (see Figure 1-3).
Tivoli Workload Scheduler
1 2 3
Workload Scheduler
generate_customer_price_list::job1 generate_customer_price_list::job2
generate_customer_price_list::job2 on system blue2 after generate_customer_price::job1
Figure 1-3 Tivoli Workload Scheduler
Tivoli Workload Scheduler orchestrates work flows with calendaring, end-to-end dependency management, and fault tolerance. Correct dependency resolution is ensured, and production is automated with timelines, deadlines, and control. Each task, or job, is defined to only one system, and always runs there regardless of dynamic conditions. In this case, generate_customer_price_list::job2 will run only on system blue2, though other blue systems could be available or could better handle this job. Tivoli Workload
11
Scheduler schedules generate_customer_price_list:job2 to run. However, load balancing this job onto another blue system is done by another Tivoli Workload Automation product, as shown in Figure 1-4.
IB M S oftware G roup | T ivoli software
Tivoli D ynam ic W orkload Broker
1 2 3
W orkload Scheduler
Dynam ic W orkload Broker
generate_custom er_price_list::job1 generate_custom er_price_list::job2
generate_custom er_price_list::job2 on the best appropriate m achine in pool blue2 after generate_custom er_price_list::job1
Figure 1-4 Tivoli Dynamic Workload Broker
12
Tivoli Dynamic Workload Broker automatically discovers and chooses the best system for executing the job, based on current system parameters, such as availability, memory, disk, and CPU utilization. These parameters are defined in a policy used by Tivoli Dynamic Workload Broker. So when the generate_customer_price_list::job2 is scheduled to run, the best available system is selected from a pool of blue2 systems by the Tivoli Dynamic Workload Broker software policy. Therefore, Tivoli Workload Scheduler can schedule this job and Tivoli Dynamic Workload Broker determines at that time the best blue system to run that job, as shown in Figure 1-5.
Tivoli LoadLeveler
1 2 3
Workload Scheduler
Dynamic Workload Broker
2
Load Leveler
2 2
generate_customer_price_list::job1 generate_customer_price_list::job2 check_price_record2 check_price_record2 check_price_record2
job2::check_price_record runs on several systems in parallel
Figure 1-5 IBM Tivoli LoadLeveler
13
Tivoli LoadLeveler manages the complex message handling among multiple cluster nodes that simultaneously perform computations on massively parallel jobs. For example, generate_customer_price_list::job2 spawns three separate jobs to check a price record. These three check_price_record jobs run in parallel and are load balanced amongst a pool of blue2 systems under the direction of Tivoli LoadLeveler, as shown in Figure 1-6.
Enterprise Workload Manager
1 2 3
Workload Scheduler
Dynamic Workload Broker
Load Leveler
Enterprise Workload Manager
2 2 2
generate_customer_price_list::job1 generate_customer_price_list::job2 check_price_record2 check_price_record2 check_price_record2
Assign more I/O on system blue2 to job2::check_price_record2
Figure 1-6 Enterprise Workload Manager
Enterprise Workload Manager ensures that the systems with critical workload have the correct amount of system resources for high-priority applications. Predictive advice for compute node processing is done so that resources are made available to applications to meet service-level objectives. An important aspect of Enterprise Workload Manager is that all data collection and aggregation activities are driven by a common service level policy called the Enterprise Workload Manager Domain Policy. This policy is built by an administrator to describe the various business processes that the domain supports and the performance objectives for each process. In this example, the domain policy determines that system blue2 running the check_price_record2
14
job needs more I/O, so the Enterprise Workload Manager then assigns additional I/O resources.
1.4.1 Tivoli Workload Automation integration with IBM products

For additional capabilities, the Tivoli Workload Automation portfolio can be easily integrated with other IBM products: IBM Tivoli Enterprise Portal, a Web-based operations console, provides a high-level overview of the entire IT environment. IBM Tivoli System Automation for z/OS proactively manages automation, high availability, and performance for z/OS environments. IBM Tivoli System Automation for Multiplatforms provides high availability for business applications running in open environments. IBM Tivoli Business Systems Manager provides executive dashboards with knowledge of key business processes and real-time service level status from a single console. IBM Tivoli Service Level Advisor delivers automated support for SLAs. IBM Tivoli Provisioning Manager efficiently provisions and configures servers, operating systems, middleware, applications, and network devices. IBM Tivoli Storage Manager automates data backup and restore functions, supporting a broad range of platforms and storage devices, and centralizing storage management operations. IBM Workload Manager for z/OS, a component of the IBM z/OS operating system, can identify work requests based on service class definitions, sets performance goals for service classes, and assigns specific IT resource usage constraints to service classes. IBM Enterprise Workload Manager, a management product for distributed, open systems, identifies work requests based on service class definitions, tracks performance of work requests, and shifts computing resources as needed to achieve specified performance goals. IBM Service Management is a portfolio of products, services, and solutions that automate and manage critical IT processes and enable IT governance.
15
16
Chapter 2.
Tivoli Workload Scheduler concepts and architecture

This chapter discusses Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker in greater detail, and describes a solution that combines both products working together in unison. The following topics are discussed: Introduction to Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker on page 18 Overview of Tivoli Workload Scheduler on page 18 Overview of Tivoli Dynamic Workload Broker on page 18 Tivoli Workload Scheduler architecture on page 19 Tivoli Workload Scheduler batch processing process flow on page 45 Sizing of typical Tivoli Workload Scheduler deployments on page 50
17
2.1 Introduction to Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker
Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker are two separate products intended to address different types of workload requirements. We will describe how to use the two products separately and together. First of all, let us go into a bit of detail about how these two products work.
2.2 Overview of Tivoli Workload Scheduler

Tivoli Workload Scheduler is the enterprise scheduling application from IBM. It can run on almost every platform in common use today, including most varieties of UNIX and Windows. In addition, applications in the Tivoli Workload Scheduler suite run on mainframes (Tivoli Workload Scheduler for z/OS) and minicomputers (Tivoli Workload Scheduler Limited FTA for i5/OS). Using Tivoli Workload Scheduler for Applications, it also possible to integrate Tivoli Workload Scheduler with other enterprise applications like Oracle and SAP. Tivoli Workload Scheduler is a fault tolerant scheduling system. In the event of a loss of power or a network outage, Tivoli Workload Scheduler simply carries on where it left off once the affected resource is back up and running again. A Tivoli Workload Scheduler job is never allowed to run until all of its dependencies across the whole network have been met. Tivoli Workload Scheduler is a centralized scheduling system that integrates scheduling across all systems in the enterprise, allowing you to schedule a job on your SAP system after both a UNIX job and a mainframe job have completed, for example. Using Tivoli Workload Scheduler, you can set up complex dependencies on your jobs so that the workload schema reflects the way your business works.
2.3 Overview of Tivoli Dynamic Workload Broker

Tivoli Dynamic Workload Broker allows dynamic distribution of workload among clusters of systems. Some types of workload can be distributed among many different systems to spread the load across the deployed enterprise computing assets, and to speed up processing of critical jobs.
18
Obviously, this sort of dynamic workload distribution is not necessarily applicable to all jobs. For jobs that must always run on a specific system, Tivoli Dynamic Workload Broker is not really called for; in these cases, it is probably better just to run the jobs through Tivoli Workload Scheduler. Note: We will discuss Tivoli Dynamic Workload Broker in detail in Chapter 3, Tivoli Dynamic Workload Broker concepts and architecture on page 53. It is also possible to integrate Tivoli Dynamic Workload Broker with Tivoli Workload Scheduler, essentially by putting a Tivoli Dynamic Workload Broker network under the control of Tivoli Workload Scheduler. It is this combined solution that we will discuss further in 3.13, Combined Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker solution architecture on page 126.
2.4 Tivoli Workload Scheduler architecture

Tivoli Workload Scheduler helps you plan every phase of production. During the processing day, the Tivoli Workload Scheduler production control programs manage the production environment and automate most operator activities. Tivoli Workload Scheduler prepares jobs for execution, resolves interdependencies, and launches and tracks each job. Because jobs start running as soon as their dependencies are satisfied, idle time is minimized, and throughput is improved. Jobs never run out of sequence. If a job ends in error, Tivoli Workload Scheduler handles the recovery process with little or no operator intervention. Tivoli Workload Scheduler is composed of several components: Tivoli Workload Scheduler engine The Tivoli Workload Scheduler engine is installed on every non-mainframe workstation in the scheduling network (for example, UNIX, Windows, and OS/400 computers). When the engine is installed on a workstation, it can be configured to play a specific role in the scheduling network. For example, the engine can be configured to be a master domain manager, a domain manager, or a fault tolerant agent. In an ordinary Tivoli Workload Scheduler network, there is a single master domain manager at the top of the network. Tivoli Workload Scheduler database The Tivoli Workload Scheduler database stores all of the scheduling objects including jobs, job streams, and all of the dependencies defined on them. By default, Tivoli Workload Scheduler uses an integrated DB/2 database to store these data; however, they can instead be stored in an already-installed Oracle database if desired.
Chapter 2. Tivoli Workload Scheduler concepts and architecture
19
Tivoli Workload Scheduler connector An integrated version of IBM WebSphere Application Server Express provides communication between the Tivoli Workload Scheduler client interfaces (the command line, Job Scheduling Console, and TDWC) and the back-end Tivoli Workload Scheduler engine and database. Job Scheduling Console (JSC) Job Scheduling Console is the Java-based graphical user interface (GUI) for the Tivoli Workload Scheduler suite. The Job Scheduling Console runs on any machine from which you want to manage Tivoli Workload Scheduler plan and database objects. It provides, through the Tivoli Workload Scheduler connector, the functions of the command-line programs conman and composer. The Job Scheduling Console can be installed on a desktop workstation or mobile computer, provided Job Scheduling Console has a TCP/IP link with the machine running the Tivoli Workload Scheduler connector. Using the Job Scheduling Console, operators can schedule and administer Tivoli Workload Scheduler over the network. Tivoli Dynamic Workload Console Tivoli Dynamic Workload Console is based on Integrated Solutions Console (ISC), a Web-based console that provides the basis for a graphical user interface to several different Tivoli products. Tivoli Dynamic Workload Console is the interface for performing actions related to event-driven scheduling, and can also be used to generate custom reports. In the next sections, we will provide an overview of the Tivoli Workload Scheduler network and workstations, the topology used to describe the architecture in Tivoli Workload Scheduler, the Tivoli Workload Scheduler components, and the plan.
2.4.1 The Tivoli Workload Scheduler network

A Tivoli Workload Scheduler network is made up of the workstations, or CPUs, on which jobs and job streams are run. A Tivoli Workload Scheduler network contains at least one Tivoli Workload Scheduler domain, the master domain, in which the master domain manager is the management hub. It is the master domain manager that manages the databases and it is from the master domain manager that you define new objects in the databases. Additional domains can be used to divide a widely distributed network into smaller, locally managed groups.
20
In the simplest configuration, the master domain manager maintains direct communication with all of the workstations (fault tolerant agents) in the Tivoli Workload Scheduler network. All workstations are in the same domain, MASTERDM (see Figure 2-1).
MASTERDM
AIX
Master Domain Manager
FTA1
Linux
FTA2 OS/400
FTA3
Windows XP
FTA4
Solaris
Figure 2-1 An example Tivoli Workload Scheduler network with only one domain
Using multiple domains reduces the amount of network traffic by reducing the communications between the master domain manager and the other computers in the network. Figure 2-2 on page 22 depicts an example of a Tivoli Workload Scheduler network with three domains. In this example, the master domain manager is shown as an AIX system. The MDM does not have to be on an AIX system; it can be installed on any of several different platforms, including AIX, Linux, Solaris, HPUX, and Windows XP. This figure is only an example, and is meant to give an idea of a typical Tivoli Workload Scheduler network.
21
MASTERDM
AIX
DomainA
AIX
DomainB
Domain Manager DMB
HPUX
Domain Manager DMA
FTA1
Linux
FTA2 OS/400
FTA3
Windows XP
FTA4
Solaris
Figure 2-2 Tivoli Workload Scheduler network with three domains
In this configuration, the master domain manager communicates directly and only with the subordinate domain managers. The subordinate domain managers communicate with the workstations in their domains. In this way, the number of connections from the master domain manager are reduced. Multiple domains also provide fault tolerance: If the link from the master is lost, a domain manager is still able to manage the workstations in its domain and resolve dependencies between them. This limits the impact of a network outage. Each domain may also have one or more backup domain managers that can become the domain manager for the domain if the domain manager fails. Before the start of each new day, the master domain manager creates a plan for the next 24 hours. This plan is placed in a production control file named Symphony. Tivoli Workload Scheduler is then restarted throughout the network, and the master domain manager sends a copy of the Symphony file to each of the subordinate domain managers. Each domain manager then sends a copy of the Symphony file to the fault tolerant agents in that domain. Once the network has been started, scheduling events such as job starts and completions are passed up from each workstation to its domain manager. The domain manager updates its Symphony file with the events and then passes the events up the network hierarchy to the master domain manager. The events are then applied to the Symphony file on the master domain manager. Events from all workstations in the network will be passed up to the master domain manager.
22
In this way, the masters Symphony file contains the authoritative record of what has happened during the production day. The master also broadcasts the changes down throughout the network, updating the Symphony files of domain managers and fault tolerant agents that are running in full status mode. It is important to remember that Tivoli Workload Scheduler does not limit the number of domains or levels (the hierarchy) of a network. There can be as many levels of domains as is appropriate for a given computing environment. The number of domains or levels in the network should be based on the topology of the physical network where Tivoli Workload Scheduler is installed. Most often, geographical boundaries are used to determine divisions between domains. Figure 2-3 shows an example of a four-tier Tivoli Workload Scheduler network: 1. Master domain manager, MASTERDM 2. DomainA and DomainB 3. DomainC, DomainD, DomainE, FTA1, FTA2, and FTA3 4. FTA4, FTA5, FTA6, FTA7, FTA8, and FTA9
MASTERDM
AIX
DomainA
Domain Manager DMA
AIX
DomainB
Domain Manager DMB
HPUX
FTA1 HPUX
FTA2
Solaris
FTA3
AIX
DomainC
DMC
AIX
DomainD
DMD
AIX
DomainE
DME
Solaris
FTA4
Linux
FTA5 OS/400
FTA6
Win 2K
FTA7
Win XP
FTA8
AIX
FTA9 HPUX
Figure 2-3 A multi-tiered Tivoli Workload Scheduler network
23
2.4.2 Tivoli Workload Scheduler workstation types

For most cases, workstation definitions refer to physical workstations. However, in the case of extended and network agents, the workstations are logical definitions that must be hosted by a physical Tivoli Workload Scheduler workstation. There are several different types of Tivoli Workload Scheduler workstations: Master domain manager (MDM) The domain manager of the topmost domain of a Tivoli Workload Scheduler network. It contains the centralized database of all defined scheduling objects, including all jobs and their dependencies. It creates the plan at the start of each day, and performs all logging and reporting for the network. The master distributes the plan to all subordinate domain managers and fault tolerant agents. In an end-to-end scheduling network, the Tivoli Workload Scheduler for z/OS engine (controller) acts as the master domain manager. Domain manager (DM) The management hub in a domain. All communications to and from the agents in a domain are routed through the domain manager. The domain manager can resolve dependencies between jobs in its subordinate agents. The copy of the plan on the domain manager is updated with reporting and logging from the subordinate agents. Backup domain manager (BDM) A fault tolerant agent capable of assuming the responsibilities of its domain manager. The copy of the plan on the backup domain manager is updated with the same reporting and logging information as the domain manager plan. Fault tolerant agent (FTA) A workstation capable of resolving local dependencies and launching its jobs in the absence of a domain manager. It has a local copy of the plan generated in the master domain manager. It is also called a fault tolerant workstation. Standard agent (SA) A workstation that launches jobs only under the direction of its domain manager. Extended agent (XA) A logical workstation definition that enables one to launch and control jobs on other systems and applications. Tivoli Workload Scheduler for Applications includes extended agent methods for the following systems: SAP R/3, Oracle Applications, CA7, JES2, and JES3.
24
Figure 2-4 shows a Tivoli Workload Scheduler network with some of the different workstation types. Its important to remember that domain manager FTAs, including the master domain manager FTA and backup domain manager FTAs, are FTAs with some extra responsibilities. The servers with these FTAs can, and most often will, be servers where you run normal batch jobs scheduled and tracked by Tivoli Workload Scheduler. This means that these servers do not have to be servers dedicated for Tivoli Workload Scheduler work only. The servers can still do some other work and run some other applications. On the other hand, you should not choose to use one of your busiest servers as one of your Tivoli Workload Scheduler domain managers of first-level.
MASTERDM
AIX
Job Scheduling Console
DomainA
Domain Manager DMA
AIX
DomainB
Domain Manager DMB
Linux
FTA1 HPUX
FTA2
Solaris
FTA3
AIX
DomainC
DMC
AIX
DomainD
DMD
AIX
DomainE
Solaris
DME
FTA4
HPUX
FTA5 OS/400
FTA6
Win NT
FTA7
Win 2K
FTA8
AIX
FTA9 HPUX
Figure 2-4 A Tivoli Workload Scheduler network with the Job Scheduling Console client
2.4.3 Tivoli Workload Scheduler topology

The purpose of having multiple domains is to delegate some of the responsibilities of the master domain manager to other workstations and to provide extra fault tolerance. A domain manager helps during the initial distribution of the scheduling plan when a new plan file has been created on the master domain manager. Each domain manager accomplishes this by handling distribution of the plan to workstations in that domain. This means that the master must send the file only to each domain manager, and the domain
25
managers will handle distribution of the file from there. A domain manager also helps by resolving inter-workstation dependencies at the domain level. This increases fault tolerance because the domain manager can continue to resolve dependencies within the domain even if the master domain manager is temporarily unavailable, perhaps due to a network outage. Workstations are generally grouped into a domain together because they share a common set of characteristics. Most often, workstations will be grouped together into a domain because they are in close physical proximity to one another, for example, in the same office. Domains may also be based on organizational unit (that is, department), business function, or application. Grouping related workstations together in a domain reduces the amount of information that must be communicated between domains, and thereby reduces the amount of network traffic generated.
2.4.4 Tivoli Workload Scheduler components

Tivoli Workload Scheduler is comprised of several separate programs. Each program has a distinct function. This division of labor segregates networking, dependency resolution, and job launching into their own individual processes. These processes communicate among themselves through the use of message files (also called event files). Every event that occurs during the production day is handled by passing events between processes through the message files. A computer running Tivoli Workload Scheduler has several active Tivoli Workload Scheduler processes. They are started as a system service, by the StartUp command, or manually from the Job Scheduling Console.
Tivoli Workload Scheduler engine processes

The Tivoli Workload Scheduler engine is comprised of the programs that do the actual scheduling work, such as resolving dependencies and submitting jobs for execution. Essentially, the Tivoli Workload Scheduler engine programs are the Tivoli Workload Scheduler programs that have been around since the very early days of Tivoli Workload Scheduler, when Tivoli Workload Scheduler was mostly a command-line program. netman The network listener program. It is the netman program that initially receives all TCP connections. The netman program accepts an incoming request from a remote program, spawns a new process to handle the request, and, if necessary, hands the socket over to the new process. Started by the StartUp script.
26
writer
The network writer process that passes incoming messages from a remote workstation to the local mailman process (through the Mailbox.msg event file). Started by netman. The primary message management process. The mailman program reads events from the Mailbox.msg file and then either passes them to batchman (through the Intercom.msg event file) or sends them to a remote workstation. Started by netman. The production control process. Working with the plan (Symphony), batchman starts jobs streams, resolves dependencies, and directs jobman to launch jobs. Once the Symphony file has been created (at the beginning of the production day), batchman is the only program that makes changes to the Symphony file. Started by mailman. The job control process. The jobman program launches and monitors jobs. Started by batchman. The watchdog program. This program checks periodically to make sure that the application server is up and running. The monitoring manager program. This receives events about Tivoli Workload Scheduler scheduling events from the batchman program by way of the Monbox.msg message file. The monman then forwards monitored events to the event processor. The monman program also starts the ssmagent monitoring program. This program monitors the system infrastructure necessary for the smooth operation of Tivoli Workload Scheduler. This includes file system space and message file size. If predefined thresholds are met, say, the Tivoli Workload Scheduler file system reaches 90% of capacity or a message file reaches its maximum size, ssmagent will send an event to the event processor.
mailman
batchman
jobman appservman
monman
ssmagent
27
Tivoli Workload Scheduler application server subsystems

Since Version 8.3, Tivoli Workload Scheduler has implemented many functions through applications running inside WebSphere Application Server. Version 8.4 greatly expands the number of application server subsystems. Many new capabilities and features added in recent versions (since 8.3) are implemented through application server subsystems. CLI Model Web Conn Model A servlet that handles composer operations. An Enterprise Java Bean (EJB) that exposes interfaces for the management of Model Objects. It implements auditing and security on DB. It uses DAO Model to persist changes. Contains the implementation for the persistence of Tivoli Workload Scheduler objects in the RDBMS. A logical representation of a connection to the RDBMS. The subsystem that builds and keeps updated the long term plan used to manage cross plan dependencies among job and job streams. A servlet that handles planman operations. The subsystem responsible for the creation of production, trial, and forecast plans.
DAO Model Data Source LTP Planner
CLI Planner Web CP Planner
Symphony Creation DAO The subsystem that implements the low level operations to write Symphony records. Conn Plan An EJB responsible for querying objects from Symphony and for implementing actions on the current production plan. The subsystem that implements low level operations required by Conn Plan. The subsystem exposes Web services for integrating Tivoli Workload Scheduler in a Service-Oriented Architecture (SOA). Contains the implementation for the persistence of Tivoli Workload Scheduler event rules.
DAO Plan Plan Services Web
DAO Event Rule
Conn Event Rule Engine An EJB that exposes the API for querying Event Rule Instances, Action Run Instances, and Message Logs. Moreover, it offers services to WEB UI to describe installed plug-ins.
28
Conn Event Rule Deployment An EJB that exposes API to manage the deployment of the monitoring configuration files. Rule Builder This subsystem is responsible for building and making effective the configuration for the Event Correlator and for the building of monitoring configuration files for all Event Plug-ins.
Download Manager Keeps a depot of the bundles containing the monitoring configuration for the agents. EIF Listener Listens for events coming from monman, ssmagent, and sendevent. The event transport mechanism is the same as Tivoli Enterprise Console. The controller of the event listening and event correlation processes. This subsystem implements the persistence of event rule instances, action run instances, and message logs.
Event Processor DAO Log
Config Download Web A servlet that serves the requests coming from monman to deploy the monitoring configuration bundle. Event Correlator Event Plug-ins This subsystem is responsible for implementing event correlation and action triggering. Subsystems responsible for building monitoring. Configurations to be deployed to their matching monitoring subagents on target agents. Subsystems responsible for the execution of the appropriate actions in response to a given event rule.
Action Plug-ins
29
The Tivoli Workload Scheduler interprocesses communication through message files, as shown in Figure 2-5.
Operator input User interface
composer Changes to Database JSC/ Web UI CLI Model Web
Application server subsystems

Conn Model LTP Planner DAO Model Data Source
DB, plan & message les

TWS Database
TWS processes
Creation of Plan
planman
CLI Planner Web
CP Planner
Symphony Creation DAO
Symnew
conman start, stop & shut JSC/ Web UI conman Changes to Plan JSC/ Web UI Web UI startmon & stopmon conman Conn Plan DAO Plan
NetReq.msg Symphony
netman writer
Mailbox.msg
mailman
Intercom.msg
batchman
Plan Services Web
Courier.msg
jobman
Monbox.msg Query event rules, actions & messages Web UI Conn Event Rule Engine DAO Event Rule DAO Log Moncmd.msg
monman
ssmagent
EIF Listener Conn Event Rule Deployment Cong Download Web Download Manager Rule Builder Event Correlator
Event Processor
Event Plugins
Action Plugins
startappserv & stopappserv
conman
Appserverbox .msg
appservman
Figure 2-5 Tivoli Workload Scheduler interprocess communication with application server subsystems
2.4.5 Tivoli Workload Scheduler plan

The Tivoli Workload Scheduler plan is the to-do list that tells Tivoli Workload Scheduler what jobs to run, and what dependencies must be satisfied before each job is launched. The plan usually covers 24 hours. This period covered by the plan is sometimes referred to as the production day. The plan start time does not have to be midnight. Often, the plan will be created early in the morning or late in the afternoon. The time of day is up to you. The best time of day to create a new plan is a time when few or no jobs are expected to be running. A new plan is created at the start of the production day.
30
Creation of the plan

The JnextPlan script generates the new plan just prior to the start of each production day. The plan contains only the job scheduling objects (jobs, job streams, and so on) that are needed for the coming production day. The plan file Symphony is created based on the job scheduling objects defined in the Tivoli Workload Scheduler database. In addition, incomplete workload from the previous production day is added to the new plan. The purpose of the JnextPlan script is illustrated in Figure 2-6.
TWS Database
TWS Plan
Workstations
Job Streams
Jobs NT Users
JnextPlan
Symphony
Prompts Resources Calendars
The databases store the definitions of all scheduling objects.
The daily plan handles production during the 24-hour production day.
The JnextPlan script runs as the last job in the production day. It builds the following days plan (the Symphony file). Only the scheduling objects needed for that day are included in the plan.
Figure 2-6 JnextPlan creates the plan file for each production day
Distribution of the plan

Once the plan has been created, a copy is sent to all subordinate workstations. The domain managers then distribute the plan to their fault tolerant agents. The subordinate domain managers distribute their copies to all the fault tolerant agents in their domain and to all the domain managers that are subordinate to them, and so on down the line. This enables fault tolerant agents throughout the network to continue processing even if the network connection to their domain manager is down.
31
From the Job Scheduling Console or the command-line interface, the operator can view and make changes in the days production by making changes in the Symphony file. The distribution of the Symphony file from master domain manager, to domain managers and their subordinate agents, is shown in Figure 2-7.
MASTERDM
AIX
Master Domain Manager TWS plan
DomainA
AIX
DomainB
HPUX
Domain Manager DMA
Domain Manager DMB
FTA1
AIX
FTA2 OS/400
FTA3
Windows XP
FTA4
Solaris
Figure 2-7 The distribution of the plan (Symphony file) in a Tivoli Workload Scheduler network
Tivoli Workload Scheduler processes monitor the Symphony file and make calls to the operating system to launch jobs as required. The operating system runs the job, and in return informs Tivoli Workload Scheduler whether the job has completed successfully or not. This information is entered into the Symphony file to indicate the status of the job. This way the Symphony file is continuously updated with the status of all jobs: the work that needs to be done, the work in progress, and the work that has been completed.
32
2.5 Tivoli Workload Scheduler advanced customization

It is possible to customize Tivoli Workload Schedulers behavior to fit your operational requirements by changing Tivoli Workload Scheduler parameters. There are two kinds of parameters: Global options Local options Global options exist only on the master and backup master and affect how the plan (Symphony) is created. Local options, on the other end, reside on each Tivoli Workload Scheduler and affect the behavior of that workstation. In the following, we will discuss some of the important global and local options parameters and provide some best practice guidelines. For a complete list of these parameters, refer to Tivoli Workload Scheduler Planning and Installation Guide Version 8.4, SC32-1273. Note: Global and local options parameters for Event driven workload automation are discussed in 6.4.12, Event driven workload automation related global options on page 340 and 6.4.13, Event driven workload automation related local options on page 342, respectively.
2.5.1 Global options parameters

You can set global options using the optman command. Note that although the optman command can be run from anywhere with a connection to the database, it is used by the planning processes to create the Symphony by the current master. To view the values of the global options, use the following syntax: optman ls Notes: Most of the options require that you run JnextPlan before they take effect. When it is not necessary, it is indicated in the option description. To show help information about an option, use the following syntax: optman chg {optionName | optionShortName} Here optionName or optionShortName is the option that you want to view. To change the values of an option, use the following syntax: optman chg {optionName | optionShortName} = value
33
Here optionName or optionShortName can be the options that are listed in the following sections.
enCarryForward | cf
This is an option that affects how the stageman command carries forward job streams. Its setting determines whether or not job streams that did not complete are carried forward from the previous to the new production plan. The available settings for enCarryForward are yes, no, and all. The default setting is all. Important: The default value for this option was yes in versions earlier than V8.3. That is, uncompleted job streams are carried forward only if the Carry Forward option is enabled in the job stream definition. This default option is changed to all in Tivoli Workload Scheduler V8.4 and V8.3. That is, uncompleted job streams are carried forward, regardless of the value of the Carry Forward option in the job stream definition. It is also important to note that even if the new default is all, the migration of globalopts preserves the old value that the user has defined in the previous installation.
enCentSec | ts
Define how the security file is used within the network. Note: Centralized security is not relevant to an end-to-end scheduling environment. If it is set to yes, the security files of all the workstations of the network can be created and modified only on the master, and the Tivoli Workload Scheduler administrator is responsible for their production, maintenance, and distribution. If it is set to no, the security file of each workstation can be managed by its root user or administrator. The local user can run the makesec command to create or update the file. The default value is no.
34
Notes: Centralized security has the benefit of preventing the risk of someone tampering with the security file on a workstation, but the administrator still has the job of distributing the security file on workstations. Therefore, it is a difficult task to maintain. If an administrator distributes a new security to a fault tolerant agent (FTA), this must be followed by a relink of the FTA (to resend the Symphony file). Otherwise, this FTA cannot participate in the Tivoli Workload Scheduler network until the next start of the day, because its Symphony file points to the previous security file.
enDbAudit | da
Select whether to enable or disable database auditing. The valid values are 0 (zero) to disable database auditing, and 1 (one) to activate database auditing. Auditing information is logged to a flat file in the TWShome/audit/database directory. Each Tivoli Workload Scheduler workstation maintains its own log. For the database, only actions are logged in the auditing file, not the delta of the action. The default value is 0. Auditing is disabled by default when the product is installed. You can enable or disable the auditing feature by setting the value of global options: enDbAudit = 0|1 Tip: Auditing does not have much impact on performance, but it uses a lot of disk space. Therefore, ensure that you have sufficient disk space. To initiate database auditing, you must shut down Tivoli Workload Scheduler completely. When you restart Tivoli Workload Scheduler, the database audit log is initiated. Plan auditing takes effect when JnextPlan is run.
enListSecChk | sc
Enable list security check is an option that controls which objects in the plan the user is permitted to list when running a Job Scheduling Console (JSC) query or a conman show command. If set to yes, objects in the plan returned from a query or show command are shown to the user only if the user has been granted the list permission in the security file. For the database, this option takes immediate effect. For the plan, JnextPlan must be run for this option to take effect. The default value is yes.
35
Tip: If you set this option to yes, it affects the Job Scheduling Console functions for the users defined in the security file. Enabling list security affects performance slightly, therefore use this option with caution.
enPlanAudit | pa
Select whether to enable or disable plan auditing. The valid values are 0 to disable plan auditing, and 1 to activate plan auditing. Auditing information is logged to a flat file in the TWShome/audit/plan directory. Each Tivoli Workload Scheduler workstation maintains its own log. For the plan, only actions are logged in the auditing file, not the success or failure of any action. The default value is 1. Auditing is disabled by default when the product is installed. You can enable or disable the auditing feature by setting the value of global options: enPlanAudit = 0|1 To initiate plan auditing, you must shut down Tivoli Workload Scheduler completely. When you restart Tivoli Workload Scheduler, the database audit log is initiated. Plan auditing takes effect when JnextPlan is run.
enSwfaultTol | Sw
Select whether to enable or disable the fault tolerant switch manager. The valid values are yes and no. The default value is no. Tip: If you change the value to yes, it causes all of the FTAs to send every message to every FULLSTATUS FTA in the same domain. Therefore, enabling this option increases the network traffic.
ignoreCals | ic
Ignore calendars is a preproduction option that affects the operation of the compiler command. The setting of this option determines whether or not user calendars are copied into the new production control file. Enter yes to prevent user calendars from being copied into the new production plan (Symphony file). The default value is no. Tip: If you change the value to yes, this slightly reduces the size of Symphony. However, you will not be able to use calendars in the datecalc command.
36
startOfDay | sd
Enter the start time of the Tivoli Workload Scheduler processing day in 24-hour format: hhmm (0000-2359). The default value is 0600. Start of day is especially useful to specify the client business day, and to specify the night after a free day as free and not be considered part of the next working day. This version of Tivoli Workload Scheduler introduces a method of managing time zones across the network. It enables the application of the startOfDay, set on the master domain manager using the optman command line, on each workstation using the local time zone set on that workstation. In this version, you are no longer required to change the launch time of the FINAL job stream when you change this option. Tip: Set the start of day to the time of the day where there is the least amount of scheduling activity, such as early in the morning or late in the afternoon.
2.5.2 Local options parameters

Change local options individually in each FTA. These changes affect the settings only on that system. Set local options in the localopts file. For the changes to take effect, stop and restart Tivoli Workload Scheduler. A template file containing the default settings is located in TWShome/config/localopts. During the installation process, a working copy of the local options file is installed as TWShome/localopts unless you have specified a non-default location for netman. The localopts file is in TWShome. Update any options pertaining to netman in the localopts file in Netmanhome. The following lists some of the local options parameters.
bm check file
Specify the minimum number of seconds that batchman waits before checking for the existence of a file that is used as a dependency. The default is 120 seconds.
37
Tip: If you use many file dependencies in your job streams, decreasing the bm check file value might help speed up the file dependency resolution. But you must be careful because there is a trade-off between speed and CPU utilization. Unlike the other dependency checking, file dependency checking is an external operation to Tivoli Workload Scheduler. Tivoli Workload Scheduler relies on the operating system to do the checking. For this reason, it is the most expensive operation in terms of resource usage. This is also evident from the fact that Tivoli Workload Scheduler attempts to check the existence of a file only after all of the dependencies (for example, predecessor, time, or prompt dependencies) are satisfied. Also related to this topic is using qualified file checking for resolving multiple file dependencies. Multiple files dependencies are checked in the order that they are specified in either the job stream or job level of a job stream definition. If a file contains six file dependencies, with each one being followed by a , (comma), it checks for the first one. If the file exists, it then looks for the second one. If the first file does not exist, it keeps checking for the first file at the iteration specified in bm check. Tivoli Workload Scheduler does not look for any of the remaining seven files until the first file exists. This means that it is possible that files two through six can exist, but because file one does not exist, it does not check for the other files until file one is found. When file one exists, it then checks for each of the remaining files and it no longer checks for file one. For example, this means that if file one existed and is later removed, the job or job stream launches, even if file one no longer exists. To prevent this, you can use the qualifier with the AND modifier (a parameter when specifying the file dependency). For example, consider a case where you have a job waiting for six files: /var/tmp/incoming/file1 /var/tmp/incoming/file2 /var/tmp/incoming/file3 With the normal file dependency, it searches the first file found. However, you can perform a qualified file dependency as follows: OPENS "/var/tmp/incoming" (-f %p/file1 -a -f %p/file2 -a -f %p/file3) This has two significant advantages: The dependency is not satisfied until all six files exist at the same time. The checking is also more efficient, because one execution of the test command is done instead of six times as many.
38
bm check status
Specify the number of seconds that batchman waits between checking the status of an internetwork dependency. The default is 300 seconds. Tip: Set this number as very large if you have no internetwork dependencies.
bm check until
Specify the maximum number of seconds that batchman waits before reporting the expiration of an until time for a job or job stream. The default is 300 seconds. Tip: If you specify a value lower than the default setting (300), this might overload the system. Setting it lower gives quicker status for missed start times, but takes away from other throughput gains. If you set it lower than the value of Local Option bm read, the value of bm read is used in its place.
bm look
Specify the minimum number of seconds that batchman waits before scanning and updating its production control file. The default is 15 seconds. For more information about this parameter, see 2.6, Tivoli Workload Scheduler batch processing process flow on page 45.
bm read
Specify the maximum number of seconds that batchman waits for a message in the INTERCOM.MSG message file. If no messages are in queue, batchman waits until the timeout expires or until a message is written to the file. The default is 10 seconds. For more information about this parameter, see 2.6, Tivoli Workload Scheduler batch processing process flow on page 45.
bm stats
Specify on to have batchman send its startup and shutdown statistics to its standard list file. Specify off to prevent batchman statistics from being sent to its standard list file. The default is off. Tip: The bm stats option must remain off unless you are debugging service problems.
bm verbose
Specify on to have batchman send all job status messages to its standard list file. Specify off to prevent the extended set of job status messages from being sent to the standard list file. The default is off.
39
Tip: The bm verbose must remain off unless you are debugging service problems.
jm job table size

Specify the size (in number of entries) of the job table used by jobman. The default is 1024 entries. Tip: It is not necessary to set this larger unless you have more than 1,000 jobs running concurrently on this workstation.
jm look
Specify the minimum number of seconds that jobman waits before looking for completed jobs and performing general job management tasks. The default is 300 seconds. For more information about this parameter, see 2.6, Tivoli Workload Scheduler batch processing process flow on page 45.
jm nice
For UNIX and Linux operating systems only, specify the nice value to be applied to jobs launched by jobman. The default is 0. Tip: Set to a negative number if you want all jobs that are run by Tivoli Workload Scheduler to run at a higher kernel priority than normal; set to a positive number to run at a lower priority.
jm no root
For UNIX and Linux operating systems only, specify yes to prevent jobman from launching root jobs. Specify no to allow jobman to launch root jobs. The default is no.
jm read
Specify the maximum number of seconds that jobman waits for a message in the COURIER.MSG message file. The default is 10 seconds. Tip: You can set this number as low as 1, keeping in mind that the jobman process runs as root, and consumes more CPU the lower the number is set.
40
mm cache mailbox
Use this option to enable mailman to use a reading cache for incoming messages. In such a case, not all messages are cached, only those that are not considered essential for network consistency. The default is no. Tip: Tivoli Workload Scheduler is able to read groups of messages from the mailbox and put them into a memory cache. Access to disk through cache is much faster than direct access to disk. The advantage is more relevant if you consider that traditional mailman requires at least two disk accesses for every mailbox message. You can get a significant performance increase when networking is involved. A special mechanism ensures that messages considered essential are not put into a cache but are handled immediately. This prevents the loss of vital information in case of a mailman failure.
mm cache size
Specify this option if you also use the mm cache mailbox. The default is 32. Use the default value for small and medium networks. Use larger values for large networks. Tip: You can set the cache size to the maximum, especially for large networks. Note that the documentation says 512 is the maximum, but in our tests we found 32767 works.
mm response
Specify the maximum number of seconds that mailman waits for a response before reporting that a workstation is not responding. The minimum wait time for a response is 90 seconds. The default is 600 seconds. Tip: The mm response and mm retrylink options determine how long mailman waits for a workstation response before flagging it as not linked and retrying the link. These do not affect the overall performance and must be left at the default setting.
mm retrylink
Specify the maximum number of seconds that mailman waits after unlinking from a non-responding workstation before it attempts to link to the workstation again. The default is 600 seconds.
41
mm sound off
Specify how mailman responds to a conman tellop ? command. Specify yes to have mailman show information about every task that it is performing. Specify no to have mailman send only its own status. The default is no. Tip: If you set this option to yes, it causes mailman to write more messages to the logs, and therefore consumes more disk, memory, and CPU.
mm unlink
Specify the maximum number of seconds that mailman waits before unlinking from a workstation that is not responding. The wait time must not be less than the response time specified for the local option nm response. The default is 960 seconds. Tip: Similar to response and retry, leave this setting at the default value.
nm port
Specify the Transmission Control Protocol (TCP) port number that netman responds to on the local computer. This must match the Transmission Control Protocol/Internet Protocol (TCP/IP) port in the computer's workstation definition. It must be an unsigned 16-bit value in the range 1 to 65535 (values between 0 and 1023 are reserved for services such as File Transfer Protocol (FTP), TELNET, Hypertext Transfer Protocol (HTTP), and so on). The default is 31111.
nm read
Specify the maximum number of seconds that netman waits for a connection request before checking its message queue for stop and start commands. The default is 10 seconds.
nm retry
Specify the maximum number of seconds that netman waits before retrying a connection that failed. The default is 800 seconds. Tip: The nm read and nm retry settings do not have much overall effect. They only change the timeouts of starting, stopping, and retrying lost connections.
nm SSL port
This is the port used to listen for incoming SSL connections. This value must match the one defined in the secureaddr attribute in the workstation definition in the database. It must be different from the nm port local option that defines the port used for normal communication.
42
If you do not plan to use SSL, set the value to 0. The default is none. Tips: If you install multiple instances of Tivoli Workload Scheduler on the same computer, set all SSL ports to different values. In general, SSL encryption imposes a large processor usage on the communications over the network. Turn SSL on only for links that must be secure (but not for other links).
sync level
Specify the rate at which Tivoli Workload Scheduler synchronizes the information written to disk. This option affects all mailbox agents and is applicable to UNIX and Linux operating systems only. The values can be: Low This value enables the operating system to handle the speed of write access. It speeds up all processes that use mailbox files. Disk usage is notably reduced. If the file system is reliable, the data integrity must be assured anyway. Medium This value makes an update to the disk after a transaction is completed. This setting can be a good trade-off between acceptable performance and high security against loss of data. Write is transaction-based, data written is always consistent. High This value makes an update every time data is entered. The default is low (high was the default setting until Tivoli Workload Scheduler V8.3. With Tivoli Workload Scheduler V8.3, the default setting has been changed to low.) Tip: If you change the value to low, this causes the processes to retain messages in memory rather than flushing them to disk after every write. We suggest that you use the low setting, because Tivoli Workload Scheduler is an input/output (I/O) intensive application and it is best to leave the handling of I/O to the operation system. Use medium if you are risk averse. High is the least performing value.
43
tcp timeout
With this attribute for the netman process, specify the maximum number of seconds that mailman and conman wait for the completion of a request How long to wait for completion of a request on an unlinked workstation (such as start, stop, link, and so on) that is not responding. The default is 300 seconds.
thiscpu
Specify the Tivoli Workload Scheduler name of this workstation. When a switch is made between masters using the switchmgr command, the Symphony header value for thiscpu is overwritten by the thiscpu value in the localopts file. The default is thiscpu.
timeout
Specify the timeout in seconds when accessing using a remote command line. The default is 3600 seconds.
wr enable compression
Use this option on fault tolerant agents. Specify whether the fault tolerant agent can receive the Symphony file in compressed form from the master domain manager. The default is no. Tip: Starting with Tivoli Workload Scheduler Version 7.0, domain managers can distribute the Sinfonia file to their FTAs in compressed form. Each Sinfonia record is compressed by mailman domain managers, sent, and then decompressed by writer FTA. The size of a compressed Sinfonia record is approximately seven times smaller. It can be particularly useful when the Symphony file is huge and the network connection between two nodes is slow or not reliable (wireless area network (WAN)). If there are FTAs in the network that have versions earlier than Tivoli Workload Scheduler V7, the Tivoli Workload Scheduler domain managers can send Sinfonia files to these workstations in uncompressed form. We recommend that you set wr enable compression=yes if the Sinfonia file is 4 MB or higher and the network bandwidth is limited. Otherwise, the CPU time it takes to compress the file outweighs the benefits of compressing the file.
wr read
Specify the number of seconds that the writer process waits for an incoming message before checking for a termination request from netman. The default is 600 seconds.
44
Tip: Setting this value lower does not offer much benefit to overall performance.
wr unlink
Specify the number of seconds that the writer process waits before exiting if no incoming messages are received. The minimum is 120 seconds. The default is 180 seconds. Tip: Setting this value lower does not improve performance.
2.6 Tivoli Workload Scheduler batch processing process flow

To speed up job execution, perform some tuning on the parameters in the Tivoli Workload Scheduler localopts file. The purpose of this section is to explain how different options affect the Tivoli Workload Scheduler performance. Before you attempt to tune the Tivoli Workload Scheduler localopts parameters to speed up the launching of jobs and increase overall performance, it is necessary to understand the Tivoli Workload Scheduler process flow.
45
Figure 2-8 shows you the process flow that runs jobs defined in the daily plan (as opposed to ad hoc jobs submitted after the creation of the plan). Note that processes involved in event based scheduling are not included in the diagram.
Symphony file
2 1
BATCHMAN
scan
TWS
bm read
13
Job
job is completed ?
job is Yes executed ?
bm look
read
14
update
4
job can be executed
courier.msg JOBMAN
5
read
job can be executed
Yes job is completed?
Yes
8
jm read
launches the job job is completed
jm look
job is completed
9
mailbox.msg MAILMAN
10
intercom.msg
job is completed 12
read
11
mm read
job is completed
Figure 2-8 Tivoli Workload Scheduler process flow
The following list explains the steps shown in Figure 2-8: 1. Jobs that must be run on the current day are loaded into the Symphony file, which is created daily when Jnextplan runs. 2. Batchman periodically scans the Symphony file to determine which jobs are ready to be run. The scan period is determined by the localopts option bm look. 3. At this stage, batchman determines if a job can be run. 4. Batchman writes a message in the message queue, courier.msg, which is read by jobman.
46
5. Jobman periodically reads the courier.msg queue. If the queue is empty, it waits for jm read seconds before trying a second time. 6. Jobman finds a message from batchman instructing it to run a job. 7. Jobman launches the job. 8. Jobman monitors it for the job completion status, checking every jm look seconds. 9. When jobman determines that a job has been completed, it writes a message into the mailbox.msg queue. 10.Mailman reads the mailbox.msg every mm read seconds. 11.Mailman passes this information to batchman by writing a message into the intercom.msg queue. Batchman then reads from the intercom.msg queue. 12.If there is no job completed message in the intercom.msg queue, batchman waits for bm read seconds before it times out. 13.If it finds a message, batchman processes it and update the Symphony file. This completes the cycle. Table 2-1 on page 48 summarizes the roles of bm look, jm read, jm look, mm read, and bm read in optimizing the overall Tivoli Workload Scheduler performance. It shows the activities that you have to tune, the corresponding option that you can set in the localopts file, and how the changed value impacts performance.
47
Table 2-1 Options for tuning job processing on a workstation Activity Batchman periodically scans the Symphony file for jobs ready to be processed. Jobman accesses the Courier.msg file to see whether there are jobs that have to be launched. After launching a job, jobman checks periodically for job completion status. Mailman looks periodically in the Mailbox.msg for completed jobs. Batchman checks periodically in Intercom.msg for jobs that are complete so that it can update the Symphony file. Option bm look Impact on performance In all of these cases, a shorter time means more frequent scans, using more CPU resources, and impacting other processes that are running. However, it also means that for all activities, waiting time is kept to a minimum. If throughput is important and the workstation has plenty of memory, try shortening the times. A longer period between successive activities means jobs take longer to run, because there are longer waits for each activity. However, the reduced frequency of the scans means that more memory is available for jobs because less is being used by these monitoring activities. If your objective is to run the jobs as quickly as possible, and you are not concerned about how quickly the information about the completed jobs is distributed, you can reduce the wait periods for bm look and jm read, but increase the periods for the others. To speed up the overall job processing time (from initial job launch to the update with the completion status), you can also tune bm look, jm look, and mm read.
jm read
jm look
mm read bm read
If you decide to tune these settings, perform the following tasks: 1. Test the results in a test system before applying changes in your production environment. To get worthwhile results, the test environment must have the same characteristics as the production environment. 2. Modify only the parameters that are necessary. It is better to modify one at a time and thoroughly test the change in performance rather than changing all at once. 3. Make a backup copy of the localopts file to ensure that you can revert to the default options, if necessary. 4. Stop and start the agent to activate the changes applied to the localopts file.
48
2.6.1 Scenarios for this book

In our lab environment, we performed some tests to understand the effects of changing these parameters. In this section, we document the test results and our findings. Important: Note that these tests were specific to our environment, and that there is no guarantee that you will obtain the same results in your environment. We suggest that you limit the changes to the localopts parameters to only those that are necessary, and test the impact thoroughly on a test system before moving the changes to the production system.
Results of the tests

The following list provides the results of our tests: The most important parameter to tune to speed up just the launching of jobs is bm look. Reducing the value of bm look improves the time required to detect jobs that are ready to be launched. To speed up the overall execution time (from initial job launch to registering the completion status), tune either bm look, jm look, or mm read. This is because reducing the time too much can overload the system by requiring a greater amount of CPU or (I/O) time. First, we performed a maximum tweaked configuration test with the lowest settings possible to understand the effects of these parameters and create a baseline. Table 2-2 on page 50 shows the maximum tweaked values versus the standard ready-for-use configuration. The exception is that we used high for synclevel. However, the default in Tivoli Workload Scheduler was changed to low from high in previous versions. Note that this is not a realistic configuration in production environments due to the excessive resource utilization.
49
Table 2-2 Maximum tweaked scenario Parameters bm look bm read jm look jm read mm cache mailbox mm cache size sync level Maximum tweaked 1 1 1 1 yes 512 low Standard 15 10 300 10 no 32 high
In this scenario, we used 100 jobs running the UNIX env command combined into one job stream, with a single dependency on the previous job. In the standard configuration, the elapsed time from conman submit through the last job completion was 34 minutes, 4 seconds. With the maximum tweaked configuration, the elapsed time from conman submit through the last job completion was 3 minutes, 43 seconds. With the following set of values for bm look, bm read, and jm read, we obtained a good compromise between performance and resource utilization. This suggests that you can set bm look one second less than that of bm read and jm read: bm look = 4 bm read = 5 jm read = 5
2.7 Sizing of typical Tivoli Workload Scheduler deployments

It is important to deploy Tivoli Workload Scheduler on hardware that is appropriate for the amount of workload that is expected. The server that does most of the work in a Tivoli Workload Scheduler network is the master domain manager. There are two reasons for this. First, the master domain manager is the system where the plan is generated each production day. Plan generation can be CPU- and disk-intensive process. Plan generation time can become a limiting factor on insufficiently powerful systems. If the master domain manager is not fast enough (CPU and disk speed) to generate the plan in a reasonable amount of time (under a couple of minutes), the start of production day can end up being delayed.
50
Second, the master domain managers Symphony file receives updates from every workstation in the network. This means that several updates will be sent to the master domain manager and written to disk for every change in the life cycle of a job, regardless of where in the network the job runs. For these reasons, and because of the important role of the master domain manager, the master domain manager is usually the most important workstation, and one where capacity planning often becomes important. With this in mind, here are our recommendations, based on performance testing done by the development team: To run from 1,000 to 25,000 jobs per day on UNIX, we recommend a server with at least a 1.0 GHz processor, a minimum of 1 GB of RAM, plus plenty of hard disk space for temporary files. To run from 25,000 to 100,000 jobs per day on UNIX, we recommend a server with at least a 1.0 GHz processor, a minimum of 2 GB of RAM, plus plenty of hard disk space for temporary files. Obviously, workstations other than the master domain manager must be sized appropriately too. As with plan generation on the master domain manager, the number of jobs a workstation can run per day is essentially limited by the CPU and disk speed of the system.
2.8 What is new in Tivoli Workload Scheduler V8.4

The following list summarizes the new functions available with Tivoli Workload Scheduler V8.4: Event driven workload automation (EDWA) scheduling and notification capability that provides the following functions (See Chapter 6, Event driven workload automation on page 269 for a detailed discussion): Trigger the execution of Tivoli Workload Scheduler batch jobs and job streams based on the reception or combination of real-time events. Notify users when anomalous conditions happens in the Tivoli Workload Scheduler scheduling infrastructure or in the Tivoli Workload Scheduler batch scheduling activity. Allow calls to an external product from Tivoli Workload Scheduler when a particular event condition occurs in Tivoli Workload Scheduler.
51
Advanced reporting features through a Web Interface that provides the following new capabilities: Allows you to tune the workload of the workstations. Detect jobs with exceptions. Document daily or specific production plans. Web interface enhancements, such as: LDAP support that allows sign on between the Web UI and the Tivoli Workload Scheduler. Sharing of tasks among groups. SAP jobs submission. Generation of trial and forecast plans. Usability improvements. Integration with Tivoli Enterprise Portal that allows monitoring of Tivoli Workload Scheduler job and job stream events through the Tivoli Enterprise Portal Console. Monitoring and automatic restart of WebSphere Application Server that can automatically restart WebSphere Application Server based on customizable policies and allow you to monitor WebSphere Application Server status from conman, in addition to starting and stopping WebSphere Application Server locally and remotely from any user ID authorized to start and stop workstations. IPv6 support provided.
52
Chapter 3.
Tivoli Dynamic Workload Broker concepts and architecture

While the concepts of Tivoli Dynamic Workload Broker are easily understandable from an architectural perspective Tivoli Dynamic Workload Broker can be a complex application. In this chapter, we provide detailed descriptions of Tivoli Dynamic Workload Broker components and interactions among them. We also describe the user interfaces used for managing the workload across the IT environment. We focus especially on the following topics: What is new in Tivoli Dynamic Workload Broker 1.2 on page 124 Topological view on page 55 Server components on page 57 Tivoli Dynamic Workload Broker agent on page 65 Common Agent Services on page 69 Job and resource definitions on page 75 Tivoli Dynamic Workload Broker user interfaces on page 77
53
Security features on page 91 Web services interface on page 118 Physical location of Tivoli Dynamic Workload Broker components on page 119 In the beginning of this chapter, we highlight the most important features that are new in Tivoli Dynamic Workload Broker V1.2.
54
3.1 Topological view

This section discusses the Tivoli Dynamic Workload Broker architecture from the topological perspective. The central point of Tivoli Dynamic Workload Broker topology is the server, which manages its agents. The users interact with the server through user interfaces (also called clients). The main purpose of Tivoli Dynamic Workload Broker is to determine the best available resource for running each submitted job, submit the job, and manage its whole life cycle. Most of the logic necessary for accomplishing of this task is centralized on the server. After determining the best available resource, a job is submitted to the target system utilizing the Tivoli Dynamic Workload Broker agent. Each Tivoli Dynamic Workload Broker agent provides several services: launches/cancels jobs, returns job outputs, returns information about hosting system status, and so on.
Chapter 3. Tivoli Dynamic Workload Broker concepts and architecture
55
Figure 3-1 shows the Tivoli Dynamic Workload Brokers topology.
Figure 3-1 Tivoli Dynamic Workload Broker topology
Important: Tivoli Dynamic Workload Broker V1.2 natively supports both the IPv4 and IPv6 protocols.
56
3.2 Server components

In this section, we describe the server components of the Tivoli Dynamic Workload Broker. The Tivoli Dynamic Workload Broker server is an J2EE enterprise application installed into the IBM WebSphere Application Server. It uses a RDBMS as its persistent data storage. The core WebSphere enterprise application is named ITDWB, and from a logical point of view is divided into the following parts: Resource Repository Resource Advisor Job Dispatcher Job Repository Allocation Repository Tivoli Dynamic Workload Broker leverages the Common Agent Services (CAS) as its server-agent communications infrastructure. Tivoli Dynamic Workload Broker server integrates with Agent Manager, which is the server side of Common Agent Services. The Agent Manager is by default installed into the same instance of WebSphere Application Server as the Tivoli Dynamic Workload Broker server. The more detailed description of Common Agent Services is included in 3.4, Common Agent Services on page 69. Additional server components can be installed into WebSphere Application Server, where the Tivoli Dynamic Workload Broker server resides. They are: Tivoli Workload Scheduler Agent (Tivoli Dynamic Workload Broker component for integration with Tivoli Workload Scheduler (also known as TDWB/TWS Bridge agent)) Enterprise Workload Manager (EWLM) enablement Tivoli Provisioning Manager (TPM) enablement IBM Change and Configuration Management Database (CCMDB) enablement All the above listed components allow Tivoli Dynamic Workload Broker to integrate with other products. Installation of these components is optional. From the WebSphere Application Server perspective, only the Tivoli Workload Scheduler Agent (TDWB/TWS Bridge agent) is a separate enterprise application. The other integration components are installed directly into the ITDWB enterprise application. For more information about integrating Tivoli Dynamic Workload
57
Broker with other products, refer to Getting Started with Tivoli Dynamic Workload Broker Version 1.1, SG24-7442. By default, the TEPListener component is also installed. TEPListener is responsible for integration with IBM Tivoli Monitoring. This component is responsible for logging defined job states into a text file. This file can be observed by the IBM Tivoli Monitoring Universal Agent running on the same machine as the Tivoli Dynamic Workload Broker server. The job states can be displayed through the Tivoli Enteprise Portal. For more information about the integration of Tivoli Dynamic Workload Broker with IBM Tivoli Monitoring, refer to Getting Started with Tivoli Dynamic Workload Broker Version 1.1, SG24-7442. Tivoli Dynamic Workload Broker leverages RDBMS as its permanent data storage. In Tivoli Dynamic Workload Broker V1.2, the RDBMS may be either DB2 or Oracle. The RDBMS engine can either reside on the same machine as Tivoli Dynamic Workload Broker server, or can be installed on a separate system. The default name of the database created for the Tivoli Dynamic Workload Broker server is TDWB. This name can be changed at the installation time. The schema of server components is shown in Figure 3-2 on page 59.
58
Figure 3-2 Tivoli Dynamic Workload Broker server architecture
The list of default physical locations is included in 3.11, Physical location of Tivoli Dynamic Workload Broker components on page 119.
59
Note: Tivoli Dynamic Workload Broker does not necessarily have to be installed onto a fresh WebSphere Application Server. It can be installed to an existing WebSphere Application Server instance, but certain prerequisites must be met (for example, you might need a certain WebSphere Application Server version and patch level). Before using an existing instance of WebSphere Application Server, consult the corresponding IBM Tivoli Dynamic Workload Broker Installation and Configuration Guide Version 1.2, SC32-2282. For more details about installation scenarios and WebSphere Application Server instances involved, see 4.7.3, Installing WebSphere Application Server V6.1 on page 197.
3.2.1 Resource Repository

The important information about the IT environment (from a job brokering perspective) is stored in the Resource Repository. It contains the list of available computers, defined resources, and real-time performance of each managed resource. This data serves as the input for the Resource Advisor. Resource definitions and relations among various types of resources and resource groups are stored in tables within the database named TDWB. It is also possible to import resources that are already maintained by the Change and Configuration Management Database (CCMDB). Tivoli Dynamic Workload Broker imports resources from the Change and Configuration Management Database and uses them as logical resources in its environment. Refer to Getting Started with Tivoli Dynamic Workload Broker Version 1.1, SG24-7442 for more details about this topic.
3.2.2 Resource Advisor

Resource Advisor (RA) performs job resource matching. This means that it determines the best candidate for each job that is about to run. It uses complex evaluation methods to determine which currently available resource has the optimal capacity and meets all the necessary prerequisites for running a particular job. The main logic, what shall run where, is computed by the Resource Advisor. In general, a heterogeneous set of resources can be required to run a job. A job may need, for example, a certain operating system, a file system, specified number of CPUs, and access to a database. A job may also request multiple
60
instances of the same type of a resource. Only when all the requirements are simultaneously satisfied can the job be started. The resource-matching process has the objective to select only the most capable resource to send the job to be processed. The decision making is a very complex task that considers various different factors: Availability of consumable resources: Resources are logically consumed by jobs while they are executing. The resource-matching process assigns the job execution to capable resources only when there is a sufficient amount of consumable resources available. During the resource-matching process, the Resource Advisor considers that many different concurrent jobs may request a quantity of the same consumable attribute at the same time. Workload distribution process (prioritization): The job with higher priority is privileged for the assignment of available resources. The prioritization of jobs works as follows: When multiple jobs are competing for the same set of consumable resources, their priorities and job ages are considered. The job age represents the time, that is, how long the job waits for a resource. For jobs with a priority between 90 and 100, the allocation requests always resolved before jobs with a priority lower than 90, regardless of how long the other jobs have been waiting. The priority settings between 90 and 100 should only be used for critical jobs. For jobs with priorities lower than 90, the allocation requests are resolved based on their priority and the age of the job. If the job waits for resources, its priority is increased periodically. The longer the job waits, the more its priority grows. If the resources are not available at the submission time, three possibilities can occur: The resources will be released and the job can allocate them The jobs priority will be increased during the wait for resources state. The jobs priority will become higher than priority of other jobs with higher initial priorities. In this case, the allocation request of our job will be resolved. The timeout allowed for resource waiting expires and the job will not be launched
61
Optimization criteria: These criteria allow further evaluation when the resource matching has been performed. Optimization criteria refine the list of available targets, that has been determined during the previous phases. We discuss the optimization criteria in following section.
Optimization criteria
After evaluating the list of possible targets, the optimization criteria tries to resolve the one target, where the particular job will be submitted. In the following articles, we use the term power, which should characterize the properties of a particular target. By the term power we do not necessarily mean only the CPU power, but any property, that is being considered (like memory, disk, and so on). There are four optimization criteria, that can help you to refine the process, which should address the best possible target for running a job: Balance by number of running jobs (default) Implementation: Round robin algorithm Usage: We expect that many jobs with common resource usage will be submitted in a large number at once. In addition to this expectation, we know that the power of the possible target computers is similar. Resource Advisor balances the workload when large amounts of job submission requests appears at once. This algorithm prevents all the jobs from the job submission bunch going to only one computer. By utilizing the round robin algorithm, the Resource Advisor ensures the proper balancing of workload among the multiple computers fitting the job requirements. Balance based on optimization objective Implementation: Proportional Balancing Based On The Statistical Probability. Usage: We expect that many jobs are submitted constantly at an almost flat rate. In addition to this expectation, we know that the power of each possible target is very different. This optimization policy is often used for jobs with logical resources requirements (for example, licenses). When the jobs with this optimization policy are submitted at a steady and high submission rate (more than three or four per second), the Resource Advisor distributes jobs to targets according to their current power. The goal of this optimization policy is to normalize the usage of particular resource type. This statement is valid for resources that follow a similar behavior in a heterogeneous environment (for example, memory and disk)
62
rather than CPU. The improvement of CPU usage normalization is planned for future versions. Best available Implementation: No statistical probability is used in this case; the best fit available resource is determined. Usage: When the best fit is a strict requirement, we recommend using this approach when the job's requirements are static and do not change over time. If the best computer is not available, then the nearest cheapest computer is selected. The typical reason for this optimization policy is to use the resource with the lowest cost. Typical examples are cost related tasks, that is, jobs that consume money during their run (energy consumption, air condition, and so on) and must be sent to the computer that will do the job most efficiently in terms of cost. Another examples of best fit resources are the requirements for NumberOfProcessors, TotalMemory, and so on. The best available optimization policy can be also used instead of proportional balancing when the updates about the state of the involved computers are configured at higher rate than the default value. Enterprise Workload Manager (EWLM) driven workload distribution Implementation: EWLM integration. Usage: Determines that the best target is passed to EWLM, which uses its own algorithm to distribute the workload.
3.2.3 Job Dispatcher

Job Dispatcher is responsible for managing requests for job submissions. It extracts the resource requirements of the job and passes them to the Resource Advisor. The resource requirements get converted into resource allocation requests. After identifying the best fitting resource, Job Dispatcher submits the job to that resource. At this moment, Job Dispatcher manages the jobs life cycle. Through its agent counterpart (called Job Execution Agent), the Job Dispatcher monitors the state of the job, gets the jobs status, and interacts with the job based on user inputs, and either displays the jobs stdout or cancels the job upon the users request.
63
3.2.4 Job Repository

The Job Repository keeps three types of data: Job definitions Job definitions that were created through: Tivoli Dynamic Workload Console Job Brokering Definition Console Imported through a command-line interface from a JSDL file Imported through the direct Web service invocation (custom application) Note: For more information about job definitions, see 3.5.1, Job definitions on page 75. Job instances Job instances resulting from: Jobs submitted from the Tivoli Dynamic Workload Console Jobs submitted to the Tivoli Dynamic Workload Broker from Tivoli Workload Scheduler Jobs submitted to the Tivoli Dynamic Workload Broker through the command-line interface Historical data Historical data describing how the previous job instances ran. The Job repository is physically represented as a couple of tables within the RDBMS. In Tivoli Dynamic Workload Broker V1.2, the RDBMS may be either DB2 or Oracle.
3.2.5 Allocation Repository

The Allocation Repository keeps data about the current resources allocation. The data within Allocation Repository is maintained by the Resource Advisor. The Allocation Repository is used to store the identifiers of the resources matched for a job. The quantities of consumed resources are kept in a cache. When the job terminates for any reason, the allocation information is removed from the Allocation Repository.
64
3.3 Tivoli Dynamic Workload Broker agent

The Tivoli Dynamic Workload Broker agent is responsible for handling requests coming from the server. The Tivoli Dynamic Workload Broker agent runs as a subagent of the Common Agent. This term is explained in 3.4, Common Agent Services on page 69. The Tivoli Dynamic Workload Broker agent leverages the Common Agent Services architecture. It is not necessary to understand Common Agent Services at this point to understand the Tivoli Dynamic Workload Broker agent functions. For an overview of Common Agent Services, see 3.4, Common Agent Services on page 69. The information included in this chapter will help you better understand how secure communication between the Tivoli Dynamic Workload Broker server and the Tivoli Dynamic Workload Broker Agent is performed. The Tivoli Dynamic Workload Broker agent runs under the user account that was specified during installation. This account is also the default user ID, which is used for running the job on the target system when a job is submitted to the agent and no user ID and password were explicitly specified in the job definition. The only exception to this behavior is on the Windows platform, when the Tivoli Dynamic Workload Broker agent is installed under the Local System account. In this case, jobs without an explicit user ID and password definition run under the default administrators account. Note: This only applies to Windows since there is no concept of a local system account in UNIX. On UNIX platforms, the agent runs under the nobody account, and jobs without explicit credential definitions are submitted under the root account. The Tivoli Dynamic Workload Broker agent itself consists of two major components. Each of these major components splits into subcomponents.
3.3.1 Agent components

The Tivoli Dynamic Workload Broker agent is responsible for performing two major tasks: handling the jobs submitted to the agent and providing information about the hosting machine. There are two components that perform these tasks: Job Execution Agent: Responsible for launching and cancelling jobs on the target system (the system where the agent resides) and tracking jobs states. A detailed architecture is shown in Figure 3-3 on page 67.
65
Resource Advisor Agent: Responsible for gathering information about the machine where it runs. It maintains information about the current machines utilization (CPU and memory), available disk space, and so on. A detailed architecture is shown in Figure 3-4 on page 69.
3.3.2 Agent subcomponents

Both the Job Execution Agent and the Resource Advisor Agent are further split into second-level subcomponents: Job Execution Agent Native Job Executor: Launches jobs in the operating systems environments (batch files, scripts, and executables) J2EE Job Executor: Launches jobs within J2EE Enterprise Java Beans (EJB) invocation Java Message Services (JMS) posting
66
The schema of a Job Execution Agent and the corresponding server counterpart is shown in Figure 3-3.
Figure 3-3 Job Execution Agent - architecture and interaction with server
Resource Advisor Agent Base scanners: Subcomponents responsible for scanning values from the hosting operating system. Scanners collect data about: Computer system Operating system Network addresses File systems Any defined logical resource
67
Scanners are based on Common Inventory Technology (CIT). The Common Inventory Technology originates from many sources (such as refactored code available from the Inventory part of Tivoli Configuration Manager, Tivoli License Manager, and others). The features of the Common Inventory Technology are: It is a common technology for hardware and software recognition and data collection. It can be used by Tivoli products that need information about the target systems hardware and software configuration. It permits sharing of recognition functionality and data among Tivoli products. It provides a consistent view of hardware and software configuration information across Tivoli products. It coordinates collection activities among Tivoli products. It converges on a standard, common data model. The schema of the Resource Advisor Agent and the corresponding server counterpart is shown in Figure 3-4 on page 69.
68
Figure 3-4 Resource Advisor Agent - architecture and interaction with server
3.4 Common Agent Services

This section describes the purpose and the architecture of the Common Agent Services. Common Agent Services (CAS) is a shared infrastructure for managing the computer systems in your environment. Multiple products can share the Common Agent Services infrastructure if they require the same Common Agent Services version. Common Agent Services consists of three main components: Common Agent is the shared agent used by other application agents (such as Tivoli Dynamic Workload Broker agent). The common agent is in fact a host for the other application agents. Application agents are installed as a subagents of the Common Agent.
69
Agent Manager is a central point of Common Agent Services. This manages the Common Agents and integrates with other applications. This registers the other application servers as Resource Managers. Resource Manager is a logical representation of the integrated application in the Agent Manager. From the Agent Managers perspective, the Resource Manager represents the server of the integrated application. The Tivoli Dynamic Workload Broker server is one of many possible Resource Managers that can be registered in the Agent Manager. We explain these components more in detail in the following subsections. Common Agent Services is just an infrastructure for other Tivoli products. By itself it does not perform any systems management tasks. It only offers a set of shared functions (such as shared libraries and secure communication) for the integrated product. Multiple Tivoli products leverage the Common Agent Services infrastructure. Be aware that different versions of each product may require a different version of Common Agent Services. We provide a sample list of Tivoli products leveraging the Common Agent Services infrastructure: Tivoli Dynamic Workload Broker Tivoli Provisioning Manager for Software Total Storage Productivity Center for Fabric Total Storage Productivity Center for Data Note: Do not confuse Common Agent Services with Tivoli Management Environment (TME, also known as the Tivoli Framework). These two infrastructures are based on completely different code bases. Tivoli Common Agent is not the Tivoli Endpoint, and Agent Manager is not a Tivoli Management Region (TMR) server.
3.4.1 Agent Manager

Agent Manager is the central point of a Common Agent Services infrastructure. It acts as the integration point among the application servers (such as Tivoli Dynamic Workload Broker server) and Common Agents. Agent Manager has the following properties: Has its own Certification Authority for issuing certificates. Maintains the list of revoked certificates (CRL).
70
Issues certificates for newly installed Common Agents. At registration time, it creates the certificate with the private key and distributes it together with CRL to the new Common Agent. Issues certificates for new Resource Managers. At registration time, it creates the certificate with the private key and distributes it to the new Resource Manager. The Tivoli Dynamic Workload Broker server must have a certificate signed by Agent Managers certification authority to be able to communicate with Common Agents and thus with the Tivoli Dynamic Workload Broker subagents hosted by Common Agents. Note: Agent Manager leverages RDBMS as its persistent storage. In Tivoli Dynamic Workload Broker V1.2, the RDBMS may be either DB2 or Oracle. Agent Manager can use the same RDBMS engine as the Tivoli Dynamic Workload Broker server, or can use another RDBMS engine. This depends on your deployment scenario. If you want the Agent Manager to use a different RDBMS instance, you need to install the Agent Manager separately from the Tivoli Dynamic Workload Broker server. If you install Agent Manager together with the Tivoli Dynamic Workload Broker, both Agent Manager and Tivoli Dynamic Workload Broker server will use the same RDBMS engine.
3.4.2 Common Agent

Common Agent is a shared run time that runs on each managed system leveraging the Common Agent Services architecture. The Common Agent lets multiple management applications share resources when managing a system and provides them with remote deployment capability, management, and security. One of the possible managing applications is Tivoli Dynamic Workload Broker. Common Agent is in fact a host for the other applications agents. An agent of a managing application is installed as a subagent of the Common Agent. Subagents use the Common Agents shared libraries and certificate for establishing secure communication with the corresponding server counterpart. Each Common Agent must first register to the Agent Manager to acquire the valid certificate. Only with the valid certificate is the Common Agent (and all of its subagents) able to communicate with other parties within the Common Agent Services infrastructure. Be aware that the different versions of each integrated application may require different versions of the Common Agent.
71
3.4.3 Interaction between Tivoli Dynamic Workload Broker and Common Agent Services
The Tivoli Dynamic Workload Broker server is registered within the Agent Manager as a Resource Manager. Agent Manager issued a certificate for the Tivoli Dynamic Workload Broker server at registration time. The Tivoli Dynamic Workload Broker server registers to Agent Manager when one of these two events occurs: A user wants to see the list of agents known by the Agent Manager (through the Tivoli Dynamic Workload Console interface). The Tivoli Dynamic Workload Broker server needs to connect to its agent. Tivoli Dynamic Workload Broker leverages the Common Agent Services infrastructure for two main purposes: The Common Agent Services infrastructure provides secure communication through SSL. The communication between the Tivoli Dynamic Workload Broker server and the Tivoli Dynamic Workload Broker Agent (which is in fact Common Agents subagent) goes directly from the Tivoli Dynamic Workload Broker server to the Tivoli Dynamic Workload Broker agent. Agent Manager is not involved in the traffic between the Tivoli Dynamic Workload Broker server and Tivoli Dynamic Workload Broker agents. Agent Manager was necessary at registration time when it issued certificates either for the Tivoli Dynamic Workload Broker server (registered in Agent Manager as a Resource Manager) or for the Common Agent hosting the Tivoli Dynamic Workload Broker subagent. Both the Tivoli Dynamic Workload Broker server and the agent use certificates issued by the same certification authority and are able to perform mutual SSL handshakes and establish a secure communication channel. After the SSL channel has been established, the incoming traffic from the Tivoli Dynamic Workload Broker server goes directly to the listening port of Common Agent. Both Tivoli Dynamic Workload Broker subagents (Resource Advisor Agent and Job Executor Agent) are exposing a Web service on that port. Based on Tivoli Dynamic Workload Broker servers request, Agent Manager provides a list of all registered Common Agents. The Tivoli Dynamic Workload Broker server can connect directly to the desired Common Agent and either install or uninstall a Tivoli Dynamic Workload Broker subagent.
72
Important note concerning agent lists: It is necessary to distinguish two different agent lists that are presented in the Tivoli Dynamic Workload Console interface. Each list is achieved in different way, using different communication channels. The content of the list may also be different: Select Tracking Computers. This view offers a list of computers. This is a logical representation of a real machine that has Tivoli Dynamic Workload Broker agents installed. When a Tivoli Dynamic Workload Broker Subagent is installed on the top of a Common Agent, it connects to the Tivoli Dynamic Workload Broker server. Its name is then stored in the list of known Tivoli Dynamic Workload Broker agents. In this case, Agent Manager was not involved in the communication between Tivoli Dynamic Workload Broker server and agent. Select Scheduling Environment Agents. This view offers a list of all Common Agents managed by the Agent Manager (including those that do not host a Tivoli Dynamic Workload Broker subagent). In this case, the Tivoli Dynamic Workload Broker contacted the Agent Manager and requested the list of installed Common Agents. From the topological perspective, the Agent Manager does not necessarily have to reside on the same machine as the main Tivoli Dynamic Workload Broker server. If Tivoli Dynamic Workload Broker is the first Tivoli product using the Common Agent Services, the Agent Manager probably will be installed on the same machine as the other Tivoli Dynamic Workload Broker server components. However, in large environments, with multiple Tivoli products leveraging the Common Agent Services infrastructure, a separate server should be dedicated for the Agent Manager component. For more information about the secure communication among the Tivoli Dynamic Workload Broker server and its agents, refer to 3.8.1, Encrypted communication on page 91.
73
See Figure 3-5 for a clear view of the Tivoli Dynamic Workload Broker server integrated with Agent Manager, and thus leveraging Common Agent Services for communicating with its agents.
Figure 3-5 Communication between the Tivoli Dynamic Workload Broker server and an agent
74
3.5 Job and resource definitions

In this section, we describe the format that is used for storing the job and resource definitions. We also list the possibilities of how the definitions can be created. Tivoli Dynamic Workload Broker job definitions and resource definitions are both stored in the Tivoli Dynamic Workload Broker repositories. However, the way in which they can be created and modified is different. The persistent storage for both repositories is RDBMS. In Tivoli Dynamic Workload Broker V1.2, the RDBMS may be either DB2 or Oracle. All the data is stored in tables defined within the database dedicated for Tivoli Dynamic Workload Broker usage. The default name of this database is TDWB.
3.5.1 Job definitions

Tivoli Dynamic Workload Broker uses a special language for defining jobs. This language is based on XML and its name is Job Submission Description Language (JSDL). Each job definition is stored in the Job Repository. When saving the job definition to the Job Repository, a validation is run against the current JSDL definition. If a definition is not valid (it does not meet the JSDL schema), it is not saved until the errors are corrected. Job definitions can be created using following tools/interfaces: Tivoli Dynamic Workload Console Job Brokering Definition Console Imported through a command-line interface from a JSDL file (plain text XML based file) Imported from custom application through a direct Web service invocation (custom application) Several approaches can be taken for working with job definitions. Basically, the jobs can be defined either by the dedicated graphical tool, or they must be written using knowledge of an XML based language called Job Submission Description Language (JSDL). Refer to 3.7, Useful tips for working with job definitions on page 84, where we provide the hints that allow you to choose the right way of working with job definitions.
75
3.5.2 Resource definitions

Resource definitions can be created and modified through the Tivoli Dynamic Workload Console in a much more fashionable way than job definitions. Tivoli Dynamic Workload Console offers the Resource wizards, which allow you to perform a step-by-step resource definition. All the work necessary for manipulating with resource definitions can be done through the Tivoli Dynamic Workload Console. An example is shown in Figure 3-6.
Figure 3-6 Resource wizard in Tivoli Dynamic Workload Console
76
3.6 Tivoli Dynamic Workload Broker user interfaces

In this section, we list the user interfaces provided with Tivoli Dynamic Workload Broker and describe their capabilities. Tivoli Dynamic Workload Broker offers a Web interface, command-line interface, and graphical tool for defining the Tivoli Dynamic Workload Broker jobs. We describe all of them in the following sections. All the user interfaces communicate with the Tivoli Dynamic Workload Broker server through the Web services interface.
3.6.1 Tivoli Dynamic Workload Console

This section describes the Tivoli Dynamic Workload Broker Web interface. We describe the Web interface functionality and the possible deployment scenarios. The Web interface of Tivoli Dynamic Workload Broker is called Tivoli Dynamic
Workload Console.
Tivoli Dynamic Workload Console runs on the top of the Integrated Solutions Console (ISC), which is the common Tivoli solution for providing multiple Tivoli products with the Web interface. Each product interface is represented as a set of portlets within the Integrated Solutions Console.
Tivoli Dynamic Workload Console functionality

Tivoli Dynamic Workload Console provides a Web interface for managing the Tivoli Dynamic Workload Broker environment. It offers, for example: A Resource Wizard for logical resources definitions A plain text editor for the editing of job definitions Interface for computer definitions (computers point to machines, where Common Agents are installed. We explain the term Common Agent in the section 3.4, Common Agent Services on page 69). Submitting and monitoring jobs Recovering failing jobs or resources
77
Note: The Tivoli Dynamic Workload Console does not offer any wizard for creating the job definitions. We do not recommend performing complex job definitions using the Tivoli Dynamic Workload Console. You should use the Job Brokering Definition Console for creating the job definitions. The Job Brokering Definition Console is described in 3.6.3, Job Brokering Definition Console on page 82.
78
You can see a snapshot of the Tivoli Dynamic Workload Console in Figure 3-7.
Figure 3-7 Tivoli Dynamic Workload Console
79
Tivoli Dynamic Workload Console deployment scenarios

The Integrated Solutions Console is a common interface for multiple products, such as Tivoli Storage Manager, Tivoli Workload Scheduler, and so on. When installing the Tivoli Dynamic Workload Console from installation bundles shipped with the Tivoli Dynamic Workload Broker, the installation program allows you to install portlets either for the Tivoli Dynamic Workload Broker or the Tivoli Workload Scheduler. Leveraging the Tivoli Dynamic Workload Console offers you the possibility to manage the important features of both Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker from one single interface. Because of performance reasons, the Integrated Solutions Console should be installed on a separate machine from the Tivoli Dynamic Workload Broker server. This is not a must, but recommended in large environments. The Tivoli Dynamic Workload Console can be installed on an existing WebSphere Application Server V.6.1. The another option is to install the Tivoli Dynamic Workload Console into the embedded version of the WebSphere Application Server. The advantage of installing the Tivoli Dynamic Workload Console into an existing WebSphere Application Server instance is that you reduce the amount of WebSphere Application Servers installed. For environments where the Tivoli Dynamic Workload Broker and Tivoli Dynamic Workload Console reside on the same machine, we recommend installing both Tivoli Dynamic Workload Broker and Tivoli Dynamic Workload Console into one existing WebSphere Application Server instance. This helps to reduce the load of the system. For systems where the Tivoli Dynamic Workload Console is installed on a separate machine from the Tivoli Dynamic Workload Broker server, the Tivoli Dynamic Workload Console can be installed to its own embedded WebSphere Application Server. However, it is up to you if you choose the embedded WebSphere Application Server or if you find the suitable existing WebSphere Application Server instance in your environment.
3.6.2 Command-line interface

Tivoli Dynamic Workload Broker also provides a command-line interface (CLI) that offers functionality similar to a graphical Web interface. CLI is useful for those users who prefer to administer the environment from the command line. CLI also offers wider possibilities for scripting of more complicated tasks.
80
The command-line interface (CLI) allows the Tivoli Dynamic Workload Broker user to perform all the essential operations necessary for managing the jobs. By using a CLI, a Tivoli Dynamic Workload Broker user can also put jobs into the archive database tables. A command-line interface offers the following functionality: Managing job definitions Submitting jobs Getting job details Cancelling jobs Querying jobs Archiving database tables We provide a simple mapping between these operations and their corresponding commands below. Example 3-1 shows the job submission from the command line.
Example 3-1 Submitting a job from the command-line interface
C:\Documents and Settings\Administrator>jobsubmit -jdname first Call Job Dispatcher to submit the job. Success returned from Job Dispatcher The job d5ac970a-588a-3eaf-bfcf-b13d8d62b0b3 submitted successfully The default path of command-line binaries is the /bin subdirectory of the Tivoli Dynamic Workload Broker installation directory: On Windows: C:\Program Files\ITDWB\Server\bin On UNIX platforms: /opt/IBM/ITDWB/Server/bin Before you can launch any of the CLI executables, you must source the Tivoli Dynamic Workload Broker environment: On Windows: C:\Program Files\ITDWB\Server\bin\tdwb_env.bat On UNIX: . /opt/IBM/ITDWB/Server/bin/tdwb_env.sh
81
Table 3-1 describes mapping among Tivoli Dynamic Workload Broker operations and their corresponding commands.
Table 3-1 Command-line interface command list Task Manage job definitions Job submission Getting single job details Cancel job Query jobs Archive database tables Related command jobstore jobsubmit jobdetails jobcancel jobquery movehistorydata
All of the CLI executables can be run only on the Tivoli Dynamic Workload Broker server. There is currently no deployment scenario available that allows you to install Tivoli Dynamic Workload Broker CLI on a separate machine and issue commands remotely.
3.6.3 Job Brokering Definition Console

The Job Brokering Definition Console is an Eclipse based graphical tool that serves as a user-friendly interface for working with the Tivoli Dynamic Workload Broker job definitions. The Job Brokering Definition Console also serves as a conversion tool for transforming the Tivoli Workload Scheduler (TWS) jobs into Tivoli Dynamic Workload Broker job definitions. The Job Brokering Definition Console is typically installed on the workstations of Tivoli Dynamic Workload Broker users that are developing the job definitions. The Job Brokering Definition Console requires a TCP/IP connection to the Tivoli Dynamic Workload Broker server. You can see the Job Brokering Definition Console snapshot in the Figure 3-8 on page 83.
82
Figure 3-8 Job Brokering Definition Console
Note: Job Brokering Definition Console can only create job definitions. If you want to create resource definitions, you must use Tivoli Dynamic Workload Console wizards. There are many approaches, that can be taken while working with the job definitions. We discuss all of them in detail, together with their advantages and disadvantages, in 3.7, Useful tips for working with job definitions on page 84.
Converting Tivoli Workload Scheduler job definitions into Tivoli Dynamic Workload Broker job brokering definitions
Job Brokering Definition Console is also a transformation tool used for converting Tivoli Workload Scheduler job definitions into Tivoli Dynamic Workload Broker job brokering definitions.
83
In the Tivoli Dynamic Workload Broker V1.2, a new important feature has been added: The Tivoli Workload Scheduler jobs that are converted into the Tivoli Dynamic Workload Broker jobs now include some of the Tivoli Workload Scheduler variables (also know as the Unison variables). The variables like UNISON_SCHED, UNISON_JOB, UNISON_RUN, and others are now available to the adapted Tivoli Dynamic Workload Broker jobs. During the migration process from the Tivoli Workload Scheduler job to the Tivoli Dynamic Workload Broker job, the Tivoli Workload Scheduler variables become available as JSDL variables. During the job run time, these variables are available as the environment variables. The detailed step-by-step mechanism of converting the Tivoli Workload Scheduler jobs into Tivoli Dynamic Workload Broker job definitions is described in Getting Started with Tivoli Dynamic Workload Broker Version 1.1, SG24-7442.
3.7 Useful tips for working with job definitions

This section discusses manipulation of job definitions from perspective of comfort and security.
3.7.1 Comfort approach

The list below describes the approaches from the most user friendly to the least one: Using the Job Brokering Definition Console This is the recommended and native way to create and modify the job definitions. Job Brokering Definition Console is an Eclipse based application that is installed directly on to operators workstations. This client offers the comprehensive graphical interface for creating the job definitions. It also performs validation of the job definitions against the Job Submission Description Language (JSDL) schema, so you will be informed of any possible error that you made during job creation. For more information about Job Brokering Definition Console, refer to 3.6.3, Job Brokering Definition Console on page 82. Creating the job definition using the Tivoli Dynamic Workload Console This Web interface offers you the ability to create the job definition directly on the server, but does not provide any sophisticated tool for this task. In fact you are required to write the complete JSDL definition from scratch.You must have
84
a comprehensive knowledge of JSDL schema to be able to create the correct job definitions from scratch. This is not the recommended way to create the job definitions from scratch. The Tivoli Dynamic Workload Console is suitable for performing minor changes to already existing job definitions, that are stored in the Job Repository. Creating the job definitions using either a plain text editor or any XML oriented editor and then uploading them to the Tivoli Dynamic Workload Broker server using the command-line interface. Again, this is not the recommended way as you cannot natively perform the validation against the JSDL schema. Sending the job definition to the Job Repository using the Tivoli Dynamic Workload Broker Web Services interface. This is the most appropriate way, that is, when you integrate the Tivoli Dynamic Workload Broker with your companys enterprise applications. However, it is up to you to define the JSDL content that you want to send to the Job Repository.
3.7.2 Security approach

The section discusses the job definitions from the security perspective. Some of the jobs definitions may include sensitive information, such user IDs and passwords for the target systems. We describe how the password is represented in the job definition. The following sections describe the representation of password entries for each approach that may be used during the job definition creation.
Using the Job Brokering Definition Console

When defining the job definition using the Job Brokering Definition Console, you must save the job definition locally before you send it to the server. If you do not save the job definition and try to upload it to the Job Repository, you will receive an error message. This can be a problem, because the locally saved JSDL file contains an unecrypted password if the password is included in the job definition. This is a possible security risk, because anybody who has access to the directory where the JSDL file is saved can read the JSDL file and grab the user ID/password information.
85
Be aware that we are speaking about the file systems of workstations where the Job Brokering Definition Console is installed. These workstations do not necessarily need to be dedicated to only Tivoli Dynamic Workload Broker related purposes. Because of that, there is a higher risk that sensitive information included within the JSDL file can be accessed by unauthorized personnel. Note: The unecrypted password issue discussed in this section should be considered if it affects workstations that are shared by multiple persons, or if their file systems are exposed to the network. If your workstations are protected to a reasonable extent, you do not need to follow the strict security approach described in this section. You can reduce the risk of misusing the unecrypted password as follows: When creating of job definitions from scratch: Create the job definition using the Job Brokering Definition Console. Save the job definition locally. Upload the job definition to the Tivoli Dynamic Workload Broker Job Repository. Delete the locally stored job definition. You can use the Job Brokering Definition Console for this task, because it allows you to manipulate the local and remote job definitions. When modifying the existing job definitions stored in the Job Repository: You do not need to take care of the passwords of jobs that you have downloaded from the Job Repository. The password encrypted on the server and the JSDL definition that was downloaded to your workstation remains encrypted as well. Only when you need to change the password should you follow the instructions below. If you change any other value but the password, the JSDL file will still keep the encrypted password: Download the definition from the Job Repository to your local file system. Open the job definition stored on your the local file system. Change the password. Save the job definition locally. Upload the job definition to the Tivoli Dynamic Workload Broker Job Repository.
86
Delete the locally stored job definition. You can use the Job Brokering Definition Console for this task, because it allows you to manipulate with the local and remote job definitions. Note: It is important to know that the above described risk is related only to the JSDL files stored locally on the workstation. Any Tivoli Dynamic Workload Broker user who is working with the Job Brokering Definition Console will not see the unecrypted password, because the password fields display just the asterisks.
Using the Tivoli Dynamic Workload Console

Each job definition that is stored in the Job Repository has the password entries encrypted using the AES algorithm. This is valid for all job definitions stored on the server, independently of how you have created them. The users that can view the job definition will see only the encrypted password from the Tivoli Dynamic Workload Console job definition editor. Furthermore, if you use the Tivoli Dynamic Workload Console to edit the job definition, the password will get encrypted again if you modify the description.
Using the text editors or CLI

Using plain text or XML editors to create the job definitions is the least convenient way. It is not easy or secure. When you use this approach, you face the same problem as with the locally stored JSDL files that were created using the Job Brokering Definition Console. There is no way to have the password encrypted in the locally stored JSDL file. Because of that, the only secure approach is to delete any locally stored JSDL files if they contain sensitive information. Of course, you must upload them to the Job Repository first.
3.7.3 Job Brokering Definition Console enhancements

This section describes two new useful enhancements that have been available since Tivoli Dynamic Workload Broker Version 1.2.
Context assistant
The context assistant feature allows you to search for computers and logical resources defined on the Tivoli Dynamic Workload Broker server. While defining the job requirements, you do not need to type the host names or logical resources manually.
87
Computers can be added by pressing Ctrl+Space in the Candidate hosts field. You can navigate to this field by selecting Resources Hardware Requirements. You can see an example in Figure 3-9.
Figure 3-9 Context assistant - Computers
Logical resources can be added by pressing Ctrl+Space in the Logical Resources field. You can navigate to this field by selecting Resources Software Requirements. You can see an example in Figure 3-9.
88
Figure 3-10 Context assistant - Logical resources
The context assistant helps you access the above defined lists. Future versions of Tivoli Dynamic Workload Broker will include context assistants for more properties.
Search for matching resources

This feature allows you to check how the job requirements will determine where the job will be submitted. This helps optimize the job requirements already in the design phase. The context assistant will display the list of computers where this particular job may be submitted. If the job requirements are too generic, you will get a long list of possible targets. On the other hand, if the job requirements are too specific, the result list can be quite narrow or even empty. Knowing this information already during the design phase can help you optimize the job requirements in order to run the job on the right computers.
89
Note: Note that this feature works with the current status of resources in the Resource repository, regardless of their current availability and administrative status (online/offline, available/unavailable, and so on). In essence, the resource matching is performed on the current status, but the availability and administrative status are not considered. Figure 3-11 shows where can you find the Search for matching resources button.
Figure 3-11 Search for matching resources
Using this feature shows the target resource groups. It is possible to see the same computer on multiple lines because one computer may match different resource groups (differently related resource instances).
90
3.8 Security features

In this section, we describe the security features of Tivoli Dynamic Workload Broker broker. Software solutions used for job workload management have the authority to launch jobs across many machines and platforms across the IT environment. A misuse of a such software tools could lead to severe security threats, such as: Unauthorized job management Submitting of jobs Cancelling of jobs Providing the jobs with inappropriate parameters Sniffing of job outputs Sniffing logon credentials sent with the jobs To reduce the security risks, the following features are included in Tivoli Dynamic Workload Broker: Encrypted communication Firewall support Authentication mechanism Authorization roles All the above-mentioned features are described in following sections.
3.8.1 Encrypted communication

In this section, we describe how the Tivoli Dynamic Workload Broker server communicates with external components. We describe in detail two different communication networks that Tivoli Dynamic Workload Broker uses. Tivoli Dynamic Workload Broker uses Web services as a communication mechanism among its components. The Tivoli Dynamic Workload Broker server accepts incoming Web services calls either from clients or from agents. Also, the agents accept Web services calls coming from the server. Tivoli Dynamic Workload Broker uses either HTTP or HTTPS (HTTP over SSL) protocols as the transport layer. This chapter describes how the secure channels can be established among the Tivoli Dynamic Workload Broker components.
91
Two communication networks

From the topological point of view we can determine two different communication networks among the Tivoli Dynamic Workload Broker server and external components: Communication with clients Tivoli Dynamic Workload Console running in the Integrated Solutions Console Job Brokering Definition Console Command-line interface Custom external applications that are using Web service calls Communication with managed agents Tivoli Dynamic Workload Broker subagents hosted by Common Agents You can see both communication networks in Figure 3-12.
Figure 3-12 Communication networks
We describe both communication networks in the following sections.
92
Server to agent communication

In this section, we describe what mechanism is used for establishing trusted communication among Tivoli Dynamic Workload Broker server and Tivoli Dynamic Workload Broker agents. The Tivoli Dynamic Workload Broker server leverages a Common Agent infrastructure for communication with its agents. Common Agent Services consists of the following parties: Agent Manager: Central point of Common Agent Services. This has its own Certification Authority, which is used for issuing certificates to Common Agents and Resource Managers. Common Agents: Agents installed on each managed system. Tivoli Dynamic Workload Broker agents are installed as subagents of Common Agents. Each Common Agent has a certificate issued by Agent Manager. Resource Manager: The server part of the application that is using the Common Agent Services infrastructure. From Agent Managers perspective, the Tivoli Dynamic Workload Broker server is a Resource Manager. There are different events that invoke the registration either of a Tivoli Dynamic Workload Broker server or a Tivoli Dynamic Workload Broker agent: Tivoli Dynamic Workload Broker servers register to Agent Manager when one of these two events occurs: The user wants to see the list of agents known by the Agent Manager (through the Tivoli Dynamic Workload Console interface). The Tivoli Dynamic Workload Broker server needs to connect to an agent. The Tivoli Dynamic Workload Broker agent registers in the installation time (if not installed in disconnected mode). Each party registered in the Common Agent Services infrastructure has a pair made up of a unique certificate and a private key. Both the certificate and private key were generated and signed by Agent Managers Certification Authority during registration. Together with the key-pair, the Certification Authority's certificate was provided to each Agent and Resource Manager. These certificates are used for a mutual SSL handshake when establishing the secure channel between the Tivoli Dynamic Workload Broker server and Tivoli Dynamic Workload Broker Agent. The term mutual means that both parties must use their certificates and private keys during the SSL handshake and thus prove their identity. Each party trusts the other because their certificates have been issued by the same certification authority.
93
Note: Each certificate issued by the Agent Manager is unique, but all the certificates are of the same type. The certificates issued for the Resource Manager (Tivoli Dynamic Workload Broker server) and for a Common Agent (hosting Tivoli Dynamic Workload Broker subagent) are each unique, but it is not possible to distinguish whether the certificate was issued for a managing server or a managed agent. Thus, it is possible to establish a trusted secure communication not only between the server and agent, but also between two agents. Theoretically, a Tivoli Dynamic Workload Broker agent could accept instructions from any other Common Agent that would use correct Web services calls. The communication between the Tivoli Dynamic Workload Broker server and Tivoli Dynamic Workload Broker Agent (the Common Agents subagent) goes directly from the Tivoli Dynamic Workload Broker server to the Tivoli Dynamic Workload Broker agent and is not routed through the Agent Manager. The Agent Manager played its most important part during the registration time when it issued certificates. Important: Because of the concept of Common Agent Services, the communication between the Tivoli Dynamic Workload Broker server and the Tivoli Dynamic Workload Broker agent is always encrypted. This must be done, and encrypted communication cannot be switched off. For additional information about the Common Agent Services infrastructure, see 3.4, Common Agent Services on page 69.
Client to server communication

In this section, we describe what mechanism is used for establishing trusted communication among the Tivoli Dynamic Workload Broker server and its clients. First, we introduce the out-of-box provided user interfaces: Tivoli Dynamic Workload Console running in Integrated Solutions Console Command-line interface Job Brokering Definition Console The same mechanism as the user interfaces leverages two additional clients: Tivoli Workload Scheduler Agent External applications using an API interface based on Web services technology
94
All Tivoli Dynamic Workload Broker clients use a Web services interface when communicating with the Tivoli Dynamic Workload Broker server. The transport protocol used for the communication can be either HTTP or HTTPS. Both HTTP and HTTPS protocols are enabled by default on the server side. This means that the Tivoli Dynamic Workload Broker server accepts Web services calls that were delivered using either secure or non-secure protocols. Depending on the clients configuration, you may use either HTTP or HTTPS. All the clients are configured to use the HTTP (unecrypted) protocol by default. The following configuration steps must be done to change the configuration of clients for enforcing HTTPS: Job Brokering Definition Console: When defining the connection to the Tivoli Dynamic Workload Broker server, you can choose whether you want to use a secure connection. Integrated Solutions Console: In the view Tivoli Dynamic Workload Broker Configuration Server Connections, you can select whether you want to use the secure connection. Command-line interface: Used by HTTP default. By editing the CLIConfig.properties file, you can select whether you want to use the secure connection. Note: In a production environment, we strongly recommend using HTTPS on all clients, because without encryption, all communication is in clear text. A secure channel between a server and its client is established using the out-of-box populated truststores. Each party (server and clients) already has out-of-box keystores populated as follows: Client side: TDWBClientKeyFile.jks: Contains the client's private key TDWBClientTrustFile.jks: Contains the server's certificate Server side: TDWBServerKeyFile.jks: Contains the server's private key TDWBServerTrustFile.jks: Contains the client's certificate For the physical locations of those files, either on the client or server side, see 3.11.3, Location of certificates and private keys on page 122. As shown in the list above, each party has locally stored its own private key and the certificate of the counterpart. Thus, everything necessary for the SSL handshake is prepared on both sides. By default, only a server-side SSL handshake is implemented.
95
Summary of default certificates used in secure communication

In this section, we provide the list of all possible certificates and private keys that are used by default by the Tivoli Dynamic Workload Broker. As we have stated before, Tivoli Dynamic Workload Broker uses two types of communication networks. We list the certificates and private keys for both of them: Certificates and private keys used in a client network: Clients private key and certificate: For each client, there is the same key pair (private/public). A clients private key is stored on the client, and the clients certificate (which includes the clients public key) is stored in the servers truststore on the server. By default, the same clients private key is stored on all clients and the clients certificate stored on the server is common for all clients. The private and public keys are already included in the installation bundles. They are not generated at installation time. Servers private key and certificate: A servers private key is stored on the server. A servers certificate (which includes a servers public key) is stored on each client. By default, the same private key is stored on any installed Tivoli Dynamic Workload Broker server and the same servers certificate is stored on each installed client. The private and public keys are already included in the installation bundles. They are not generated at installation. The default certificates and private keys are used only for an SSL handshake. They provide the confidentiality and integrity features (nobody can read or change transferred data), but do not provide authentication (they do not ensure the identity of any client). However, you may use your own certificates that will correspond to each particular system. Certificates and private keys used in an agent network Agents private key and certificate: They are both generated by Agent Manager during the registration time. Each Common Agent registers to Agent Manager and provides the common registration password. Agent Manager then generates the certificate and private key for that agent. They are always unique. The agents private key is stored on the agent, and the agents certificate (which includes the agents public key) is stored in the Agent Managers truststore. Also, the certificate of Agent Managers Certification Authority is transferred to the agent during registration.
96
Servers private key and certificate: These items are generated by Agent Manager during the registration of the Tivoli Dynamic Workload Broker server to the Agent Manager. During registration, the Tivoli Dynamic Workload Broker server must provide the correct registration password. Agent Manager then generates a certificate and private key for the Tivoli Dynamic Workload Broker server and registers it as a Resource Manager. This certificate is always unique. Also, the certificate of the Agent Managers Certification Authority is transferred to the server (Resource Manager) during registration. Figure 3-13 shows the communication of Tivoli Dynamic Workload Broker server with its agents and clients. It also shows the certificates involved in establishing a secure communication.
Figure 3-13 Communication networks and used certificates
97
3.8.2 Firewall support

Tivoli Dynamic Workload Broker uses strictly defined ports for inbound communication. When placed in a firewall environment, it is sufficient to specify the corresponding allow attributes for the listening ports used by Tivoli Dynamic Workload Broker components. See Figure 3-14 to get an idea of how the Tivoli Dynamic Workload Broker traffic passes through the zone boundaries.
Figure 3-14 Sample - interaction with firewalls
For a detailed list of ports used by Tivoli Dynamic Workload Broker components, refer to IBM Tivoli Dynamic Workload Broker Installation and Configuration Guide Version 1.2, SC32-2282. The tables describing the default port values can be found in the sections that describe the silent installation methods.
98
3.8.3 Authentication mechanism

In previous sections, we explained the two different communication networks: Client network Agent network In each of these networks, a different authentication mechanism is used. We explain them in more detail in the following sections.
Authentication in an agent network

Authentication in the agents network is assured by the mechanism of Common Agent Services. Each party registered in the Common Agent Services has its unique certificate, which proves the identity of each party performing the mutual SSL handshake (establishing the secure connection). No additional authentication is implemented. Proving the identity using the certificate is sufficient.
Authentication in client network

When speaking about the authentication mechanism, we must distinguish the data flows among various clients and Tivoli Dynamic Workload Broker server. In fact, we can separate the clients into two categories: Clients directly calling the listening server port on which Tivoli Dynamic Workload Broker server exposes Web services. Clients that communicate with the server directly are: Job Brokering Definition Console Command-Line Interface Any application using a Web services interface (such as Tivoli Workload Scheduler Agent or any custom application) A Web browser connecting to Tivoli Dynamic Workload Console. The browser points to the Integrated Solutions Console portal first. Tivoli Dynamic Workload Console running within the portal then handles the request and calls the listening server port on which the Tivoli Dynamic Workload Broker server exposes Web services. Independently, in the clients category, the authentication on Tivoli Dynamic Workload Broker server is dependent on WebSphere Application Servers settings. Authentication is enforced when WebSphere Application Server has Global Security enabled. By default, WebSphere Application Server does not have Global Security switched on.
99
Direct client to server authentication

In this section, we describe the mechanism of authentication for direct client to server communication and how this authentication can be turned on. The Tivoli Dynamic Workload Broker in installed in WebSphere Application Server and leverages the WebSphere Application Servers authentication mechanism. Tivoli Dynamic Workload Broker does not implement any internal authentication infrastructure for communication with clients. The authentication mechanism is enabled on the Tivoli Dynamic Workload Broker server when the Global Security of the WebSphere Application Server is enabled. Important: Global Security for WebSphere Application Server V6.1 is disabled by default. It can be enabled by the WebSphere Administrative Console. Be aware that the check box called Enable J2EE security will be preselected if you enable the Global Security. If you enable the Global Security, make sure that you have deselected the Enable J2EE security check box prior to submitting the request. The J2EE security must not be enabled on the WebSphere Application Server V6.1 hosting the Tivoli Dynamic Workload Broker server. Depending on the WebSphere Application Server configuration, the user authentication is performed either against local operating systems user authority or against a defined LDAP. WebSphere Application Server by itself does not contain any user definitions and credential vaults. When the Global Security is turned on, each client must provide a user ID and password. These credentials are transported within the HTTP header because HTTP Basic Authentication is used. Every time a request is transferred from client to server, it carries the credentials in the HTTP header. WebSphere Application Server takes care of the authentication then (either using operating systems authority or by checking the credentials with the LDAP). Figure 3-15 on page 101 gives an overview of the client to server authentication setup. Note: In this section, we do not discuss encrypted communication, but instead we discuss authentication. We stress this fact because we want to avoid confusion. There is a difference between these terms. For example, you may use a secure channel that was established between a client and server using the server certificate for the SSL handshake, but if the WebSphere Application Server does not have Global Security turned on, you still do not have an authentication mechanism in place, even if you use certificates and SSL.
100
Figure 3-15 Client to server authentication
Browser to ISC to TDWC to server authentication

In this section, we describe the mechanism of authentication when a Tivoli Dynamic Workload Console is used for communication with a server. In this section, we describe the default behavior when all the components use separated user registries and no single sign-on is implemented. The single sign-on enablement is described in 3.8.5, Single sign-on enablement on page 105. The authentication process is split into two steps: Authentication performed by the Integrated Solutions Console hosting the Tivoli Dynamic Workload Console Authentication performed on the Tivoli Dynamic Workload Broker server side Note: Before reading the following pages, make sure that you have read Direct client to server authentication on page 100. We explain several terms in that section that are necessary to understand the following content. Now we describe the Integrated Solutions Console authentication mechanism in greater detail and explain the interaction with Tivoli Dynamic Workload Broker server authentication.
101
The Tivoli Dynamic Workload Console is hosted by the Integrated Solutions Console. The Integrated Solutions Console enforces the authentication mechanism by default. Integrated Solutions Console can leverage the following authentication realms: Federated Repositories: This is the default authentication realm. The Integrated Solutions Console uses internal files, where the credentials are stored. The entries can be managed through the Integrated Solutions Console user interface. Local Operating System: The authentication is done on the operating system level (on the machine where the Integrated Solutions Console is installed). Standalone LDAP registry: External LDAP server may be used for authentication. This approach is also the prerequisite for the single sign-on enablement. The single sign-on enablement is described in 3.8.5, Single sign-on enablement on page 105. Stand-alone custom registry The user that wants to use the Tivoli Dynamic Workload Console to access the Tivoli Dynamic Workload Broker server sees only one visible authentication step; he must provide the proper credentials for the Integrated Solutions Console. If the Global Security on the WebSphere Application Server hosting the Tivoli Dynamic Workload Broker server is turned off, no further authentication is required and the user can perform actions on the Tivoli Dynamic Workload Broker server. If the Global Security on the WebSphere Application Server hosting the Tivoli Dynamic Workload Broker server is turned on, the user must authenticate itself against the WebSphere Application Server hosting the Tivoli Dynamic Workload Broker server. Depending on your deployment scenario, the logon credentials may or may not be the same for the Integrated Solutions Console and Tivoli Dynamic Workload Broker server: If each component uses a separate user registry, then the credential vaults are not automatically synchronized in any way. Thus, you must manually map the credentials for Integrated Solutions Console and for the Tivoli Dynamic Workload Broker server. The mapping is performed on the Integrated Solutions Console side in the Server Connection page. If the components use the same user registry (for example, the LDAP server), then the credentials are the same. However, you still need to define the credential mapping on the Integrated Solutions Console side in the Server Connection page.
102
If the components share the same user registry and single sign-on is implemented, then the credentials are the same and you do not need to handle the manual credential mapping. Note: The user account mapping can be significantly simplified if you leverage the single sign-on mechanism. The single sign-on enablement is described in 3.8.5, Single sign-on enablement on page 105. Once the user gets authenticated by the Integrated Solutions Console, the mapped credentials are passed to the Tivoli Dynamic Workload Broker (in fact, they are passed to the WebSphere Application Server that is hosting the Tivoli Dynamic Workload Broker server). Then the authentication mechanism is exactly the same, as described in Direct client to server authentication on page 100. The credentials are transferred in each HTTP request within the HTTP header and the users identity is checked using HTTP Basic authentication. Figure 3-16 shows the whole mechanism of authentication when the user connects to the Tivoli Dynamic Workload Broker server using the Tivoli Dynamic Workload Console.
Figure 3-16 Browser-ISC-TDWB server authentication w/ separate user registries
103
3.8.4 Authorization roles

In this section, we describe the different authorization roles that different Tivoli Dynamic Workload Broker users can posses. We also explain the scope of roles and where can they be defined. Different degrees of authorization allow users to perform different set of actions. Table 3-2 shows the full list of all possible authorization roles.
Table 3-2 List of Tivoli Dynamic Workload Broker authorization roles Authorization role Administrator Configurator Developer Permitted operations Super user with full authorization (configurator + developer + operator). Manages the scheduling infrastructure. Manages job definitions (necessary role for the Job Brokering Definition Console when communicating with the Tivoli Dynamic Workload Broker server). Monitors and controls any job that has been submitted. Monitors and controls its own jobs (necessary role required for TWS Agent).
Operator Submitter
The user assignments to particular roles can be changed using the WebSphere Application Server Administrative Console (on the WebSphere Application Server hosting the Tivoli Dynamic Workload Broker server). By default, any user that successfully authenticates against the WebSphere Application Server (hosting the Tivoli Dynamic Workload Broker server) has the administrator role. If this user accesses the Tivoli Dynamic Workload Broker server using the Tivoli Dynamic Workload Console interface, he must authenticate it against at least the Integrated Solutions Console. Note: If a particular role is assigned to a user, it is valid for all jobs and resources in the environment. For example, a developer role allows the user to modify and delete any job defined in the Job Repository. It is not possible to narrow the scope of jobs and resources to the given role. However, this feature is planned for future versions.
104
3.8.5 Single sign-on enablement

This chapter describes the Tivoli Dynamic Workload Broker single sign-on capabilities. We describe the single sign-on enablement also for the Tivoli Workload Scheduler. Both Tivoli Dynamic Workload Broker and Tivoli Workload Scheduler are the key products of IBM workload automation family. They share a common administrative interface: the Tivoli Dynamic Workload Console. This section describes the basic concepts of single sign-on among the Tivoli Dynamic Workload Console, Tivoli Dynamic Workload Broker engine, and Tivoli Workload Scheduler engine. Note: We cover single sign-on enablement for both Tivoli Dynamic Workload Broker and Tivoli Workload Scheduler in this section. Note that it is not an absolute necessity to enable single sign-on for both products. Even in the stand-alone Tivoli Dynamic Workload Broker solution, the single sign-on feature can help simplify the user account management. If Tivoli Workload Scheduler is also installed, you may also configure it to leverage the single sign-on functionality. This is not a necessity, but optional. Depending on your environment, you may choose several authentication approaches: Single sign-on for Tivoli Dynamic Workload Console and both Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker Single sign-on for Tivoli Dynamic Workload Console and the Tivoli Dynamic Workload Broker only Single sign-on for Tivoli Dynamic Workload Console and the Tivoli Workload Scheduler only Not using the single sign-on approach at all
Benefits of single sign-on

This section explains the benefits of single sign-on in the Tivoli Dynamic Workload Broker or Tivoli Workload Scheduler environment. Single sign-on allows you to define the users just in one user registry, that is, the LDAP server. Without single sign-on, you need to configure accounts on: Tivoli Dynamic Workload Console Tivoli Dynamic Workload Broker engine Tivoli Workload Scheduler engine
105
Furthermore, without single sign-on implemented, you need to specify the credentials for a server connection from the Tivoli Dynamic Workload Console to following servers: Tivoli Dynamic Workload Broker engine Tivoli Workload Scheduler engine Without single sign-on, you must perform five different tasks. With single sign-on, you perform just one task: You put the user into the LDAP. The single sign-on approach reduces your security management by eliminating four other tasks. Figure 3-17 shows the environment that leverages single sign-on enablement.
Figure 3-17 TDWB/TWS environment leveraging single sign-on
Major single sign-on implementation steps

This section briefly addresses the necessary prerequisites together with the steps that must be taken in order to enable the single sign-on for Tivoli Dynamic Workload Console, Tivoli Dynamic Workload Broker, and Tivoli Workload Scheduler.
106
The following components are involved in the single sign-on implementation: Tivoli Dynamic Workload Console Tivoli Dynamic Workload Broker engine Tivoli Workload Scheduler (optional) Each of these components is hosted by the WebSphere Application Server. To implement single sign-on: You must have an supported LDAP server in order to be able to leverage the single sign-on capabilities. All WebSphere Application Servers hosting the particular components (such as Tivoli Dynamic Workload Console or Tivoli Dynamic Workload Broker engine) must use the LDAP server as its authentication realms. Each involved WebSphere Application Server must point to the same LDAP server. Note: A detailed description of sharing the user registry in the WebSphere Application Server V6.1 can be found in http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp. Within this site, navigate to the WebSphere Application Server (Distributed platforms and Windows) Version 6.1 and then select Securing applications and their environment. You must configure the involved WebSphere Application Servers to share the authentication tokens. Once the user gets authenticated by the Tivoli Dynamic Workload Console, its authentication tokens must be passed to the subsequent WebSphere Application Server (for example, the WebSphere Application Server hosting the Tivoli Dynamic Workload Broker engine). This is accomplished by using LTPA token keys. The term LTPA means Lightweight Third-Party Authentication. This is the mechanism that propagates user credentials among the WebSphere Application Server based applications. The step by step instructions that describe the steps necessary for single sign-on enablement are included in IBM Tivoli Dynamic Workload Broker Installation and Configuration Guide Version 1.2, SC32-2282.
107
Note: The WebSphere Application Server automatically uses the LTPA mechanism internally. This means that the LTPA token keys can be used among multiple J2EE applications running within the same WebSphere Application Server instance. This statement is important in deployment scenarios where the Tivoli Dynamic Workload Console and Tivoli Dynamic Workload Broker are running within the same instance of the WebSphere Application Server. In this case, you do not need to perform any LTPA related configuration steps. Anyway, you must do the LTPA related configuration steps for single sign-on enablement between Tivoli Dynamic Workload Console and Tivoli Workload Scheduler. Tivoli Workload Scheduler uses its own embedded version of WebSphere Application Server. Therefore, it cannot be installed in the same WebSphere Application Server instance as the Tivoli Dynamic Workload Console. In order to leverage single sign-on between Tivoli Dynamic Workload Console and the Tivoli Dynamic Workload Broker, you must not enter any credentials when defining the server connection for the users. The same statement is valid also for the single sign-on enablement between Tivoli Dynamic Workload Console and the Tivoli Workload Scheduler engine. This is important if you have not used the single sign-on originally, and you have just switched to a single sign-on solution. In this case, remove any credentials that you have specified in the server connections for the users in the Tivoli Dynamic Workload Console. An example is shown in Figure 3-18.
Figure 3-18 Server Connection within Tivoli Dynamic Workload Console
108
Authentication scenarios
This section describes three different authentication scenarios: Separated user registries for each component Shared user registries among the components, but no single sign-on implemented Shared user registries among the components with single sign-on enabled We describe these three approaches because we want to avoid the confusion that often accompanies the shared LDAP approach and the full single sign-on approach. In the figures that follow, we use the following acronyms: WebSphere Application Server (WAS) Tivoli Dynamic Workload Console (TDWC) Tivoli Dynamic Workload Broker (TDWB) Tivoli Workload Scheduler (TWS) Lightweight Third-Party Authentication (LTPA)
Separated user registries scenario

This section describes the deployment scenario, where each component uses its own user registry. Mostly these user registries are just the accounts defined on local operating systems (on the servers where the involved the WebSphere Application Servers are installed).
109
This deployment scenario is shown in Figure 3-19.
Figure 3-19 Authentication with no shared user registry
When using this deployment scenario, you must define the user IDs in the following places: Tivoli Dynamic Workload Console Tivoli Workload Scheduler Tivoli Dynamic Workload Broker
110
Furthermore, you need to specify the credentials for the server connection from the Tivoli Dynamic Workload Console to the following servers: Tivoli Dynamic Workload Broker engine Tivoli Workload Scheduler engine For a single user, you must perform five different security management tasks.
Shared user registries scenario

This section describes the deployment scenario where the components use the shared user registry (LDAP server). This solution is shown in the Figure 3-20.
Figure 3-20 Authentication with shared user registry without single sign-on
This scenario describes the following state: You have configured all the involved WebSphere Application Servers to use the same user registry (LDAP). You did not configure the involved WebSphere Application Servers to use the Lightweight Third-Party Authentication (LTPA) mechanism.
111
When using this deployment scenario, you must define the user IDs in the shared registry - LDAP server. Because you did not enable the LTPA mechanism, you still need to specify credentials for the server connection from the Tivoli Dynamic Workload Console to the following servers: Tivoli Dynamic Workload Broker engine Tivoli Workload Scheduler engine For a single user, you must perform three different security management tasks.
Single sign-on scenario

This section describes the deployment scenario with full single sign-on enablement. This solution is shown in Figure 3-21.
Figure 3-21 Authentication with shared user registry and single sign-on
This scenario describes the following state: You have configured all the involved WebSphere Application Servers to use the same user registry (LDAP). You have configured the involved WebSphere Application Servers to use the Lightweight Third-Party Authentication (LTPA) mechanism.
112
When using this deployment scenario you must define the user IDs in the shared registry - LDAP server. Because you have enabled the LTPA mechanism, you do not need to specify credentials for the server connection from the Tivoli Dynamic Workload Console to the following servers: Tivoli Dynamic Workload Broker engine Tivoli Workload Scheduler engine For a single user, you must perform one security management task: putting the user to LDAP registry.
What single sign-on simplifies

This section discusses what security management tasks are simplified by the single sign-on enablement and which tasks are not affected. You must consider the difference between authentication and authorization. While authentication is the process of determining the users identity (who the user is), authorization determines the users rights (what the user can do). Single sign-on simplifies the authentication part only. Even if you set up single sign-on between the Tivoli Dynamic Workload Console and the Tivoli Dynamic Workload Broker server, you still need to adjust the authorization settings separately on each of them. This means that even with the single sign-on enablement, you must do following tasks to set up authorization: Add the Tivoli Dynamic Workload Console user to the corresponding group (within the Integrated Solutions Console GUI) in order to allow the user access to specific portlets (modifying jobs, resources, and so on). Add the user to the defined group on the Tivoli Dynamic Workload Broker engine. This step can be done by the administration console of the WebSphere Application Server hosting the Tivoli Dynamic Workload Broker. If you also have the Tivoli Workload Scheduler installed, set the authorization roles by modifying the Tivoli Workload Scheduler security file.
3.8.6 Recommended security best practices after installation

In this section, we describe the necessary steps that will set up a more secure environment than the default installation. 1. Turn on WebSphere Application Server Global Security (on the WebSphere Application Server hosting the Tivoli Dynamic Workload Broker server).
113
2. Choose the authentication method in used in your environment and set up the authentication. Refer to Authentication scenarios on page 109 for more information. 3. Assign the users their desired authorization roles using the WebSphere Application Server Administrative Console (on the WebSphere Application Server hosting the Tivoli Dynamic Workload Broker server). 4. Optionally, generate a new server certificate for the Tivoli Dynamic Workload Broker server. This certificate will be used for communication in the client network. Distribute this new certificate into the appropriate directory on all possible clients. If you install any new client (such as a new instance of the Job Brokering Definition Console, you must distribute this certificate to that client). If you want to enable single sign-on between the Tivoli Dynamic Workload Console and the Tivoli Dynamic Workload Broker engine, see 3.8.5, Single sign-on enablement on page 105. This section discusses single sign-on from the architectonical perspective. The detailed step by step instructions for enabling single sign-on are described in IBM Tivoli Dynamic Workload Broker Installation and Configuration Guide Version 1.2, SC32-2282.
3.9 Tivoli Dynamic Workload Broker auditing

Tivoli Dynamic Workload Broker V1.2 provides an auditing feature that can help you track the operations that are provided in the Tivoli Dynamic Workload Broker environment. Auditing allows you to log and track the actions that the particular users have performed with the Tivoli Dynamic Workload Broker, such as submitting or cancelling of jobs, or adjusting the environment (jobs and resources definitions). This information may be especially relevant for businesses that must meet the following guidelines: Sarbanes-Oxley Act Health Insurance Portability and Accountability Act Basel II International Banking Accord Note: The auditing feature is switched off by default.
114
3.9.1 Tivoli Dynamic Workload Broker audit capabilities

This section lists the capabilities of the Tivoli Dynamic Workload Broker auditing feature. If you switch the auditing on, you can audit following events: AgentAuditEvent: Operations performed on agents JobDefinitionAuditEvent: Operations performed on job definitions JobLogAuditEvent: Operations performed on job logs JobAuditEvent: Operations performed on jobs ResourceAuditEvent: Operations performed on resources RelationshipAuditEvent: Operations performed on relationships between resources RecoveryActionAuditEvent: Operations performed on recovery actions HistoryDataAuditEvent: Operations performed on historical data
3.9.2 Configuring the auditing properties

The auditing properties can be adjusted by altering the file <TDWB_INSTALL_DIR>/config/audit.properties. By modifying this file, you can either turn auditing on or off, and you can also specify the audit settings in detail. By modifying this file, you can either set up the particular audit properties (what to audit) and the system settings (where to store the audit information). Example 3-2 shows an extract from the configuration file <TDWB_INSTALL_DIR>/config/audit.properties.
Example 3-2 Default audit properties
audit.enabled=true audit.consumer.file.auditFilePrefix='tdwb_'yyyy-MM-dd audit.consumer.file.auditFileLocation="C:\\Program Files\\IBM\\ITDWB\\Server/audit" audit.consumer.file.maxFileSize=10000000 audit.consumer.file.maxAuditFiles=100
115
3.9.3 Audit trail file name convention

This section describes how the audit information is created and stored on the Tivoli Dynamic Workload Broker server. Tivoli Dynamic Workload Broker auditing leverages the Common Auditing and Reporting Service (CARS). The audit data is stored in text files in the unified format. You can view this data utilizing the plain text editors. However, we recommend that you download the IBM Log and Trace Analyzer. This tool can display the audit trails in a more user friendly format. It can be obtained at the following Web site: http://www-128.ibm.com/developerworks/autonomic/btmpd There are three versions of IBM Log and Trace Analyzer available: Portal-based version Eclipse plug-in version: You must have Eclipse already installed and add the IBM Log and Trace Analyzer as a plug-in into Eclipse. Java desktop version: This version has no dependencies on the Eclipse user interface. Even though this is a lightweight version, it is ideal as a stand-alone problem determination utility. The audit trail files can be created in the directory that you can specify in the audit.properties file. This file allows you to specify the criteria for the naming conventions of the audit trail files, maximum file size, and so on. We include an example in Sample audit trail convention on page 117. The naming convention can contain either a fixed file name part (such as tdwb_) or a variable part (such as MM-dd). This allows you to distinguish the audit trails for particular dates. The file name always takes the suffix auditN.log (where the N represents the incremental counter). Audit trail files are created using the rotation principle. There are configurable values for the audit trail file maximum size and maximum count of audit trail files within a period. Note: As already stated, the audit trails contain important security information that could help you analyze the security possible incidents in your environment. Therefore, we recommend you periodically archive them to leverage your enterprise backup/archive solution.
116
Sample audit trail convention

This section demonstrates the behavior of audit trail files under specific conditions. Let us set the following criteria: The audit trails file name is set to tdwb_yyyy_MM_dd_N.log. The audit trails maximum file size is set to 5 MB. The maximum count of the audit trail files for a period is set to 20. The date is 2007/12/08. The following behavior will occur: The first audit trail file for today will be named tdwb_2007_12_08_0.log. This file will grow until it reaches a size of 5 MB. When the 5 MB size limit is reached, the new file tdwb_2007_12_08_2.log is created. This growth continues until tdwb_2007_12_08_19.log is created. When its maximum size is reached, then the first file tdwb_2007_12_08_0.log is recreated again and its original content is overwritten. We emphasize this fact because it is crucial to consider following criteria: The disk space usage: For this one day, 5x20=100 MB of audit trails has been created. Together with audit trails created during previous days, your disk space may decrease quickly. Possible audit trail loss: If you specify too low a criteria, then the audit trails may get overwritten, and sensitive data may be lost. Archiving solution: You should move the older audit trails into your archive location. In this scenario, we have used values lower than the default ones. The default values are also the maximum ones and are set as follows: The audit trail maximum file size is 10 MB. The maximum count of audit trail files for a period is 100. Note: Note that the period can be either day, month, or year. The longer the period, the bigger the chance is that the audit trails will be periodically overwritten by the new data. Also keep in mind that using the default values can produce up to 1 GB of auditing data. This can result in 30 GB of audit trail files in your file system for each month. You should set up the parameters carefully and archive the audit trails frequently.
117
3.9.4 Important security note

Note that the audit files are created by the Java process belonging to the WebSphere Application Server, which hosts the Tivoli Dynamic Workload Broker J2EE application. The Java process creates the auditing file with the read/write permissions for all users. Unfortunately, this behavior cannot be changed by any property setting, which means that any user can also modify or delete the audit trail files. This can result in a state where some user performs some bad operations and then cleans up the audit logs to hide his actions. You can prevent this only on the file system level. By modifying the audit.properties file, you are able to select the destination directory where the audit trails are being written. If you want to avoid unauthorized access, specify the read/write permissions on that directory so that only authorized users will be able to display/modify the content of audit trail files. This means giving access only to the owner of the directory or to a group of trusted users. More detailed information about the audit features can be found in IBM Tivoli Dynamic Workload Broker User's Guide Version 1.2, SC32-2281.
3.10 Web services interface

The Tivoli Dynamic Workload Broker relies on the service-oriented architecture (SOA). It leverages the Web services interface for the Server-Agent communication and for the Client-Server communication. By utilizing the Web services interface, your business applications can programmatically leverage the job management capabilities provided by Tivoli Dynamic Workload Broker. You can easily incorporate Tivoli Dynamic Workload Broker into the SOA in your environment. Your business applications may focus on their own logic. The management of external jobs (that are dependent on suitable resources) can be passed to the Tivoli Dynamic Workload Broker. It will find the best, suitable resource for running the job and will manage the jobs life cycle. The application integrated with the Tivoli Dynamic Workload Broker through the Web services interface can perform similar operations, as the operator using the Tivoli Dynamic Workload Brokers command-line interface. Selecting the right candidate for the external job in heterogeneous and distributed environment is not an easy task. Usually it requires additional efforts of developers to implement logic evaluating where to launch a specific external
118
job based on its requirements. Integration with the Tivoli Dynamic Workload Broker could solve this task quickly and efficiently. The detailed description of the Web services interface together with guidance on how to build the sample project utilizing the Tivoli Dynamic Workload Broker Web services interface may be found in Getting Started with Tivoli Dynamic Workload Broker Version 1.1, SG24-7442.
3.11 Physical location of Tivoli Dynamic Workload Broker components

This section provides a more detailed view of Tivoli Dynamic Workload Broker components from the file system point of view. It can serve as a basic link from the architectural point of view to the configuration or troubleshooting perspective. Note: Be aware that the values provided below are default paths and may vary depending on your installation. They serve as basic pointers only.
3.11.1 Locations of server components

As described before, Tivoli Dynamic Workload Broker server components consist of several J2EE applications: A main application called ITDWB An Agent Manager An optional Tivoli Workload Scheduler Agent All of these enterprise applications are running within the WebSphere Application Server. Each of these components can be managed separately by the WebSphere Administrative Console and has its own file structure within the WebSphere Application Server. The Tivoli Dynamic Workload Console is not a direct part of Tivoli Dynamic Workload Broker server binaries. It is installed as part of the Integrated Solutions Console. The Integrated Solutions Console is a portal solution that can be a common interface for other products, such as Tivoli Storage Manager, Tivoli Workload Scheduler, and so on. The Integrated Solutions Console can use either its own embedded WebSphere Application Server instance or an existing WebSphere Application Server V.6.1 instance.
119
Figure 3-22 shows the Tivoli Dynamic Workload Broker server components as separate J2EE applications that are running within the WebSphere Application Server.
Figure 3-22 List of server components (WebSphere Management Console)
Default locations of server components

Table 3-3 shows the default paths for server components on the Windows platform.
Table 3-3 Default server paths on Windows platform Component WebSphere installation directory Tivoli Dynamic Workload Broker installation directory (command-line binaries and others) ISC WebSphere installation directory Path C:\Program Files\IBM\WebSphere\ AppServer C:\Program Files\IBM\ITDWB\Server
C:\Program Files\IBM\ISC\AppServer
120
Table 3-4 shows the default paths for server components on UNIX and Linux platforms.
Table 3-4 Default server paths on UNIX and Linux platforms Component WebSphere installation directory Path /usr/IBM/WebSphere/AppServer (AIX) /opt/IBM/WebSphere/AppServer (other UNIXes and Linux) /opt/IBM/ITDWB/Server
Tivoli Dynamic Workload Broker installation directory (command-line binaries and others) ISC WebSphere installation directory
/opt/IBM/ISC/AppServer
Note: The J2EE applications representing the Tivoli Dynamic Workload Broker server, Tivoli Workload Scheduler bridge, Tivoli Dynamic Workload Console, and Integrated Solutions Console are located in the directory trees in the corresponding WebSphere Application Server instances.
3.11.2 Locations of agent components

Table 3-5 shows the default paths for agent components on the Windows platform.
Table 3-5 Default agent paths on the Windows platform Component Common Agent (if installed with a Tivoli Dynamic Workload Broker agent) Tivoli Dynamic Workload Broker agent Path C:\Program Files\IBM\ITDWB\Agent
C:\Program Files\IBM\ITDWB\Agent\ep\r untime\agent\subagents
121
Table 3-6 shows the default paths for agent components on UNIX and Linux platforms.
Table 3-6 Default agent paths on UNIX and Linux platforms Component Common Agent (if installed with Tivoli Dynamic Workload Broker Agent) Tivoli Dynamic Workload Broker agent Path /opt/IBM/ITDWB/Agent
/opt/IBM/ITDWB/Agent/ep/runtime/
agent/subagents
3.11.3 Location of certificates and private keys

In this section, we list the default keystore locations. We provide two tables listing the keystores used in a client network and agent network, as described in Two communication networks on page 92.
Keystores for client network

Table 3-7 on page 123 shows the location of the keystores of private keys and certificates necessary on a client network for a server-side SSL handshake. The keystores are by default located on the file systems described in the table. They are provided out-of-box and are not generated at installation time.
122
Table 3-7 Keystores for client network Security file type Job Brokering Definition Console servers certificate Job Brokering Definition Console - clients private key Tivoli Dynamic Workload Console installed within Integrated Solutions Console - servers certificate Tivoli Dynamic Workload Console installed within Integrated Solutions Console - clients private key Command-line interface installed on server - serverss certificate Command-line interface installed on server - clients private key Clients certificates stored on server Servers private key Path and file name <JBDC_install_dir>/Certs/ TDWBClientTrustFile.jks <JBDC_install_dir>/Certs/ TDWBClientKeyFile.jks <ISC_WebSphere_install_dir>/ISC/ AppServer/profiles/default/etc/ TDWBClientTrustFile.jks <ISC_WebSphere_install_dir>/ISC/ AppServer/profiles/default/etc/ TDWBClientKeyFile.jks <ITDWB_server_install_dir>/Certs/ TDWBClientTrustFile.jks <ITDWB_server_install_dir>/Certs/ TDWBClientKeyFile.jks <ITDWB_server_install_dir>/Certs/ TDWBServerTrustFile.jks <ITDWB_server_install_dir>/Certs/ TDWBServerKeyFile.jks
Keystores for agent network

Table 3-8 shows the location of the keystores of private keys and certificates necessary on the agent network for a mutual SSL handshake. The keystores are by default located on file systems, as described in Table 3-8. Private keys and certificates are generated by Agent Managers Certification Authority in the registration time.
Table 3-8 Keystores for the agent network Security file type Certificate of Agent Managers Certification Authority transferred to Tivoli Dynamic Workload Broker server at start of the registration. Certificate and private key issued by Agent Managers Certification Authority for Tivoli Dynamic Workload Broker server. Path and file name <ITDWB_server_install_dir>/ ResourceManager\cert\agentTrust.jks
<ITDWB_server_install_dir>/ ResourceManager\cert\agentKeys.jks
123
Security file type Certificate of Agent Managers Certification Authority transferred to Common Agent at start of the registration. Certificate and private key issued by Agent Managers Certification Authority for Common Agent. Certificate of Agent Manager.
Path and file name <common_agent_install_dir>/ep/runtime/ agent/cert/agentTrust.jks <common_agent_install_dir>/ep/runtime/ agent/cert/agentKeys.jks <ITDWB_server_install_dir>/ AgentManager/certs/ agentManagerTrust.jks <ITDWB_server_install_dir>/ AgentManager/certs/ agentManagerKeys.jks <ITDWB_server_install_dir>/ AgentManager/certs/agentTrust.jks
Private key of Agent Manager.
Certificates of Agent Managers Certification Authority transferred from Agent Manager to Common Agent or Tivoli Dynamic Workload Broker server at start of registration. This certificate is used by the agent (resource manager) for initiating a server-side SSL handshake. Certificate and private key of Agent Managers Certification Authority. Certificate Revocations List of Agent Managers Certification Authority.
<ITDWB_server_install_dir>/ AgentManager/certs/CARootKeyRing.jks <ITDWB_server_install_dir>/ AgentManager/certs/ CertificateRevocationList
3.12 What is new in Tivoli Dynamic Workload Broker 1.2

This section briefly lists the features that are new in the Tivoli Dynamic Workload Broker V1.2. The following features and enhancements are new in Tivoli Dynamic Workload Broker V1.2: Logical server features: Auditing feature. New optimization policy differentiation. Availability of Tivoli Workload Scheduler variables to the Tivoli Dynamic Workload Broker jobs.
124
If you have integrated Tivoli Dynamic Workload Broker with the Tivoli Workload Scheduler, you can use this new flexible feature. The Tivoli Dynamic Workload Broker jobs that were adapted from the Tivoli Workload Scheduler environment can now use some of the Tivoli Workload Scheduler variables (also know as the Unison variables). The variables, such as UNISON_SCHED, UNISON_JOB, UNISON_RUN, and others are now available for the adapted Tivoli Dynamic Workload Broker jobs. During the migration process from the Tivoli Workload Scheduler job to the Tivoli Dynamic Workload Broker job, the Tivoli Workload Scheduler becomes available as JSDL variables. During the runtime, these variables are available as the environment variables. For the complete list of the Tivoli Workload Scheduler variables that are available to the Tivoli Dynamic Workload Broker jobs, refer to IBM Tivoli Dynamic Workload Broker Installation and Configuration Guide Version 1.2, SC32-2282. The IBM Support Assistant (ISA) plug-in is now available for the Tivoli Dynamic Workload Broker server. Leveraging the IBM Support assistant simplifies problem tracking related tasks. It helps you with gathering essential information that you need for communicating with IBM software support. User Interface features: Context assistant in the Job Brokering Definition Console: This feature retrieves the actual content of possible "Candidate hosts and Logical Resources" defined in the Resource repository directly into the Job Brokering Definition Console. Search for related resources feature: The Job Brokering Definition Console now includes a simulation, the resources of which will match the job requirements. Password entries are now encrypted within the Job Brokering Definition Console and the Job Repository. The Tivoli Dynamic Workload Broker Web Interface is now integrated into the Tivoli Dynamic Workload Console. The Tivoli Dynamic Workload Console can now run in the existing WebSphere Application Server instance. In the previous version, the Tivoli Dynamic Workload Broker Web Interface used the embedded WebSphere Application Server instance only. The Tivoli Dynamic Workload Console offers a common administrative interface for both Tivoli Dynamic Workload Broker and Tivoli Workload Scheduler.
125
Server/Agent topological features: Oracle support: Oracle can now be used as the persistent storage for Tivoli Dynamic Workload Broker. It can be used for Agent Manager (the server part of Common Agent Services) as well. Single sign-on enablement: The single sign-on solution can be implemented between the Tivoli Dynamic Workload Console and the Tivoli Dynamic Workload Broker engine. It can significantly simplify the user account management in your Tivoli Dynamic Workload Broker environment. Extended agent management capabilities: It is possible to install/upgrade the Tivoli Dynamic Workload Broker agent components within Common Agent. IP v6 protocol support. Extended target platform support: See IBM Tivoli Dynamic Workload Broker Installation and Configuration Guide Version 1.2, SC32-2282 for details.
3.13 Combined Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker solution architecture
Having discussed both the Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker architectures separately, we now can talk about the combined architecture, meaning Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker working together. When Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker are used together, the Tivoli Dynamic Workload Broker network is placed subordinate to one of the Tivoli Workload Scheduler domain managers. From the point of view of the domain manger, the Tivoli Dynamic Workload Broker server appears to be a standard agent. Normally, a standard agent would have Tivoli Workload Manager installed. However, in the case of the Tivoli Dynamic Workload Broker server, it is Tivoli Dynamic Workload Broker that runs instead of Tivoli Workload Scheduler. To make Tivoli Dynamic Workload Broker appear to be a standard agent, there is an additional piece of software called the Tivoli Workload Scheduler agent (or TWS/TDWB Bridge). As the name implies, the Tivoli Workload Scheduler Agent creates a connection between Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker, essentially making the entire network of Tivoli Dynamic Workload Broker agents appear to be one single standard agent under the Tivoli Workload Scheduler network. This bridge is what allows jobs to be scheduled
126
from Tivoli Workload Scheduler and run on Tivoli Dynamic Workload Broker agents. Figure 3-23 shows where Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker fit in an integrated scheduling solution.
MASTERDM
AIX
DomainA
AIX
Domain Manager DMA
TWS Agent Dynamic Workload Broker Server

Linux
FTA1
HPUX
FTA2 OS/400
FTA4
Windows XP
TDWB Network
TDWB Agent 1
Linux
TDWB Agent 2
Linux
TDWB Agent 3
Linux
TDWB Agent 4
Linux
Figure 3-23 A Tivoli Workload Scheduler network with subordinate Tivoli Dynamic Workload Broker agents
Individually, Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker address specific scheduling needs. By combining their strengths into a single solution, it is possible to get the best of both worlds. The integrated TWS-TDWB solution allows the flexible, policy-based, and dynamically allocated workload of the Tivoli Dynamic Workload Broker network to be incorporated into the larger Tivoli Workload Scheduler scheduling environment. TDWB jobs can be scheduled from the Tivoli Workload Scheduler. Dependencies can be created between Tivoli Workload Scheduler jobs and Tivoli Dynamic Workload Broker
127
jobs. The status of these Tivoli Dynamic Workload Broker jobs is reported up the network hierarchy and is visible through the Tivoli Workload Scheduler users interfaces. Note: For a dynamically allocated workload in the Tivoli Dynamic Workload Broker network, the job log of each job will contain the name of the node where the job actually ran.
128
Part 2
Part
Deployment
In this part, we discuss the installation and configuration of Tivoli Workload Scheduler V8.4 and Tivoli Dynamic Workload Broker V1.2. We also cover some sample demonstration scenarios with these products.
129
130
Chapter 4.
Installation and configuration

In this chapter, we describe how to install and customize Tivoli Workload Scheduler on a UNIX/Linux (AIX 5L V5.3) system and Tivoli Dynamic Workload Broker on a Windows (2003) system. We demonstrate the installation and configuration processes in detail. By following these instructions, you should be able to successfully install Tivoli Workload Scheduler, Tivoli Dynamic Workload Broker, and configure them to meet your requirements. The following topics are discussed in this chapter: Installing and configuring Tivoli Workload Scheduler V8.4 on page 137 Installing Tivoli Dynamic Workload Console V8.4 on page 154 Installing Tivoli Job Scheduling Console V8.4 on page 163 Installing and configuring Tivoli Dynamic Workload Broker V1.2 on page 168
131
4.1 Software and hardware requirements for Tivoli Workload Scheduler

Note: For the complete and up-to-date hardware and software requirements, refer to the following link: http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm .tivoli.itws.doc/igmst02.htm#ToC_71
4.2 Tivoli Workload Scheduler software requirements

Here we discuss the Tivoli Workload Scheduler software requirements.
4.2.1 Supported operating systems

Table 4-2 on page 133 identifies the operating systems that are supported by the engine (where the support is not full, details are supplied in the notes). The abbreviations shown in Table 4-1 are used in Table 4-2 on page 133 (and elsewhere on this page).
Table 4-1 Supported operating systems: abbreviations used Abbreviation MDM BKM FTA CONN CLI JSC Description Master domain manager Backup master domain manager Fault tolerant agent (Since Version 8.3, there is no separate agent types called standard agent. All standard agents fault tolerant.) Connector for a Tivoli Workload Scheduler engine Command-line client Job Scheduling Console (See note 2 on page 135 and note 3 on page 135.)
132
Table 4-2 Supported operating systems for the TWS engine Platforms IBM AIX 5L Versions 5.2 and 5.3 IBM i5/OS Versions 5.3 and 5.4 HP-UX Version 11i v1 PA-RISC Version 11i v2 Itanium and PA-RISC Version 11i v3 Itanium Version 11i v3 PA-RISC Microsoft Windows Server 2003: Standard, Enterprise, and Data Center Server 2003: Standard, Enterprise, Data Center for 64-bit Itanium2 based systems Supported in tolerance mode only (32-bit) Server 2003: Standard and Enterprise for AMD64 and EMT64T Kernel 64 - Supported in tolerance mode only (32-bit) XP Professional with SP2 Vista Vista for AMD64 and EMT64T Red Hat Enterprise Linux 3.0 System x (IA32) and eSeries (AMD64 and EM64T) Kernel 32 (see note 4 on page 135) Power Systems Kernel 64 (see note 4 on page 135) System z Kernel 32 (see note 1 on page 134) System z Kernel 64 (see note 1 on page 134) X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X MDM/ BKM FTA CONN CLI JSC
X X X
X X X
X X X
Chapter 4. Installation and configuration
133
Platforms
MDM/ BKM
FTA
CONN
CLI
JSC
Red Hat Enterprise Linux 4.0 (see note 1 on page 134) System x and eSeries (AMD64 and EM64T) Kernel 32 (see note 4 on page 135) System x (AMD64 and EM64T) Kernel 64 Power Systems Kernel 64 System z Kernel 32 System z Kernel 64 X X X X X X X X X X X X X X X X X X X X X
Red Hat Enterprise Linux 5.0 (see note 1 on page 134) System x and eSeries (AMD64 and EM64T) Kernel 32 System x (AMD64 and EM64T) Kernel 64 Power Systems Kernel 64 System z Kernel 32 Solaris Operating Environment Version 9 Version 10 Version 10 AMD (Opteron) X X X X X X X X X X X X X X X X X X X X X X X X X X X
SUSE Linux Enterprise Server 9 and 10 (see note 1 on page 134) System x (IA32) and eSeries (AMD64 and EM64T) Kernel 32 System z, Kernel 32 System z, Kernel 64 Power Systems, Kernel 64 X X X X X X X X X X X X X X X X X X
Notes
1. InstallShield installation on Linux operating systems needs the bc utility to be installed. For further information, refer to: http://community.installshield.com/archive
134
2. The Job Scheduling Console is included in this table to aid you in planning. Its hardware and software requirements are documented in IBM Tivoli Workload Scheduler Job Scheduling Console User's Guide Version 8.4, SC32-1257. 3. The Job Scheduling Console is not supported on SUSE Linux Enterprise Server 10. 4. On Red Hat Enterprise Linux 3.0, DB2 V9.1 is not supported. On these systems, you need to install DB2 V8.2 manually before running the Tivoli Workload Scheduler installation.
4.3 Tivoli Dynamic Workload Broker hardware and software requirements

The Tivoli Dynamic Workload Broker server can be installed on AIX, HPUX, Solaris, Red Hat Enterprise Linux, SUSE Linux Enterprise Server, or Microsoft Windows (various versions). For the specific versions of these operating systems that are supported, and a description of the minimum hardware required, consult the IBM Tivoli Dynamic Workload Broker Installation and Configuration Guide Version 1.2, SC32-2282, which can be found at: http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.it dwb.doc/tdwbmst26.htm#prereqsw
4.4 Supported operating systems for other Tivoli products

IBM maintains a matrix on its Web site showing the supported operating systems for all Tivoli products, which can be found at: http://www.ibm.com/software/sysmgmt/products/support/Tivoli_Supported_P latforms.html
135
4.5 Our Tivoli Workload Automation environment

In Table 4-3, we describe our Tivoli Workload Automation test environment.
Table 4-3 Tivoli Workload Automation environment Host name melbourne Operating system IBM AIX 5L V5.3 TL5 Applications installed Tivoli Workload Scheduler V8.4 master IBM DB2 UDB V9.1 server Tivoli Dynamic Workload Console V8.4 Tivoli Dynamic Workload Broker Console V1.2 Tivoli Dynamic Workload Broker V1.2 server IBM DB2 UDB V9.1 server IBM WebSphere Application Server V6.1.0.11 Tivoli Dynamic Workload Broker Console V1.2 Tivoli Dynamic Workload Console V8.4 Tivoli Workload Scheduler Bridge Tivoli Workload Scheduler V8.4 fault tolerant agent Tivoli Dynamic Workload Broker V1.2 agent Tivoli Dynamic Workload Broker V1.2 agent Tivoli Dynamic Workload Broker V1.2 agent
athens
Windows Server 2003 SP1
prague toronto newyork london
Linux Red Hat EL 4.0 Windows Server 2003 SP1 Windows Server 2003 SP1 Windows Server 2003 SP1
136
4.6 Installing and configuring Tivoli Workload Scheduler V8.4

There are several methods to install Tivoli Workload Scheduler on a computer. For example, you can use the graphical installation wizard, twsinst command, or a Software Distribution product such as IBM Tivoli Configuration Manager or IBM Tivoli Provisioning Manager. In a large scale environment, provisioning the agents through IBM Tivoli Configuration Manager or IBM Tivoli Provisioning Manager works well. This is a quick way to set up your Tivoli Workload Scheduler environment when you do not have local access to the target machines. In this section, we describe how to install Tivoli Workload Scheduler on AIX 5L V5.3 using the SETUP.sh script. We also describe how to install the additional components, Tivoli Job Scheduling Console V8.4 and Tivoli Dynamic Workload Console V8.4. You can refer to IBM Tivoli Workload Scheduler Planning and Installation Guide Version 8.4, SC32-1273 for more information about installing Tivoli Workload Scheduler components. Important: Before installing Tivoli Workload Scheduler, you have to make sure that your computer meets the necessary hardware and software requirements of Tivoli Workload Scheduler. See 4.1, Software and hardware requirements for Tivoli Workload Scheduler on page 132 for more details.
Note: The twsinst script is supported only for the installation of fault tolerant agents, and not a master domain manager.
4.6.1 Tivoli Workload Scheduler V8.4 installation

To install a Tivoli Workload Scheduler V8.4 master domain manager (MDM), follow these steps: 1. Insert the product installation CD and mount the device and launch ./SETUP.sh. Note: If you do not have the Installation CD and have downloaded the software from the IBM Tivoli Passport Advantage Web site, just copy the files to the destination computer and run the ./SETUP.sh script.
137
2. The installer displays the language selection box, as shown in Figure 4-1. Accept either the default language of English or choose your preferred language and click OK.
Figure 4-1 Installation setup language window
Note: This selection only specifies the language for Tivoli Workload Scheduler V8.4 installation dialog boxes. 3. The Tivoli Workload Scheduler Welcome window will be displayed, as shown in Figure 4-2 on page 139. Click Next to continue.
138
Figure 4-2 Welcome window
4. The License Agreement window will be displayed. Read the license agreement carefully. Click the Agree button if you accept the terms of the agreement, and click Next. Note: If you do not accept the license agreement and click Next, a window displays asking you if you really wish to decline the license agreement. If you click Yes, the InstallShield Wizard will be completed and the product will not be installed. Click Finish to exit the wizard.
139
5. The Installation choice window will be displayed, as shown in Figure 4-3. This is where you choose from installing a new instance, upgrading an existing instance, adding features to an existing instance of Tivoli Workload Scheduler, or installing the command-line client. Choose Install an instance of Tivoli Workload Scheduler and click Next. Note: The Upgrade Instance and Add new features are available only if you have an existing installation of Tivoli Workload Scheduler.
Figure 4-3 Installation choice window
6. The panel to choose the type of instance to install will be displayed, as shown in Figure 4-4 on page 141. Choose Master domain manager and click Next.
140
Figure 4-4 Type of Instance window
7. The user name and password window will be displayed, as shown in Figure 4-5 on page 142. Insert the user name and password and click Next. Note: On UNIX systems, the TWSUser must exist, so you have to create this user before the Tivoli Workload Scheduler installation. By default, Tivoli Workload Scheduler is installed under the HOME directory of the selected user. If you want another installation directory, you can link the HOME to the Tivoli Workload Scheduler installation directory after the installation is completed.
141
Figure 4-5 The user name and password window
8. The workstation configuration information window will be displayed, as shown in Figure 4-6 on page 144. Fill in your information and click Next. Company. Your Company name. This workstation name. Logical name for this workstation (can be different from host name). Master domain manager name. The name of the Master domain manager. TCP/IP port number (used by netman). The port number used by netman. Add the job stream SFinal. Select this option to add the default job stream SFinal to the Tivoli Workload Scheduler database definition.
142
Note: When you add the SFinal to your environment, you create the FINAL job stream that contains the JnextPlan steps. This job stream is scheduled to run everyday at 06.00 to maintain the old style Jnextday behavior. Automatically generate all the other Tivoli Workload Scheduler ports. Select this option to generate automatically all Tivoli Workload Scheduler ports with the default values. Important: If you have a firewall in your environment, remember to open the selected ports to permit the Tivoli Workload Scheduler communication. The ports are shown in Table 4-4.
Table 4-4 Default ports used during installation Port type HTTP transport (used by composer when HTTP protocol is selected) HTTPS transport (used by composer when HTTPS protocol is selected) Bootstrap / RMI (used by the graphical user interfaces) SOAP connector port SAS port Server authentication port Mutual authentication port ORB port Administration port Administration secure port Event Processor port Port number 31115 31116 31117 31118 31119 31120 31121 31122 31123 31124 31131
143
Figure 4-6 The workstation configuration window
Tip: The installation program, new with Tivoli Workload Scheduler V8.4, provides context help for a set of Tivoli Workload Scheduler Engine windows. This should help you understand installation parameter meanings that are not obvious at first look. 9. The Installation directory window will be displayed, as shown in Figure 4-7 on page 146. Choose your preferred installation directory and click Next. Note: The default Installation directory is the users home directory that was specified in step 7 on page 141.
144
Note: Select Create symbolic links to create links in the /usr/bin directory. Any existing Tivoli Workload Scheduler symbolic links are overwritten. The symbolic links are copies of the following executables: maestro at batch datecalc morestdl jobstdl parms The symbolic links created under /usr/bin are: lrwxrwxrwx 1 root system 21 Oct 25 13:47 datecalc -> /opt/TWS/bin/datecalc lrwxrwxrwx 1 root system 20 Oct 25 13:47 jobstdl -> /opt/TWS/bin/jobstdl lrwxrwxrwx 1 root system 20 Oct 25 13:47 maestro -> /opt/TWS/bin/maestro lrwxrwxrwx 1 root system 15 Oct 25 13:47 mat -> /opt/TWS/bin/at lrwxrwxrwx 1 root system 18 Oct 25 13:47 mbatch -> /opt/TWS/bin/batch lrwxrwxrwx 1 root system 21 Oct 25 13:47 morestdl -> /opt/TWS/bin/morestdl lrwxrwxrwx 1 root system 18 Oct 25 13:47 parms -> /opt/TWS/bin/parms
145
Figure 4-7 Installation directory window
10.The Database selection window will be displayed, as shown in Figure 4-8 on page 148. Select DB2 Universal database and click Next.
146
Note: If you want to use Oracle Database, you need to install the Oracle Client or Oracle Server before starting the installation wizard. In particular, you will need the following information (some of these have default values): Net Service Name Oracle Administrator User (default is system) Oracle Administrator Password Tivoli Workload Scheduler Oracle User (default is Tivoli Workload Scheduler user) Tivoli Workload Scheduler Oracle User Password (default is Tivoli Workload Scheduler user password) Tivoli Workload Scheduler data tablespace (default is USERS) Tivoli Workload Scheduler report tablespace (default is USERS) Tivoli Workload Scheduler temp tablespace (default is TEMP) Note that all tablespaces must be created before installation starts. Tivoli Workload Scheduler Oracle User is created by the installation and must not be created before installation. Contact your Oracle Database Administrator for an Oracle specific configuration.
147
Figure 4-8 Database selection window
11.The Database installation action window will be displayed, as shown in Figure 4-9 on page 149. Select Install DB2 UDB Enterprise Edition and Administration Client, version 9.1 and click Next. Note: You can also choose to use an existing DB2 Server installation, or install a DB2 UDB Administration Client. In this case, contact your DB2 database Administrator to have the credentials and the connection information to continue.
148
Figure 4-9 Database installation action window
12.The database installation information window will be displayed, as shown in Figure 4-10 on page 150. Fill in the information required and click Next. Instance name The name of the DB2 server instance. Instance port The port number of the DB2 server instance. DB2 server administrator user (administrator of the DB2 instance) The DB2 administrator user name. DB2 server administrator password The DB2 administrator password. Confirm DB2 server administrator password Retype the previous password.
149
Note: If the DB2 server administrator does not exist, it will be created automatically.
Figure 4-10 DB2 installation information
13.The DB2 installation directory will be displayed. Insert your preferred path and click Next. 14.The DB2 database configuration window will be displayed, as shown in Figure 4-11 on page 152. Click Next.
150
Note: Select Specify advanced configuration parameters for the IBM Tivoli Workload Scheduler database if you want to specify the following advanced parameters: Tablespace Name: The name of the DB2 instance tablespace. This tablespace is used to store scheduling objects and event rules. For information about DB2 tablespaces, refer to the DB2 documentation. Tablespace Path: The relative path of the DB2 tablespace. The path can be a relative or an absolute path. When the tablespace path is an absolute path, the DB2 administrator user must have complete access rights to the directory where the tablespace is installed. Report Tablespace Name: The name of the tablespace for storing report data. The default name is TWS_LOG. Report Tablespace Path: The path of the tablespace for storing report data. The default path is TWS_LOG. The path can be relative or absolute. When the tablespace path specified is an absolute path, the DB2 administrator user must have complete access rights to the directory where the tablespace is installed.
151
Figure 4-11 DB2 database configuration window
Note: Report Tablespace Name and Report Tablespace Path are two new parameters in the installation program available with Tivoli Workload Scheduler V8.4.
152
15.The Summary window will be displayed, as shown in Figure 4-12. This window contains all the information that you have provided in the previous steps.
Figure 4-12 Summary window
153
16.The DB2 install script is needed to complete the installation. Select the path where the script is located, when requested, as shown in Figure 4-13.
Figure 4-13 DB2 installation script selection window
17.The Installation completed window will be displayed. Click Finish to end the InstallShield Wizard.
4.6.2 Installing Tivoli Dynamic Workload Console V8.4

Tivoli Dynamic Workload Console V8.4 provides a Web interface to directly manage the plan. Important: You must have Tivoli Dynamic Workload Console installed in order to be able to use the new features of Tivoli Workload Scheduler V8.4 (that is, Event driven scheduling, reporting, and so on).
154
In this section, we describe how to install Tivoli Dynamic Workload Console V8.4 on AIX 5L V5.3. To install Tivoli Dynamic Workload Console V8.4, follow these steps: 1. Insert the product installation CD and launch ./setup.bin, which is located in the /WEBUI/AIX directory. Note: If you do not have the Installation CD and have downloaded the software from IBM Tivoli Passport Advantage Web site, just copy the files to the destination computer and run the ./setup.bin script. 2. The installer displays the language selection window, as shown in Figure 4-14. Accept either the default language of English or choose your preferred language and click OK.
Figure 4-14 Language selection window
155
3. The IBM Tivoli DynamicWorkload Console Welcome window will be displayed, as shown in Figure 4-15. Click Next to continue.
Figure 4-15 TDWC welcome window
4. The License Agreement window will be displayed. Read the license agreement carefully. Click the Agree button if you accept the terms of the agreement, and click Next. Note: If you do not accept the license agreement and click Next, a window displays asking you if you really wish to decline the license agreement. If you click Yes, the InstallShieldWizard will be completed and the product will not be installed. Click Finish to exit the wizard. 5. The Installation choice box will be displayed, as shown in Figure 4-16 on page 157. Here is where you choose between installing Tivoli Dynamic Workload Console and the Embedded version of WebSphere Application Server V6.1, or install Tivoli Dynamic Workload Console on an existing installation of WebSphere Application Server. Choose Install Tivoli Dynamic Workload Console and the embedded version of WebSphere Application Server version 6.1 and click Next.
156
Note: For more information about installing Tivoli Dynamic Workload Console on an existing WebSphere Application Server, see 4.8, Installing Tivoli Dynamic Workload Console V8.4 on an existing WebSphere Application Server V6.1 on page 209.
157
6. The Installation directory window will be displayed, as shown in Figure 4-17. Insert your preferred directory and click Next.
7. The installation type window will be displayed, as shown in Figure 4-18 on page 159. Here you can choose between Default Installation and Advanced Installation. Select Default Installation and click Next. Note: If you want to use different settings, select Advanced Installation and click Next. Figure 4-19, Figure 4-20, and Figure 4-21 will be displayed in the specified order. Modify each window as you wish and click Next.
158
Figure 4-18 Type of installation window
Figure 4-19 Advanced Installation window 1 of 3
159
160
8. The Administrative user credentials window will be displayed, as shown in Figure 4-22. Insert the Administrative user credentials and click Next.
Figure 4-22 Administrative user credential window
9. The wasadmin roles window will be displayed, as shown in Figure 4-23 on page 162. The wasadmin user needs specific roles to use the Tivoli Dynamic Workload Console. In this window, you can select the products for which you want to give these roles to the administrator. Choose the products and click Next.
161
Figure 4-23 wasadmin roles window
10.The summary window will be displayed, as shown in Figure 4-24. Click Install.
162
11.The Successful installation window will be displayed, as shown in Figure 4-25. In this window, you can find the instructions to launch the Integrated Solutions Console for IBM Tivoli Dynamic Workload Console. Click Finish to end the InstallShield Wizard and close the window. Note: If you did not change the default port, the following addresses will be used: http://<yourmachinehostname>:29060/ibm/console https://<yourmachinehostname>:29043/ibm/console
Figure 4-25 Successful installation window
4.6.3 Installing Tivoli Job Scheduling Console V8.4

In 4.6.2, Installing Tivoli Dynamic Workload Console V8.4 on page 154, we show the installation of Tivoli Dynamic Workload Console, which allows you to work on the plan functions. In this section, we show you how to install Job Scheduling Console (JSC) V8.4. Job Scheduling Console is a Java based administrative interface used to manage the plan and the database. It is usually installed on an operators or administrators personal computers, while Tivoli Dynamic Workload Console is a Web-based application accessible through a Web browser.
163
Important: Remember that you must have Tivoli Dynamic Workload Console installed in order to be able to use the new features of Tivoli Workload Scheduler V8.4 (that is, Event Driven Scheduling and Reporting). In this section, we install the Tivoli Job Scheduling Console V8.4 on AIX 5L V5.3. Note that an installation on other platforms is very similar. To install Tivoli Job Scheduling Console V8.4, follow these steps: 1. Insert the product installation CD and launch ./setup.bin, which is located in the /INSTALLER directory. Note: If you do not have the Installation CD and have downloaded the software from the IBM Tivoli Passport Advantage Web site, just copy the files to the destination computer and run the ./setup.bin script. 2. The installer displays the language selection window, as shown in Figure 4-26. Accept either the default language of English or choose your preferred language and click OK.
3. The Tivoli Job Scheduling Console Welcome window will be displayed, as shown in Figure 4-27 on page 165. Click Next to continue.
164
Figure 4-27 Welcome window
4. The installation directory will be displayed, as shown in Figure 4-28. Enter your preferred directory and click Next.
165
5. The shortcut window will be displayed, as shown in Figure 4-29. Here you can choose to create a shortcut icon under /opt/ISMP/dt/appconfig/appmanager/C with the name that you have indicated in the shortcut window. Note: The shortcut is also linked in /etc/dt/appconfig/appmanager/C.
Important: If you used blank spaces in the name of the shortcut, the blanks will be replaced with _ (underscore). For example if you used JSC 8.4 it will be located in /opt/ISMP/dt/appconfig/appmanager/C/JSC_8.4 and /etc/dt/appconfig/appmanager/C/JSC_8.4.
Figure 4-29 Shortcut window
6. The summary window will be displayed, as shown in Figure 4-30 on page 167. Click Next to continue.
166
7. The installation successful window will be displayed. Choose Next to continue. 8. To complete the installation, click Finish in the InstallShield finish window, as shown in Figure 4-31 on page 168.
167
Figure 4-31 InstallShield finish window
4.7 Installing and configuring Tivoli Dynamic Workload Broker V1.2

IBM Tivoli Dynamic Workload Broker provides dynamic management of your environment, analyzes job requirements, and launches and monitors jobs. IBM Tivoli Dynamic Workload Broker improves your workload by load balancing across resources. New resources are automatically discovered using the Agent Manager and integrated in the scheduling environment. In this section, we describe how to install IBM Tivoli Dynamic Workload Broker V1.2 on a Windows 2003 machine, using the launchpad.exe graphical interface. We also describe the installation of the Job Brokering Definition Console, which is needed to create and modify Job Submission Description Language (JSDL) files. See 4.7.4, Installing Job Brokering Definition Console V1.2 on page 205 fore more details.
168
Important: Before installing IBM Tivoli Dynamic Workload Broker, ensure that DB2 (or Oracle) and WebSphere Application Server V6.1 are already installed to deploy the product. See 4.7.2, Installing IBM DB2 Universal Database V9.1 on page 184 or 4.7.3, Installing WebSphere Application Server V6.1 on page 197
4.7.1 IBM Tivoli Dynamic Workload Broker V1.2 installation

To install IBM Tivoli Dynamic Workload Broker V1.2 Server, follow these steps: 1. Insert the product installation CD and double click launchpad.exe. The graphical interface will be displayed, as shown in Figure 4-32. Click Install the IBM Tivoli Dynamic Workload Broker Server to continue. Note: If you do not have the Installation CD and have downloaded the software from the IBM Tivoli Passport Advantage Web site, just copy the files to the destination computer and run launchpad.exe.
Figure 4-32 IBM Tivoli Dynamic Workload Broker launchpad
169
2. The installer displays the language selection window, as shown in Figure 4-33. Accept either the default language of English or choose your preferred language and click OK.
3. The IBM Tivoli Dynamic Workload Broker welcome window will be displayed, as shown in Figure 4-34. Click Next to continue.
Figure 4-34 IBM Tivoli Dynamic Workload Broker welcome window
4. The License Agreement box will be displayed. Read the license agreement carefully. Click the Agree button if you accept the terms of the agreement, and click Next.
170
Note: If you do not accept the license agreement and click Next, a window displays asking you if you really wish to decline the license agreement. If you click Yes, the InstallShieldWizard will be completed and the product will not be installed. Click Finish to exit the wizard. 5. The installation directory window will be displayed, as shown in Figure 4-35. Insert your preferred directory and click Next.
6. The Installation choice window will be displayed, as shown in Figure 4-36 on page 172. Here you can choose two different kinds of installation: Typical Automatically installs the following components: Tivoli Agent Manager Tivoli Dynamic Workload Broker Database Tivoli Dynamic Workload Broker Server Tivoli Workload Scheduler Bridge
171
Custom All the above IBM Tivoli Dynamic Workload Broker extensions
Select Custom and click Next.
7. The custom installation window will be displayed, as shown in Figure 4-37 on page 173. In this section, we do not need to install the Tivoli Workload Scheduler Bridge to integrate an existing Tivoli Workload Scheduler environment. De-select Tivoli Workload Scheduler Bridge and click Next. Note: You can install the Tivoli Workload Scheduler Bridge later by running the same installation wizard.
172
Important: To enable communication between Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker, you need to install and configure the Tivoli Workload Scheduler Bridge. The Tivoli Workload Scheduler Bridge is installed on the Tivoli Dynamic Workload Broker server and emulates the behavior of an Tivoli Workload Scheduler standard agent. The Tivoli Workload Scheduler Bridge contains a subset of the standard agent features to enable the user to manage the life cycle of Tivoli Workload Scheduler jobs in Tivoli Dynamic Workload Broker.
Note: In the IBM Tivoli Dynamic Workload Broker - Extension, you can enable the following features: Enterprise Workload Manager (EWLM) IBM Tivoli Change and Configuration Management Database (CCMDB) IBM Tivoli Provisioning Manager
Figure 4-37 Custom installation window
173
8. The database selection window will be displayed, as shown in Figure 4-38. Select DB2 and click Next.
Figure 4-38 Database selection window
174
9. The database connection window will be displayed, as shown in Figure 4-39. Insert the required connection information and click Next.
Figure 4-39 Database connection box
175
10.The database customization box will be displayed, as shown in Figure 4-40. Customize the tablespace creation and click Next.
Figure 4-40 Database customization window
176
11.The Application Server connection window will be displayed, as shown in Figure 4-41. Insert the required connection information and click Next.
Figure 4-41 Application Server connection window
177
12.The Tivoli Dynamic Workload Broker port selection window will be displayed, as shown in Figure 4-42.
Figure 4-42 Tivoli Dynamic Workload Broker port selection window
13.The Tivoli Agent Manager information window will be displayed, as shown in Figure 4-43 on page 179. Insert the information and click Next. Note: You can also choose to configure the Advanced Installation Settings. See Figure 4-44 and Figure 4-45 for more information.
178
Figure 4-43 Tivoli Agent Manager information window
Figure 4-44 Advanced installation information window 1 of 2
179
Figure 4-45 Advanced installation information window 2 of 2
14.The Restart Application Server box will be displayed, as shown in Figure 4-46 on page 181. To complete the installation, the Application Server must be restarted. Here you can choose to do this automatically.
180
Select Yes, insert the administrator user and password credentials, and click Next.
Figure 4-46 Restart Application Server window
181
15.The installation summary window will be displayed, as shown in Figure 4-47. Click Install to continue.
Figure 4-47 Installation summary window
182
16.The summary of completed steps window will be displayed, as shown in Figure 4-48. Here you can see all operations performed during the installation. Click Next to continue.
Figure 4-48 Summary of completed steps window
183
17.The Installation completed window will be displayed, as shown in Figure 4-49. Click Finish.
Figure 4-49 Installation Completed window
4.7.2 Installing IBM DB2 Universal Database V9.1

To install IBM DB2 Universal Database on Windows 2003, follow these steps: 1. Insert the product installation CD and launch setup.exe. Note: If you do not have the Installation CD and have downloaded the software from the IBM Tivoli Passport Advantage Web site, just copy the files to the destination computer and run the setup.exe command.
184
2. The DB2 Setup launchpad will be displayed. Select Install a Product in the left side menu, as shown in Figure 4-50, then click Install New to start the DB2 Enterprise Server Edition installation.
Figure 4-50 DB2 Setup launchpad
185
3. The DB2 Setup Wizard for DB2 Enterprise Server Edition V9.1 window will be displayed, as shown in Figure 4-51. Click Next to continue.
Figure 4-51 Db2 Setup Wizard window
4. The License Agreement window will be displayed. Read the license agreement carefully. Select the Agree button if you accept the terms of the agreement, and click Next. Note: If you do not accept the license agreement and click Next, a window displays asking you if you really wish to decline the license agreement. If you click Yes, the InstallShieldWizard will be completed and the product will not be installed. Click Finish to exit the wizard.
186
5. The installation type window will be displayed, as shown in Figure 4-52. Select Typical and click Next.
Figure 4-52 Installation type window 1 of 2
187
6. A second Installation type window will be displayed to choose if you want Install the Product, create only the Response file, or both. See Figure 4-53. Select Install DB2 Enterprise Server Edition on this computer and save my settings in a response file and click Next to continue.
Figure 4-53 Installation type window 2 of 2
188
7. The Installation directory window will be displayed, as shown in Figure 4-54. Insert the preferred Installation directory and click Next.
189
8. The User information window will be displayed, as shown in Figure 4-55. Insert the user name and password for the DB2 administrator, check Use the same user name and password for the remaining DB2 services, and click Next.
Figure 4-55 User information window
9. The Instance configuration window will be displayed, as shown in Figure 4-56 on page 191. Select the instance DB2 and click Next. Note: You can see the configuration windows in Figure 4-57, Figure 4-58, and Figure 4-59.
190
Figure 4-56 Instance configuration window
Figure 4-57 Instance configuration window 1 of 3
191
192
10.The DB2 tools catalog window will be displayed, as shown in Figure 4-60. De-select Prepare the DB2 tools catalog and click Next.
Figure 4-60 DB2 tools catalog window
193
11.The SMTP server configuration window will be displayed, as shown in Figure 4-61. De-select Set up your DB2 server to send notifications and click Next.
Figure 4-61 SMTP Server configuration window
194
12.The operating system security window will be displayed, as shown in Figure 4-62. De-select Enable operating system security and click Next.
Figure 4-62 Operating system security window
195
13.The summary installation window will be displayed, as shown in Figure 4-63. Here you can see the features that will be installed. In this case, we chose to install the product and create the response file. Click Finish to continue.
Figure 4-63 Summary installation window
14.The Setup completed window will be displayed, as shown in Figure 4-64 on page 197. You can consult the log file to check if all steps are completed successfully. Click Finish to close the Setup window.
196
Figure 4-64 Setup completed window
15.The DB2 First Step Welcome Launchpad will be displayed. Select Exit to close the launchpad.
4.7.3 Installing WebSphere Application Server V6.1

To install WebSphere Application Server V6.1, follow these steps: 1. Insert the product installation CD and run launchpad.exe. Note: If you do not have the Installation CD and have downloaded the software from IBM Tivoli Passport Advantage Web site, just copy the files to the destination computer and run launchpad.exe command.
197
2. The welcome launchpad window will be displayed, as shown Figure 4-65. Click Launch the installation wizard for WebSphere Application Server to continue.
Figure 4-65 Welcome launchpad window
3. The Welcome Wizard window will be displayed, as shown in Figure 4-66 on page 199. Click Next to continue.
198
Figure 4-66 Welcome wizard window
4. The License Agreement window will be displayed. Read the license agreement carefully. Click the Agree button if you accept the terms of the agreement, and click Next. Note: If you do not accept the license agreement and click Next, a window displays asking you if you really wish to decline the license agreement. If you click Yes, the InstallShieldWizard will be completed and the product will not be installed. Click Finish to exit the wizard. 5. Now the IBM WebSphere Application Server wizard will check your system prerequisites. Your operating system should complete the prerequisites check successfully. Click Next to continue the installation. 6. The Sample Applications window will be displayed. Deselect Install the sample applications and click Next.
199
7. The Installation directory window will be displayed, as shown in Figure 4-67. Insert your preferred installation directory and click Next.
200
8. The Security enablement window will be displayed, as shown in Figure 4-68. Select Enable administrative security insert user name and password for the WebSphere administrator and click Next to continue. Note: Enabling the administrative security is a good practice. Remember that these credentials are used to access the Tivoli Dynamic Workload Console and Tivoli Dynamic Workload Broker applications.
Figure 4-68 Security enablement window
201
9. The installation summary window will be displayed, as shown in Figure 4-69. Click Next to continue.
Figure 4-69 Installation summary window
202
10.The installation result window will be displayed, as shown in Figure 4-70. You should have successfully installed IBM WebSphere Application Server V6.1 on Windows 2003. Click Finish to complete.
Figure 4-70 Installation result window
203
11.After the installation, the First Step window will be displayed automatically, as shown in Figure 4-71. Click Start the server wait until the server is opened for e-business, as shown in Figure 4-72 on page 205.
Figure 4-71 First Step window
204
Figure 4-72 Server started window
4.7.4 Installing Job Brokering Definition Console V1.2

The Job Brokering Definition Console provides an easy-to-use graphical interface for creating and editing jobs based on the Job Submission Description Language (JSDL) schema. To install Job Brokering Definition Console V1.2, follow these steps: 1. To install the Job Brokering Definition Console V1.2, you can use the same Launchpad used to install the IBM Tivoli Dynamic Workload Broker V1.2, as shown in Figure 4-32 on page 169. Click Install the Job Brokering Definition Console to continue. 2. The installer displays the language selection window, as shown in Figure 4-73. Accept either the default language of English or choose your preferred language and click OK.
205
3. The welcome window for installing IBM Tivoli Workload Broker Job Brokering Definition Console will be displayed, as shown in Figure 4-74. Click Next to continue.
Figure 4-74 Welcome installation window
4. The License Agreement window will be displayed. Read the license agreement carefully. Click the Agree button if you accept the terms of the agreement, and click Next. Note: If you do not accept the license agreement and click Next, a window displays asking you if you really wish to decline the license agreement. If you click Yes, the InstallShieldWizard will be completed and the product will not be installed. Click Finish to exit the wizard.
206
5. The installation directory window will be displayed, as shown in Figure 4-75. Insert your preferred directory and click Next.
207
6. The summary installation window will be displayed, as shown in Figure 4-76. Click Install to continue.
Figure 4-76 Summary installation window
7. The installation completed window will be displayed, as shown in Figure 4-77 on page 209. Click Finish to close the InstallShield wizard.
208
Figure 4-77 Installation completed window
4.8 Installing Tivoli Dynamic Workload Console V8.4 on an existing WebSphere Application Server V6.1
In this section, we describe how to install Tivoli Dynamic Workload Console V8.4 on an existing installation of WebSphere Application Server V6.1. This section is necessary when you must deploy the Tivoli Dynamic Workload Console in a preexisting production environment. The installation on an existing WebSphere Application Server allows you to reduce the number of running processes on the server. Important: Before starting the installation, ensure that your WebSphere Application Server version is 6.1.0.9 or later. The installation will not continue if the WebSphere Application Server discovered is not aligned. You also need the UpdateInstaller installed on the machine. It is necessary to upgrade the Integrated Solutions Console to Version 7.1
209
To install Tivoli Dynamic Workload Consoled V8.4 on an existing WebSphere Application Server V6.1 on a Windows 2003 Server, follow these steps: 1. Insert the product installation CD and launch launchpad.exe. Note: If you do not have the Installation CD and have downloaded the software from IBM Tivoli Passport Advantage Web site, just copy the files to the destination computer and run launchpad.exe. 2. The welcome launchpad window will be displayed, as shown in Figure 4-78. Select Install IBM Tivoli Dynamic Workload Console and click Install the IBM Tivoli Dynamic Workload Console.
Figure 4-78 Welcome launchpad window
3. The installer displays the language selection window, as shown in Figure 4-79 on page 211. Accept either the default language of English or choose your preferred language and click OK.
210
4. The IBM Tivoli DynamicWorkload Console Welcome window will be displayed, as shown in Figure 4-80. Click Next to continue.
Figure 4-80 TDWC welcome window
5. The License Agreement window will be displayed. Read the license agreement carefully. Click the Agree button if you accept the terms of the agreement, and click Next. Note: If you do not accept the license agreement and click Next, a window displays asking you if you really wish to decline the license agreement. If you click Yes, the InstallShieldWizard will be completed and the product will not be installed. Click Finish to exit the wizard.
211
6. The Installation choice window will be displayed, as shown in Figure 4-81. Here is where you choose between installing Tivoli Dynamic Workload Console and the Embedded version of WebSphere Application Server V6.1, or install Tivoli Dynamic Workload Console on an existing installation of WebSphere Application Server. Choose Install Tivoli Dynamic Workload Console on an existing installation of WebSphere Application Server and click Next.
212
7. The Identify WebSphere Application Server installation window will be displayed, as shown in Figure 4-82. Fill the form with the information required and click Next.
Figure 4-82 Identify WebSphere Application Server installation window
213
8. The WebSphere Update installer location window will be displayed, as shown in Figure 4-83. Specify the location of the WebSphere Update installer and click Next.
Figure 4-83 WebSphere Update installer location window
214
9. The administrative credential window will be displayed, as shown in Figure 4-84. Provide the administrative credentials and click Next.
Figure 4-84 Administrative credential window
215
10.The wasadmin roles window will be displayed, as shown in Figure 4-85. The wasadmin user needs specific roles use Tivoli Dynamic Workload Console. In this window, you can select the products for which you want to automatically give these roles to the administrator. Choose the products and click Next.
Figure 4-85 Wasadmin roles window
216
11.The summary window will be displayed, as shown in Figure 4-86. Click Install.
217
12.The Successful installation window will be displayed, as shown in Figure 4-87. In this window, you can find the instructions to reach the Integrated Solutions Console for IBM Tivoli Dynamic Workload Console. Click Finish to end the InstallShield Wizard and close the window.
Figure 4-87 Successful installation window
218
Chapter 5.
Demonstration scenarios
In this chapter, we will focus on some demonstration scenarios for Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker. We will also show you an example scenario where both Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker are used. This chapter has the following sections: Tivoli Workload Scheduler quick-start demonstration on page 220 Tivoli Workload Scheduler custom reports demonstration on page 248 IBM Tivoli Dynamic Workload Broker V1.2 scenario on page 255 Tivoli Workload Scheduler V8.4 and Tivoli Dynamic Workload Broker V1.2 integration scenarios on page 260
219
5.1 Tivoli Workload Scheduler quick-start demonstration

In this section, several scenarios are presented to explain basic workload scheduling concepts and to demonstrate how to perform rudimentary tasks like creating jobs and job streams. Whether you are new to Tivoli Workload Scheduler or completely new to job scheduling, these scenarios should help you get up and running quickly with Tivoli Workload Scheduler. The scenarios presented in this section will show you how to: Create a job. Create a new job from an existing job. Create a job stream containing multiple jobs. Schedule a job stream for automatic submission. Submit a job stream. Submit an ad hoc job. Browse a job log. These scenarios show how to perform these actions in the Tivoli Job Scheduling Console, the primary graphical interface to Tivoli Workload Scheduler. You will need to launch Job Scheduling Console and log into the Tivoli Workload Scheduler master to perform these actions.
5.1.1 Create a job

The job is the basic unit of work in a Tivoli Workload Scheduler network. A job is essentially just a named pointer to an executable command, program, or script. When you define a job, you must specify at least four pieces of information: A name for the job. This is the jobs unique identifier in the Tivoli Workload Scheduler database. Job names can be up to forty (40) characters long. The name of the executable command, program, or script to run. It is often best to specify the full path name to the executable. The user that runs the job. Tivoli Workload Scheduler will switch to this user just prior to running the job, using a mechanism similar to that used by the su command in UNIX. The name of the workstation where the job should be run.
220
In the following scenario, we will create a simple test job that echoes the sentence Hello, world: 1. First, expand the New Job Definition section in the Actions list, Then, click the name of your Tivoli Workload Scheduler master domain manager, as shown in Figure 5-1.
Figure 5-1 Creating a new job definition
2. The job Properties window should appear as shown in Figure 5-2 on page 222. Fill in the following information: Task Type: Your operating system type, for example, UNIX. Name: A name for the job, for example, test-job-1. Workstation Name: The name of the workstation where the job will run. Either type in the name or find it by clicking the ellipses button at right. Our workstation is master84. Login: The user who runs the job. We are going to run the job as the Tivoli Workload Scheduler user, called master84 on our system. The Tivoli Workload Scheduler user is often tws.
Chapter 5. Demonstration scenarios
221
Figure 5-2 Creating a new job definition: General properties
3. Next, click the Task tab on the left side of the window. The Task section should appear, as shown in Figure 5-3 on page 223. Enter the following information: Select the Command radio button. In the blank text field, type in the command you would like to run in this ad hoc job. In our example, we are running a simple echo command.
222
Figure 5-3 Creating a new job definition: Task properties
After entering the command to be run, click OK to save the job definition.
223
5.1.2 Create a new job from an existing job

It is often easier to create a copy of an existing job than to start from scratch and create an entirely new job definition. To do this, follow these steps: 1. First, find the original job definition, right-click it, and choose Create Another..., as shown in Figure 5-4.
Figure 5-4 Creating a new job definition from an existing job definition
2. A new job Properties window should appear, as shown in Figure 5-5 on page 225.
224
Figure 5-5 Creating a new job definition from an existing job definition: General properties
Change the job name. In our example, we used the name TEST-JOB-2. You can also change the other details of the job at this point, but because this is only a test job, we are going to leave these details just the same in this job as in the original one. Click OK to save the new job definition.
225
5.1.3 Create a job stream containing multiple jobs

A job stream is a collection of one or more jobs and their dependencies. In the previous scenarios, we created a couple of jobs. Next, we create a job stream containing those two jobs and a simple dependency between the first job and the second job. Here are the steps: 1. First, expand the New Job Stream section in the Actions list. Then, click the name of your Tivoli Workload Scheduler master domain manager, which should appear under the New Job Stream section. In our test system, the name of the master domain manager is master84, as shown in Figure 5-6.
Figure 5-6 Creating a new job stream
2. A new job stream Properties window should appear, as shown in Figure 5-7 on page 227.
226
Figure 5-7 Creating a new job stream: General properties
Here, you must provide at least the following two pieces of information: Name: A name for the new job stream. The name is the job streams unique identifier in the Tivoli Workload Scheduler database, so each job stream name must be unique on each workstation in the Tivoli Workload Scheduler network. In other words, you cannot have two job streams that have the same name defined on the same workstation in the Tivoli
227
Workload Scheduler network. Job stream names are limited to sixteen (16) characters. Once you have entered this data, click OK. You must also provide a name for the workstation where the job will run. A new job stream editor window will appear, as shown in Figure 5-8. The job stream editor window is where you add jobs to a job stream and set the dependencies on those jobs. Next, we add the first job to the job stream.
Figure 5-8 Creating a new job stream: adding the first job to the job stream
3. To add a job to the job stream, click the Actions menu, and choose Job Definition from the Add Job submenu. You can also add a job by clicking the Add Job Definition button. 4. A new Find Job Definition window will appear, as shown in Figure 5-9 on page 229.
228
Figure 5-9 Adding the first job to the job stream
In the text field labeled Find, type in the name of the job or the first part of the name followed by an asterisk (*). Click Start to begin the search for the job. In our example, the job we want to add is TEST-JOB-1, so we used the search term TEST*. Note: Object names in Tivoli Workload Scheduler, such as workstation names, job names, and job stream names, are not case-sensitive. You can use lowercase and uppercase letters interchangeably. Click the name of the job stream in the list (in our example, TEST-JOB-1), and click OK to add the job to the job stream.
229
An icon representing the job should now appear in the job stream editor window, as shown in Figure 5-10.
Figure 5-10 Creating a new job stream: one job created
5. Repeat steps 3 and 4 above to add a second job to the job stream. In our example, we add the job TEST-JOB-2 to the job stream.
230
Figure 5-11 Creating a job stream: two jobs successfully added to the job stream
An icon representing the second job should now appear in the job stream editor window. Tip: You can move the icons around by dragging and dropping them in the job stream editor window. You can also straighten the icons up by right-clicking in the white window background and choosing Arrange Icons from the pop-up menu. We now have a job stream containing two jobs. If we submitted the job stream as it is now, the jobs would both run at the same time. For example, say that we wanted them to run in order instead, TEST-JOB-1 first, and then TEST-JOB-2 second. How do we do that? It is actually quite simple: We just need to add a dependency between the two jobs.
231
6. To add a dependency between TEST-JOB-1 and TEST-JOB-2, follow these steps: a. Select Add Link from the Actions menu, as shown in Figure 5-12.
Figure 5-12 Adding a dependency between two jobs in a job stream
The mouse pointer will turn into crosshairs. a. Click and hold on the first job, drag the pointer to the second job, and release the button.
232
An arrow should appear between the jobs, pointing in the direction of the second job, as shown in Figure 5-13.
Figure 5-13 A job stream with two jobs and a dependency between the jobs
7. Choose Save from the File menu to save the job stream. We created a new job stream called TEST-STREAM-1 that contains two jobs: TEST-JOB-1 and TEST-JOB-2. We added a dependency between the two jobs so that when the job stream runs, the two jobs will run in sequence, TEST-JOB-1 first, and TEST-JOB-2 second. In the next scenario, we specify which days the job stream should run. We will do this by adding a run cycle to the job stream. Run cycles determine the days when the job is selected for inclusion in the plan.
233
5.1.4 Schedule a job stream for automatic submission

In this scenario, we will add a a simple, daily run cycle to the job stream that instructs Tivoli Workload Scheduler to schedule the job stream every day of the week. Do the following steps: 1. If the job stream editor is not already open, find the job stream in the All Job Streams database list and double-click it. We work with the same job stream that we created in the previous scenario. The default view of the job stream editor window when you first open is Graph View. Graph View is where you add or remove jobs, and set dependencies on those jobs. 2. However, to add a run cycle, we must switch to the Run Cycle View. To do this, select View Run Cycle, as shown in Figure 5-14.
Figure 5-14 Switching the job stream editor to the Run Cycle View
You can also switch to the Run Cycle View by clicking the Run Cycle View button.
234
3. Once in the Run Cycle View, select Add Add Run Cycle, as shown in Figure 5-15.
Figure 5-15 Adding a run cycle to a job stream
You can also add a run cycle by clicking the Add Run Cycle button.
235
The Run Cycle window should appear, as shown in Figure 5-16.
Figure 5-16 Adding a daily run cycle to select a job stream for execution every day of the week
4. In the Run Cycle window, enter the following settings, as shown in Figure 5-16: Name: everyday (This name is arbitrary, but it should reflect the settings you make to the run cycle.) Type: Daily Frequency: Every 1 Day On: Everyday Click OK to save the run cycle.
236
5. You should now see the everyday run cycle you have created appear in the Run Cycles list. If you click the name of the run cycle in the list (everyday), you can see the days that run cycle will select the job stream for execution, as shown in Figure 5-17.
Figure 5-17 Run Cycle View: displaying the effect of a run cycle
The days with blue bars are days that this run cycle explicitly includes. The turquoise-highlighted days are days when the job stream will run. Because this job stream has only one run cycle, these two sets of days are the same. If you add more than one run cycle, you can use this view to see how each run cycle affects the days when the job stream will run. Choose Save from the File menu to save the changes you have made to the job stream.
237
As it is now, the job stream is scheduled to run every day. However, in order to run, the job stream must first be included in the plan, and the first time it will have a chance to be included in the plan will be the next time the plan is built. By default, the plan is created only once per day at 5:59 in the morning. We could rebuild the plan now, but there is an easier way. To make the job stream run now, all we need to do is submit the job stream, as shown in the next section.
5.1.5 Submit a job stream

We submit the job stream that we just created. To submit the job stream, follow these steps: 1. First, expand the New Job Stream section in the Actions list. Then, click the name of your Tivoli Workload Scheduler master domain manager, which should appear under the New Job Stream section. In our test system, the name of the master domain manager is master84, as shown in Figure 5-18 on page 239.
238
Figure 5-18 Submitting a job stream
The Find Job Stream window should appear, as shown in Figure 5-19 on page 240.
239
Figure 5-19 Submitting a job stream: finding the job stream to submit
2. In the Find text field, type in the name of the job stream, or a part of the name followed by an asterisk (*). In our example we submit the job stream TEST-STREAM-1, so we found it by using the search term test*. Click Start to search for the job stream. 3. Select the job stream from the list and click OK. 4. Next, display the status of the job stream in a job stream plan list. We use the default plan list All Scheduled Job Streams and filter the results to show only job steams whose names contain the word test.
240
If you are quick enough, you might catch the job stream while it is still in the Ready status, as shown in Figure 5-20.
Figure 5-20 The TEST-STREAM-1 job stream in the Ready status
After a moment or two, the job stream should begin to run. It should not take long to complete. When the job stream has completed successfully, the status should be Successful (SUCC), as shown in Figure 5-21.
Figure 5-21 The TEST-STREAM-1 job stream in the Successful status
The jobs inside the job stream will also run: first, TEST-JOB-1, and second, TEST-JOB-2. You can display their status by viewing a job plan list. In our example, we display the default plan list Status of All Jobs and filter it to show only jobs whose names contain the word test. In Figure 5-22, you can see that both of the jobs in the job stream completed successfully.
Figure 5-22 The two jobs in TEST-STREAM-1, both in the Successful status
241
5.1.6 Submit an ad hoc job

An ad hoc job is a job that is submitted directly into the plan without first being defined as an object in the Tivoli Workload Scheduler database. Usually, you would choose to submit an ad hoc job if you just want to test something quickly and do not expect to have to run it again. Another reason to submit ad hoc jobs is if you need to submit unplanned work programmatically, for example, from a script. Note: To submit an ad hoc job from the command line or programmatically (inside a script or a program), use the conman sbd command. Consult the IBM Tivoli Workload Scheduler Reference Guide Version 8.4, SC32-1274 for more information about this command. If you are likely to need to run a job more than once or twice, it is probably more trouble than it is worth to submit each occurrence of the job as an ad hoc job; in this case, it makes more sense to define the job in the Tivoli Workload Scheduler database and submit the job by name. To submit an ad hoc job, perform the following steps: 1. First, expand the Submit section in the Actions list, and the Ad Hoc section under that. Then, click the name of your Tivoli Workload Scheduler master domain manager, which should appear under the Ad Hoc section. In our test system, the name of the master domain manager is master84, as shown in Figure 5-23 on page 243.
242
Figure 5-23 Submitting an ad hoc job
2. The job properties window will appear, as shown in Figure 5-24 on page 244. Fill in the following fields: The login name of the user who will run the job (in our case, we specify the name of the Tivoli Workload Scheduler user, master84). An alias (name) for the job, for example, test-adhoc-1.
243
Figure 5-24 Submitting an ad hoc job: General properties
3. Click the Task tab in the left side of the Properties window. The Task section should appear, as shown in Figure 5-25 on page 245. Enter the following information: Select the Command radio button. In the blank text field, type in the command you would like to run in this ad hoc job. In our example, we run a simple echo command.
244
Figure 5-25 Submitting an ad hoc job: Task properties
After entering the command to be run, click OK. The ad hoc job will be submitted immediately into the plan. To view the status and job log, refer to 5.1.7, Browse a job log on page 245.
5.1.7 Browse a job log

Once a job has been submitted into the plan and any dependencies the job has have been satisfied, the job will run. For every job that Tivoli Workload Scheduler executes, a job log is saved containing the standard output (stdout) and standard error (stderr) returned by the process executed by the job.
245
There are many reasons why you might want to browse the log of a job, including: To diagnose a job that ended in error To learn more about the cause of an error or warning message For a job with multiple steps, to discover where in the chain a problem arose To view output from the job, for example, reporting or statistical purposes Whatever the reason, viewing a job log is very simple. Note: You can display the job log of any job that has reached the EXEC (Running) state or has completed to the SUCC (Successful) or ABEND (Error) state.
Important: It is not possible to display the job log of a jobs that has ended in the FAIL state. FAILed jobs are jobs that Tivoli Workload Scheduler was not able to launch, usually due to typographical errors in the task path name, user, or insufficient permissions. To see the specific reason the job ended up in the FAIL state, look in the YYMMDD_TWSERGE.log file located in the TWSHome/stdlist/logs directory. In this scenario, we will display the job log of the ad hoc job we submitted in the previous scenario. You can use the same steps to display the log of any running or completed job. 1. Find the job in the plan, by displaying a the job in a job status list, for example the default list All Scheduled Jobs. In this example, we have filtered the output in Job Scheduling Console so that only jobs whose names contain the word test are displayed. 2. Right-click the row corresponding to the job and choose Browse Job Log, as shown in Figure 5-26 on page 247.
246
Figure 5-26 Browsing a job log
The job log should appear in a new window, as shown in Figure 5-27.
Figure 5-27 Browsing a job log: the job log window
247
5.2 Tivoli Workload Scheduler custom reports demonstration

Tivoli Workload Scheduler V8.4 adds a feature that allows the generation of advanced custom reports. The next scenario will show an example of how to generate such a custom report. The report we will generate here is a very simple one that displays job run statistics for all jobs. However, as you will see, it is also possible to be much more specific about which data is displayed in the report: 1. First, log in to the Tivoli Dynamic Workload Console (also sometimes called the Integrated Services Console). Expand the Tivoli Workload Scheduler category and the Customize and Generate Reports sub-category, as shown in Figure 5-28.
Figure 5-28 Customize and generate reports for Tivoli Workload Scheduler
248
2. To generate a custom Tivoli Workload Scheduler report, you must first create a task that specifies the details of the report you would like to generate. After you have created the report task, you generate the report by running that task. Click the New button (highlighted in blue in Figure 5-28 on page 248) to create a new task. A new page entitled Create Task will appear, as shown in Figure 5-29.
Figure 5-29 Creating a new task that generates a custom TWS Job Run Statistics Report
249
3. Make sure that Job Run Statistics Report is selected and click Next. A page with the heading Enter Task Information will appear, as shown in Figure 5-30.
Figure 5-30 Creating a Job Run Statistics Report task: entering the basic task information
Under Task Sharing Options, select All and click Next.
250
4. On the Report Header page, shown in Figure 5-31, you can specify the contents and appearance of the header that will appear at the top of the report. We do not need to change anything here, so just click Next.
Figure 5-31 Creating a Job Run Statistics Report task: configuration of the report header
251
5. On the Filter Criteria page, shown in Figure 5-32, you can enter parameters that specify which jobs you want to be included in the report. For the purposes of our demonstration, we will leave all of these fields at their default values. Click Next to save the report task.
Figure 5-32 Creating a Job Run Statistics Report task: specifying filter criteria
252
6. You should now be taken back to the list of custom report tasks. Click the check box to the left of the task you just created and click Run, as shown in Figure 5-33.
Figure 5-33 Running a newly-created custom report task
253
7. On the Choose Engine page, specify the Tivoli Workload Scheduler user name and password, as shown in Figure 5-34. Click the Enable Reporting check box and enter the database user name and password. Click OK to run the report task.
Figure 5-34 Running a custom report task: specifying scheduling engine details
The output from the report should appear in a new window, and should look similar to the output in Figure 5-35 on page 255. The custom reporting function is quite flexible, and you can create reports to show many types of information.
254
Figure 5-35 Excerpt from the output of the custom report task
5.3 IBM Tivoli Dynamic Workload Broker V1.2 scenario

IBM Tivoli Dynamic Workload Broker is an on demand scheduling infrastructure that provides dynamic management of your environment. It improves workload coordination and optimizes the use of IT infrastructure by constantly analyzing your environment. Tivoli Dynamic Workload Broker provides the means to create a job definition. A job definition contains the information required to determine on which system a job could run. When a job is submitted, Tivoli Dynamic Workload Broker analyzes job requirements and evaluates the resources based on the job definition.
255
You can also use Tivoli Dynamic Workload Broker as a stand-alone solution, as described in this section, or integrate with Tivoli Workload Scheduler, as described in 5.4, Tivoli Workload Scheduler V8.4 and Tivoli Dynamic Workload Broker V1.2 integration scenarios on page 260.
5.3.1 Resource optimization scenario

The following scenario shows how IBM Tivoli Dynamic Workload Broker automatically assigns jobs to the best available resource. To complete the scenario, follow these steps: 1. Create two different logical resources assigned to different computers. Define a different quantity for each logical resource. Table 5-1 shows how we assigned the resources. Suppose that we want to limit the number of connections to these computers, as shown in Figure 5-36.
Table 5-1 Logical resource assignment Host name NEWYORK TORONTO Logical resource Connection1 Connection2 Quantity 11 9
Figure 5-36 Logical resource view
256
2. To create a job requirement, open the Tivoli Dynamic Workload Broker Job Brokering Definition Console, open your job definition, and click the Resources tab. Here you can specify the resource requirements for your job. Our sample job needs to run on an x86 architecture at 64-bit. Click the Hardware Requirements tab. In the Candidate CPU Architectures window, click Add and select x86_64, as shown in Figure 5-37.
Figure 5-37 Hardware requirements view
257
3. Click the Software Requirements tab in the same window. Our job needs to run on a Windows 2000 or a Windows 2003 system and requires one connection. In the Candidate Operating System panel, click Add and select Windows 2000 and Windows 2003. In the Logical Resources window, click Add to add the resource type Connections, as shown in Figure 5-38.
Figure 5-38 Software requirements view
4. Once you have defined the job requirements, you can now upload the job definition in the Tivoli Dynamic Workload Broker database for submission. 5. To submit the job, log in to the Integrated Solution Console. Select Tivoli Dynamic Workload Broker Definitions Jobs. Search for your job name, select the job, and submit it from the Actions menu, as shown in Figure 5-39 on page 259.
258
Figure 5-39 Job submission view
6. The job will be routed to the computer with the majority of resources, as shown in Figure 5-40.
Figure 5-40 Job instances view
In this scenario, we used NEWYORK as the computer that has the best available resources. You can simply change this status by reducing the quantity of resources available on NEWYORK or increasing the value on TORONTO. This kind of scenario permits you to run a job on the computer that has the greater number of resources available.
259
5.4 Tivoli Workload Scheduler V8.4 and Tivoli Dynamic Workload Broker V1.2 integration scenarios
Tivoli Dynamic Workload Broker can work together Tivoli Workload Scheduler to schedule, monitor, and manage jobs. In this scenario, Tivoli Workload Scheduler is used to manage the submission of jobs and the resolution of dependencies, while Tivoli Dynamic Workload Broker features are used to identify resources where the jobs can run and to assign jobs to a resource in a way that makes efficient use of the available computer resources. Note: You can integrate Tivoli Dynamic Workload Broker V1.2 with Tivoli Workload Scheduler V8.4, V8.3, and V8.2.1. Using Tivoli Dynamic Workload Broker with Tivoli Workload Scheduler provides a number of benefits compared to a stand-alone Tivoli Workload Scheduler solution: Virtualization of the scheduling infrastructure by providing an abstraction layer on the resource selection Workload balancing by routing jobs among a group of resources according to the availability and activity levels of those resources Scheduling of IBM WebSphere Java 2 Enterprise Edition (J2EE) applications Automatic routing of jobs to the most appropriate resources based on job requirements Enhanced flexibility in workload distribution and running Automatic routing of jobs for which submission failed to appropriate resources Tivoli Workload Scheduler also provides the following features to Tivoli Dynamic Workload Broker: End-to-end scheduling infrastructure Scheduling, calendaring, planning, and choreographing capabilities To enable the communication between Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker, you need to install and configure the Tivoli Workload Scheduler Bridge. The Tivoli Workload Scheduler Bridge is installed on Tivoli Dynamic Workload Broker server and emulates the behavior of an Tivoli Workload Scheduler standard agent. The Tivoli Workload Scheduler Bridge contains a subset of the standard agent features to enable the user to manage the life cycle of Tivoli Workload Scheduler jobs in Tivoli Dynamic Workload Broker.
260
You can use the standard Tivoli Workload Scheduler procedures to submit and monitor jobs that are to be allocated resources by Tivoli Dynamic Workload Broker to the Tivoli Workload Scheduler Bridge. Jobs are then managed and monitored by Tivoli Dynamic Workload Broker and submitted to Tivoli Dynamic Workload Broker Agent. In this section, we will explain how to create and configure the Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker integration. We describe the Tivoli Workload Scheduler Bridge configuration, and an integration scenario to demonstrate the benefits of Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker integration.
5.4.1 Configuring Tivoli Workload Scheduler Bridge in the Tivoli Workload Scheduler environment
After installing the Tivoli Workload Scheduler Bridge, you must configure it as a standard agent in the Tivoli Workload Scheduler environment. To configure the Tivoli Workload Scheduler Bridge as a standard agent using the Tivoli Workload Scheduler Job Scheduling Console, perform the following steps: 1. Open the Tivoli Workload Scheduler Job Scheduling Console. 2. Click New Workstation in the Action List window. The window shown in Figure 5-41 on page 262 will appear. 3. Fill in the fields as required. In the Name text field, type the same name defined during the Tivoli Workload Scheduler Bridge. In the Workstation Type field, select Standard Agent. In the Node Name text field, type the host name of the computer where the Tivoli Workload Scheduler Bridge is installed. In the TCP Port text field, type the port specified during the Tivoli Workload Scheduler Bridge. The agent will use this port to communicate with the master. Check that the date and time are aligned with the Tivoli Workload Scheduler server to ensure that the correct timing information is provided. Note: If you do not know or remember all the parameters, you can view the configuration in the TWSAgentConfig.properties file. It is located in the Tivoli Dynamic Workload Broker server config directory.
261
Figure 5-41 New Workstation window
262
Note: Some of the features available for Tivoli Workload Scheduler standard agent are not supported by Tivoli Workload Scheduler Bridge. The following features are not supported: Return code mapping Centralized scripts
5.4.2 Integration scenario

After configuring the Tivoli Workload Scheduler Bridge, we can submit the Tivoli Dynamic Workload Broker jobs through Tivoli Workload Scheduler Job Scheduling Console or conman. In this section, we describe how you can integrate the scheduling features provided by Tivoli Workload Scheduler and the resource optimization features provided by Tivoli Dynamic Workload Broker.
Resource utilization scenario

In this scenario, we want use the IBM Tivoli Workload Scheduler to submit jobs to the best available resource using IBM Tivoli Dynamic Workload Broker. The following steps describe an example of the process to complete this scenario: 1. Create a new logical resource that shows database licenses and assigns the resource to the computer where it is located, as shown in Figure 5-42.
Figure 5-42 Logical resource view
263
2. Open the Job Brokering Definition Console and open your definition file. Select Resources Software Requirements in the Logical Resources panel and click Add to add a logical resource requirement. Insert DBResource of type DB2_Licenses and save the definition, as shown in Figure 5-43. In this way, the job will run only on the computer where the DB2Resource logical resource is assigned.
Figure 5-43 Job Brokering Definition Console view
3. Select Hardware Requirements. In the Physical Memory selection window, we can choose the amount of free physical memory needed by our sample job to run correctly, as shown in Figure 5-44 on page 265.
264
Figure 5-44 Physical memory assignment
4. Now we can upload the new definition to the IBM Tivoli Dynamic Workload Broker Server. Select the definition file and click the Upload button, or right-click the definition file and select Upload. Note: In the previous steps, we defined and uploaded a job in the IBM Tivoli Dynamic Workload Broker server. The IBM Tivoli Dynamic Workload Broker does not have scheduling capabilities, so, we need to set the IBM Tivoli Workload Scheduler to perform automatic and scheduled submissions of our job.
265
5. Open the Tivoli Workload Scheduler Job Scheduling Console. Create a new job definition using a workstation as the standard agent where the IBM Tivoli Dynamic Workload Broker server is installed. In the Task tab, insert the name of the job uploaded in the Tivoli Dynamic Workload Broker, as shown in Figure 5-45.
Figure 5-45 Job definition window
6. Create a new job stream definition and insert the job previously defined into the new job stream. 7. Now we are able to schedule the job submission. Open the job properties from the job stream editor. In the Time Restrictions tab, set the Latest Start Time to 10.00 PM and Repeat Range to every two minutes. Click OK to close the window.
266
8. Open the run cycle view and click Add Run Cycle. Insert a name for the run cycle, select Daily, and click Workdays, as shown in Figure 5-46. Click OK to close the window.
Figure 5-46 Run cycle definition window
267
9. In the Run Cycle view, you can see the days when the job is scheduled to run, as shown in Figure 5-47.
Figure 5-47 Run cycle view window
10.Save the job stream and close the editor. 11.Now you can submit the job stream, and the job will be automatically routed to the IBM Tivoli Dynamic Workload Broker and assigned to the best available resource that can handle the job requirements. Important: If none of the computers can handle the job requirements, the job will fail with a Resource allocation failed error.
In this example, we defined a job submission every two minutes from 06.00 AM to 10.00 PM from Monday to Friday, and, using IBM Tivoli Dynamic Workload Broker, the job will be submitted on the computer that has a minimum of 200 KB of free physical memory.
268
Chapter 6.
Event driven workload automation

Tivoli Workload Scheduler V8.4 offers many new useful features. One of the new key extensions is event driven workload automation (EDWA). This new feature allows the Tivoli Workload Scheduler to better reflect the needs of a rapidly changing on demand environment. The Tivoli Workload Scheduler was originally designed to automate the execution of a batch workload according to predefined calendars. While Tivoli Workload Scheduler was very powerful in calendar based scheduling, it was not that flexible when reacting to asynchronous events occurring in the environment. Of course, you could leverage the integrations with other IBM Tivoli products (such as Tivoli Enterprise Console or IBM Tivoli Monitoring) to accomplish this function, but that would bring some management complexity. EDWA allows Tivoli Workload Scheduler to react to asynchronous events, regardless of whether they occurred within or outside the Tivoli Workload Scheduler environment. Tivoli Workload Scheduler can react to a set of predefined events (such as job or job stream state changes, mail reception, file transfer completion, and so on). In addition, it is possible to create custom user defined events that can describe concrete conditions that are important for on demand workload automation. User defined actions can be created as well.
269
This chapter discusses following topics: Event driven workload automation highlights on page 271 Event driven workload automation logical design on page 271 Event driven workload automation implementation details on page 284 Working with event driven workload automation on page 297 Event driven workload automation demonstration on page 360
270
6.1 Event driven workload automation highlights

While we describe the event driven workload automation in detail later in this chapter, we want to highlight its most important benefits here: The event driven workload automation contains a set of out-of-box, predefined monitors and actions. Using these predefined templates, you can rapidly extend your current Tivoli Workload Scheduler environment with event driven capabilities. The predefined templates are ready for Tivoli Workload Scheduler self monitoring. The health of critical Tivoli Workload Scheduler components can be self-monitored and corrective actions can be triggered automatically. You can monitor the WebSphere Application Server status and state of Tivoli Workload Scheduler objects (such as jobs, job streams, workstations, and so on). The predefined templates also contain a built-in notification mechanism, such as e-mailing, Tivoli Enterprise Console (TEC) Event forwarding, and so on. The event driven workload automation can be managed by a very intuitive
Web interface. It can be managed by the command-line interface as well, if

necessary. The event driven workload automation is built-in feature and does not need external products as prerequisites. The event driven workload automation is an open solution. The generic events are supported. The solution allows you to plug in new event types, new event monitors, and actions. The development of these extensions does not require you to change the Tivoli Workload Scheduler code. The integration with some other Tivoli products is already built in.
6.2 Event driven workload automation logical design

This section describes the event driven workload automation logical design. We focus especially on the following topics: Events Event rules Event correlation conditions Actions Time out actions Event providers Action providers
Chapter 6. Event driven workload automation
271
6.2.1 The event driven workload automation concept

The concept of event driven workload automation is based on events, event rules, and actions. Events represent the conditions that occurred either inside or outside of the Tivoli Workload Scheduler environment. Based on the incoming events, we want to react using responsive actions. The logic that links the events to the actions is defined by the user within the
event rule.
Figure 6-1 demonstrates the concept of the event driven workload automation.
Figure 6-1 Event driven workload automation concept
6.2.2 Events
This section describes events in detail. Events represent the conditions that occur either inside or outside of the Tivoli Workload Scheduler environment. We can classify events from two different perspectives: Event type: Internal events External events
272
Event source: Events generated by built-in event providers Generic events We discuss these classifications in the following sub-sections.
Events classified by event type

Using this classification, we can divide events into: Internal events: Events that occur inside the Tivoli Workload Scheduler environment. Typical examples of internal events are: A job with a name that begins with IMPORTANT_JOB_* ended in the ABEND state. A workstation with a name that begins with ACCOUNTING_* has been unlinked. External events: Events that occurred outside the Tivoli Workload Scheduler environment. Typical examples of external events are: A file /finance/transfer/monthly_report.pdf has been created and is no longer being modified (which usually means that the file transfer completed). A message Process ended is written to the log file. Event XYZ has been issued on SAP system ABC.
Events classified by their originator

Using this classification, we can divide events into: Events generated by predefined event provider : This is the most common usage. Tivoli Workload Scheduler V8.4 offers a set of predefined event providers that monitor the usual conditions that are occurring either inside or outside of the Tivoli Workload Scheduler environment. When specific conditions are met on monitored targets, the event provider generates an event and sends it to central correlation engine called an event processor. Generic events generated by custom (user defined) event providers. Events generated by the user or script invoking the sendevent utility. The predefined set of events is determined by implemented event providers. We describe the event providers in 6.2.5, Event providers on page 281.
273
6.2.3 Event rules

An event rule defines which actions should be triggered based on incoming events. The event rule acts as a logical connector among events (inputs) and actions (outputs). An event rule definition consists of: An event(s) An event correlation condition An action(s) Usually there are many active event rules in the Tivoli Workload Scheduler environment. Each of the event rules defines different input conditions (what events must arrive) and different outputs (what shall be triggered). All event rules run in one central place called the Event Correlation Engine. The Event Correlation Engine is a sub-component of the Event Processor, which is the central point of the event driven workload automation architecture.
Event rule life cycle

This section describes the life cycle of an event rule. We describe the event rule from the moment when it is being defined by the user until the events are being received from the monitoring agents and the actions are being triggered. We provide the explanation in a form of a numbered list. Each step mentioned below is displayed in the Figure 6-2 on page 275: 1. The user creates an event rule. He uses a graphical Rule Editor for this task. Once the rule is saved, it is stored in the Tivoli Workload Scheduler database. 2. An event rule is built and activated in the Event Correlation Server. 3. Monitoring configurations are downloaded and activated on the Tivoli Workload Scheduler agents. 4. The monitoring agents start to monitor. If the defined condition occurs, the monitoring agent sends an event. 5. The Rules Correlation Server receives the events and checks if they match any defined rule. Incoming events can fully or partially satisfy correlation conditions of particular rules. Some incoming events can initialize timeouts for particular correlation conditions. 6. If a particular correlation condition is matched, the response actions are triggered.
274
If any initialized timeout expires, the timeout actions are triggered. 7. The instance of an event rule is created. The result of a triggered action is logged into the database. 8. The user uses the monitoring interface to query the status of event rule instances and triggered actions.
Figure 6-2 Event rule life cycle - numbered
275
Figure 6-3 explains the same topic in a schematic way.
Figure 6-3 Event rule life cycle schema
Event correlation conditions

This section explains how the incoming events are processed by active rules. Each incoming event is sequentially passed to all active rules. It means that the incoming event is passed to the first active rule, then to the second rule, and so on. Each rule matches the incoming events against its defined event correlation condition. Event correlation conditions determine if the incoming event will be processed by a rule or not. Only the event that matches the definition is accepted.
276
The term matches has following meaning: The type of the incoming event must be the same as defined in the rule (for example, Job Status Changed). The attributes in the incoming event must match the attributes of the defined event (for example, Workstation=ABC).
Correlation conditions types

There are three possible types of event correlation conditions: Single event (filter): This event correlation condition performs just simple matching, as explained above. Note: The synonym for event correlation condition single event is filter. If the correlation condition is set to single event, then the event rule definition must contain only one event. When a matching event arrives from the monitoring agent, the correlation condition is satisfied. Then the response action(s) can be triggered. A typical example of single event correlation condition: If the incoming event informs you that the job MONTHLY_REPORT ended with status ABEND, the condition is satisfied. The response action(s) can be triggered. Note: The correlation condition single event is the default one. If you are defining event rules containing only one event, you do not need to explicitly specify the single event correlation condition, because it is already preselected. Event set: In this case, the event rule definition must contain at least two events or more. All of the defined events must arrive in order to satisfy the condition, and then the response action(s) can be triggered. The order in which the events arrive is not important. A typical example of the event set correlation condition follows: We expect two events that must be received: The first event informs you that the job MONTHLY_REPORT running on the workstation ACCOUNTING_1 ended with status ABEND. The second event informs you that the job MONTHLY_REPORT running on the workstation ACCOUNTING_2 ended with status ABEND.
277
Only if both of these two events arrived would the correlation condition would be satisfied, and then the response action(s) can be triggered. The correlation condition event set does not reflect the order in which the events have arrived. The condition is satisfied when all events that are defined in the event rule arrive, regardless of their order. Event sequence: This is a special case of the event set correlation condition. The event rule definition must contain at least two events or more and their order is taken into account. All of the defined events must arrive in the defined order in order for the condition to be satisfied, and then the response action(s) can be triggered. A typical example of the event set correlation condition follows: We expect two events that must be received: The first event informs you that the job MONTHLY_REPORT running on workstation ACCOUNTING_1 ended with status SUCC. The second event informs you that the file /finance/transfer/monthly_report.pdf has been created on the workstation MANAGEMENT_3 and is no longer being modified (which usually means that the file transfer completed).
Only if both of these two events arrived in this order would the correlation condition would be satisfied, and then the response action(s) can be triggered. The correlation condition event sequence reflects the order in which the events arrived. The condition is satisfied only if all events defined in the event rule arrived in the defined order. If the order is not met, then the condition is not satisfied, even if all of the events arrive. Important: In the generally available version of Tivoli Workload Scheduler V8.4, the Event Processor is not persistent. This affects the handling of event sets and event sequences. If the event processor is stopped, switched, or crashes, all the received events are lost. If the subsequent events arrive after the restart of the event processor, they will not be correlated with the events that arrived before the restart. This can cause some conditions to be inaccurately evaluated and the response actions will not be triggered. This limitation will be removed in Tivoli Workload Scheduler V8.4 FP01.
278
Timeouts
An important option called timeout can be set to the following correlation conditions types: Event set Event sequence The timeout specifies that the condition must be satisfied in the defined time frame. When the timeout is specified for the correlation condition, two different results are possible: The first matching event arrives and the timeout counter is initialized. All defined events arrive within the defined timeout and the response actions are triggered. The first matching event arrives and the timeout counter is initialized. At least one of the defined events did not arrive before the timeout expired. The response actions are not triggered; instead, the timeout actions are triggered. Timeout actions can perform the same tasks as the response actions. The only difference is that timeout actions are triggered only if there is a timeout defined in the correlation condition and this timeout expires. Timeout notes: Timeouts can be set only on the event rules that contain multiple event definitions. This means that the event correlation condition for such rules must be set either to event set or event condition. The timeout counter starts to count down when the first event arrives. For event set, any of specified events is sufficient for initializing the counter. For event sequence, only the first defined event must arrive in order to initialize the timeout counter. The timeout specifies the time interval between the first and last event within the event set or event sequence. It does not specify the time interval between two particular events. For example, if there are three defined events in the set, all three events must arrive within the defined interval. The timeout is initialized after the first incoming event, but is not being re-initialized after the second event arrives.
279
6.2.4 Actions
Actions specify the tasks that should be performed if the incoming event(s) satisfy the correlation condition defined within the event rule. In general, we can classify actions as follows: Operational actions: These actions perform operative tasks within the Tivoli Workload Scheduler environment. Typical examples of operational actions are: Submit a job with the name CREATE_REPORT. Submit a job stream with the name PERFORM_CLEANUP. Reply to the prompt Prompt1. These actions are related to the Tivoli Workload Scheduler environment only. Notification actions: These actions notify either operators or other applications about particular conditions that have occurred in your environment. Typical examples of notification actions are: Send an e-mail with a defined body and subject to the defined recipients. Log a message into an internal audit database. Forward an event to Tivoli Enterprise Console. Even if you already have integrated Tivoli Workload Scheduler with Tivoli Enterprise Console using BmEvents.conf, the notification actions can be much more specific. The conditions that you may define in the event rules allow you to explicitly specify what you want to monitor. The unnecessary information is not sent to Tivoli Enterprise Console and thus saves processing time. Generic actions: This type of action is used for performing generic tasks. Typical examples of notification actions are: Run an operating system command on the event processor. Run a script on the event processor. Furthermore, we can classify actions from the timeout perspective: Response actions: Triggered when the event correlation condition of the event rule is satisfied. Timeout actions: Triggered when the event correlation condition of the event rule has been initiated, but not completely satisfied within the defined time interval. See Timeouts on page 279 for more information about timeouts.
280
The predefined set of actions is determined by implemented action providers. The description of action providers is provided in 6.2.6, Action providers on page 282.
6.2.5 Event providers

This section describes the built-in event providers. These event providers are responsible for monitoring particular conditions in the environment. If these conditions occur, the event provider generates an event, which is sent to the event processor. The built-in event providers run as sub-components of a monitoring agent on target workstations. For information about event providers implementation, refer to 6.3.8, Event providers implementation on page 296.
Tivoli Workload Scheduler Object Monitor

The Tivoli Workload Scheduler Object Monitor is responsible for monitoring particular conditions that are related to Tivoli Workload Scheduler objects in the current plan. Table 6-1 contains the events that can be generated by the Tivoli Workload Scheduler Object Monitor.
Table 6-1 Events generated by the Tivoli Workload Scheduler Object Monitor Event name JobStuatusChanged JobUntil JobSubmit JobCancel JobRestart JobLate JobStreamStatusChanged JobStreamUntil JobStreamSubmit JobStreamCancel JobStreamRestart Event Description Job changed its status. Jobs until has elapsed. Job has been submitted. Job has been cancelled. Job has been restarted. Job is late (termination deadline has elapsed). Job stream changed its status. Job streams until has elapsed. Job stream has been submitted. Job stream has been cancelled. Job stream has been restarted.
281
Event name JobStreamLate WorkstationStatusChanged ChildWorkstationLinkChanged ParentWorkstationLinkChanged PromptStatusChanged
Event Description Job stream is late (termination deadline has elapsed). Workstation changed its status. Child workstation has been linked or unlinked. Parent workstation has been linked or unlinked. Status of a prompt changed.
File Monitor
The File Monitor event provider is responsible for monitoring particular conditions that can occur on the file system where the File Monitor is deployed. Table 6-2 contains the events that can be generated by the File Monitor.
Table 6-2 Events generated by the File Monitor Event name FileCreated FileDeleted ModificationCompleted Event description File has been created. File has been deleted. File has been modified and is no longer being modified. This event is not sent at the time when the modifications are detected, but only if the file is no longer modified in two consecutive monitoring cycles after a detected modification. A log message in a defined format has been written to a file. This functionality is usually used for the monitoring of log files.
LogMessageWritten
6.2.6 Action providers

This section describes the built-in action providers.
Tivoli Enterprise Console Event Forwarder

This action provider implements and forwards the event to an external Tivoli Enterprise Console server (or any other application capable of listening for events in the Tivoli Enterprise Console format).
282
The parameters related to the Tivoli Enterprise Console host name and listening port must be specified in the Tivoli Workload Scheduler global options. You must use the optman command for this task. The global options related to the TEC Event Forwarder are described in 6.4.12, Event driven workload automation related global options on page 340; refer to Table 6-13 on page 340, which contains the list of important global options, their meanings, and default values.
Mail Sender
This action provider sends an e-mail using the SMTP protocol. The parameters related to the e-mail content are specified in the particular action definition within the event rule. The parameters related to the SMTP settings, mail server, mail sender name, and authentication settings must be specified in the Tivoli Workload Scheduler global options. You must use the optman command for this task. The global options related to the Mail Sender are described in 6.4.12, Event driven workload automation related global options on page 340; Table 6-14 on page 341 contains the list of important global options, their meaning, and default values.
Message Logger
This action provider logs defined messages to the internal auditing database. These messages can be viewed in the Tivoli Dynamic Workload Console as the Operator Messages. The Operator Messages portlet is a console-like view that is used for tracing the rules execution. The number of entries within the auditing database is configurable. There is an automatic cleanup with the FIFO policy. The global options related to the Message Logger are described in 6.4.12, Event driven workload automation related global options on page 340; Table 6-15 on page 342 contains the list of important global options, their meaning, and default values.
283
Tivoli Workload Scheduler Action provider

This action plug-in implements actions related to Tivoli Workload Scheduler functionality. The following Tivoli Workload Scheduler actions can be performed: SubmitJob SubmitCommand SubmitJobStream ReplyToPrompt
Generic Command Executor

The action plug-in implements a simple command executor. Commands are executed on the same machine where the event processor runs. Either local commands or scripts can be executed.
6.3 Event driven workload automation implementation details

This section describes the implementation details of the event driven workload automation.
6.3.1 Event driven workload automation topology

This section describes the topology of event driven workload automation. We highlight the most important components and their purpose. From the topological perspective, the event driven workload automation can be divided into the following components: Event processor Monitoring agents Database User interfaces Figure 6-4 on page 285 shows the event driven workload automation topology.
284
Figure 6-4 Event driven workload automation - topological view
We have used following abbreviations in this figure: Tivoli Workload Scheduler (TWS). Tivoli Workload Scheduler Domain Manager (TWS DM). Tivoli Workload Scheduler Fault Tolerant Agent (TWS FTA). Job Scheduling Console (JSC). Embedded version of WebSphere Application Server (eWAS). Integration Solutions Console (ISC).
285
Tivoli Workload Scheduler Web user interface (TWS WEB-UI). Another name for the Tivoli Dynamic Workload Console. The major components are described in the following sections.
Event processor
The event processor is a J2EE application installed in the embedded version of WebSphere Application Server. The event processor runs within the same instance of the WebSphere Application Server, as the master domain manager or the backup master. The event processor can run on any eligible node (the master or one of backup masters) regardless, if it runs on the same machine that is the current domain manager of the MASTERDM domain. This statement means that the event processor can run on the backup master that runs currently only as a plain Fault Tolerant Agent. The event processor consists of several sub-components. We list the most important of them: Event correlation engine: All active rules run within this component. The incoming events are being matched against the event correlation conditions. Action helper: Instantiates the event rule and executes actions when the event correlation conditions are satisfied. Rule Builder: Builds the defined rules defined by user and deploys them to target monitoring agents.
Monitoring agents
Monitoring agents are responsible for monitoring of defined conditions. If the defined conditions occurred, the monitoring agent will generate an event and send it to the event processor. The monitoring agent is located on workstations. The agent is represented by the new Tivoli Workload Scheduler process called monman. The monman process relies upon the Netcool SSM agent. It consists of several subagents responsible for monitoring different conditions. The particular Netcool SSM subagents are described in 6.3.8, Event providers implementation on page 296.
Database
All event rules and their instances are stored in the database. Event driven workload automation utilizes some tables in the common Tivoli Workload Scheduler database.
286
User interfaces
The following user interfaces can be used for interaction with the event driven workload automation: Tivoli Dynamic Workload Console Command-line interface The Job Scheduling Console by itself does not provide any interface for interaction with event driven workload automation. It can just launch the Web browser pointing to the Tivoli Dynamic Workload Console. The Tivoli Dynamic Workload Console launched from the Job Scheduling Console points directly to the event driven workload automation portlets.
6.3.2 Event driven workload automation: high availability

This section discusses the concepts of the event driven workload automation high availability. In fact, the event driven workload automation uses concepts similar to the native Tivoli Workload Scheduler core components. The central point, the event processor, can be switched from the master domain manager to one of the backup master nodes. The event processor and master domain manager do not need to run at the same time on the same machine. The event processor can be switched to the backup master that runs currently as a plain fault tolerant agent only. The syntax of the command that switches the event processor from one node to another is described in 6.4.11, Useful command-line interface commands on page 338.
6.3.3 Event driven workload automation: security

This section briefly describes the security prerequisites that you must meet in order to be able to work with the event driven workload automation.
Tivoli Dynamic Workload Console authentication

This section briefly describes what type of credentials can be passed to the Tivoli Dynamic Workload Console.
287
The Tivoli Dynamic Workload Console is hosted by the Integrated Solutions Console. The Integrated Solutions Console enforces the authentication mechanism by default. Integrated Solutions Console can leverage the following authentication realms: Federated Repositories: This is the default authentication realm. The Integrated Solutions Console uses internal files, where the credentials are stored. The entries can be managed through the Integrated Solutions Console user interface. Local Operating System: The authentication is done on the operating system level (on the machine, where the Integrated Solutions Console is installed). Standalone LDAP registry: External LDAP server can be used for authentication. This approach is also the prerequisite for the single sign-on enablement. Stand-alone custom registry. By default, the internal credential vault of Integrated Solutions Console is used. The user account and passwords can be managed through the Web interface. Each user that authenticates against the Integrated Solutions Console must have defined a server connection to the Tivoli Workload Scheduler engine. The server connection specifies the following: Host name of the Tivoli Workload Scheduler engine. Credentials supplied to the Tivoli Workload Scheduler engine (if there is not a single sign-on solution implemented). The authentication between the Tivoli Dynamic Workload Console can be implemented in the following ways: There are separated user registries for Tivoli Dynamic Workload Console and Tivoli Workload Scheduler engine. Tivoli Dynamic Workload Console and Tivoli Workload Scheduler engine use a shared user registry (for example, an LDAP server), but there is no single sign-on solution implemented. Tivoli Dynamic Workload Console and Tivoli Workload Scheduler engine use a shared user registry (for example, an LDAP server) and there is a single sign-on solution implemented. These authentication related topics are very complex and they are beyond the scope of this chapter.
288
Tivoli Dynamic Workload Console authorization

This section describes how to configure the authorization roles of the Tivoli Dynamic Workload Console. The Tivoli Dynamic Workload Console authorization influences what portlets will be available to particular users. If the authorization roles are set incorrectly, the user will not see the portlets necessary for his work. The authorization roles are determined by the group membership of each user. You must put each user into the corresponding group in order to provide him with the necessary portlets. Table 6-3 shows the necessary group membership for working with the event driven workload automation portlets.
Table 6-3 Group membership necessary for event driven workload automation portlets Task Create/Edit/Delete Rule List rules List rules View rule instances Add new Engine Group membership TWSWEBUIDeveloper TWSWEBUIDeveloper TWSWEBUIAnalyst TWSWEBUIConfigurator
Note: The membership in the group TWSWEBUIConfigurator is not necessary for working with the event driven workload automation portlets. However, the user needs to define his connection to the Tivoli Workload Scheduler engine. The menu option that allows the user to define the connection to the Tivoli Workload Scheduler engine is not available for roles lower than TWSWEBUIConfigurator. The user must have this role at least temporarily in order to be able to define his own connection to the Tivoli Workload Scheduler engine.
Tivoli Workload Scheduler engine authorization

This section describes the new entry types in the Tivoli Workload Scheduler security file. These entries determine the users authorization for working with the event driven workload automation objects.
289
Table 6-4 lists the entries that must be added to users, who will work with the event driven workload automation objects. The way of updating the security settings remains the same: use the dumpsec and makesec commands to manipulate the security file.
Table 6-4 Object eventrule eventrule eventrule eventrule eventrule eventrule action action action event Tivoli Workload Scheduler security file objects for EDWA Keyword add delete display modify list unlock use display list use Description Add new event rule definitions to the database. Delete event rule definitions from the database. Either display or extract definitions for event rules and event rule instances from the database. Modify, lock, or unlock definitions for event rules owned by the user in the database. Display information about event rules and event rule instances in the database. Unlock event rule definitions locked by other users in the database. Use the action to create event rule definitions. Either display or extract the action execution log from the database. Display information about action execution log. Use the event to create event rule definitions.
6.3.4 Event rule deployment process

This section describes the event rule deployment process.
Deployment steps
Once the rule is saved in the database and marked as complete, it will be activated by the event builder. The activation process consists of these steps: The monitoring conditions for the rule must be configured on the affected workstations and the monitoring of these conditions must start. The rule itself must be built and activated within the event correlation engine.
290
We call this process the event rule deployment process. If we speak about deploying the rule to the target workstation, we mean the following: The workstation will receive the list of active rules that expect events from this workstation. The workstation will receive the monitoring conditions for particular event providers and start to monitor these conditions. An example of the monitoring condition is monitor the status changes of the job AAA.
Determining the eligible workstations

The list of workstations where the rule will be deployed is determined by the following criteria: One of the event objects in the rule definition explicitly specifies that the event should originate from a particular workstation.
workstation XYZ.
An example of such definition is monitor the status of the job AAA on the One of the event objects in the rule definition uses wildcards. The list of target workstations is composed of those workstations that match the wildcard definition.
workstations XY* (where the asterisk represents any string).
An example of the monitoring condition is monitor the link status on
Deploying the monitoring configuration to workstations

The deployment process of the configuration settings to workstations consists of following steps: The rule builder generates configuration files for each particular workstation and compresses them using the ZIP algorithm. A dedicated zipped file is created for each workstation. Each monman process running on the affected workstations is notified about the new configuration. Each monman process downloads its own zipped file using the HTTP/HTTPS protocol. Each monman process unzips the downloaded zipped file and restarts the locally running Netcool SSM agent. The new configuration becomes active. The location of the configuration files is described in Monitoring agent configuration on page 295.
291
Initiating the deployment process

The deployment process can be of two types: Manual: Issued from command line. Automatic: Periodical deployment of new rules or modified rules. The deployment period is configurable. Both of the mentioned deployment types are described in 6.4.6, Deploying and activating a rule on page 327.
6.3.5 Communication among the event processor and agents

In 6.3.4, Event rule deployment process on page 290, we have described how the event rule deployment works. We have also mentioned that the deployment process relies upon the HTTP/HTTPS protocol family. The communication mechanism used for information exchange between the event driven workload automation components is different. The communication among the Event Processor and monitoring agents relies upon the Event Integration Facility (EIF). This is a Java based code and originates from the Tivoli Enterprise Console product. For those who are familiar with Tivoli Management Framework, we can mention that the non-TME transfer method is used. This means that the network traffic between the components is not encrypted. This limitation should be removed in the FP01, and the SSL support for Event Integration Facility should be added. The Event Integration Facility uses the mechanism of caches. Caches are initialized during the component start and are only used when the corresponding counterpart is not able to receive the messages. The unsent messages are kept in the local cache. Each monitoring agent uses one common cache file for all of its event providers (particular monitors). If the connection between a monitoring agent and the event processor is down for a longer time, the local cache file can become full. You can adjust the maximal cache size in the Event Integration Facility configuration file. The important files and directories related to the Event Integration Facility are listed in Event Integration Facility on page 294. Note: The Event Integration Facility is independent of the communication used in the Tivoli Workload Scheduler network. If the TCP/IP communication is working between the event processor and a particular monitoring agent, the information is still being delivered, even if the workstation is unlinked.
292
6.3.6 Important files and directories on the event processor

This section provides information about directories and important files used by the event driven workload automation components. In this section, we describe the file locations on the event processor.
Event Integration Facility

Table 6-5 lists the important files and directories related to the Event Integration Facility (EIF) on the event processor.
Table 6-5 Important EIF related files and directories on event processor Meaning EIF directory (contains the files listed below) Configuration file Cache file Log file Location <TWS_home>/appserver/profiles/twsprofile/temp/TWS/ EIFListener eif.conf cache.dat <TWS_home>/appserver/profiles/twsprofile/logs/server 1/SystemOut.log
Note: The SystemOut.log mentioned in Table 6-5 is not dedicated to the Event Integration Facility only. It is a shared log file of the embedded version of WebSphere Application Server. However, important information, such as event reception, appears in this log file. Using this log file, you can track the incoming events and check whether they were identified as valid events or not.
293
Event and action plug-ins

Table 6-6 lists the important files and directories related to the built-in event and action plug-ins. The directory specified in the table is also used for installing new generic plug-ins.
Table 6-6 Location of event and action plug-ins Meaning Plug-ins directory (contains the files listed below) Tivoli Workload Scheduler objects monitor event plug-in File Monitor event plug-in Tivoli Workload Scheduler action plug-in Tivoli Enterprise Console Event Forwarder action plug-in Mail sender action plug-in Message logger action plug-in Generic event plug-in Generic action plug-in Location <TWS_HOME>/eventPlugIn TWSObjectsMonitorPlugin.jar
FileMonitorPlugIn.jar TWSActionPlugin.jar TECEventForwarderPlugIn.jar
MailSenderPlugin.jar MessageLoggerPlugIn.jar GenericEventPlugIn.jar GenericActionPlugin.jar
6.3.7 Important files and directories on the workstations

This section provides information about directories and important files used by the event driven workload automation components. In this section, we describe the file locations on the workstations.
Event Integration Facility

Table 6-7 on page 295 lists the important files and directories related to the Event Integration Facility (EIF) on workstations.
294
Table 6-7 Important EIF related files and directories on workstations Meaning EIF directory (contains the files listed below) Configuration file Cache file Location <TWS_home>/EIF monmaneif.conf monmancache.dat
Monitoring agent configuration

Table 6-8 lists the important files and directories related to monitoring agents on workstations.
Table 6-8 Important monman configuration files Meaning Monman executable Netcool SSM agent directory Monman configuration directory (contains the files listed below) ZIP file containing the definition of rules that shall run on the workstation Definition of active rules deployed to workstation Particular event providers configuration file Example: TWS Object Monitor configuration file Example: File Monitor configuration file Log file Location <TWS_home>/bin/monman(.exe) <TWS_home>/ssm <TWS_home>/monconf
deployconf.zip
activeRules.txt <evt_provider_name>.cfg TWSObjectsMonitor.cfg
FileMonitor.cfg
<TWS_home>/stdlist/logs/YYYYMMDD_TWSMERGE.l og
295
Note: The YYYYMMDD_TWSMERGE.log mentioned in Table 6-8 on page 295 is not dedicated for the monman use only. It is a shared log file for other Tivoli Workload Scheduler processes. The file <TWS_home>/monconf/deployconf.zip has been downloaded by the monman process from the event processor. The other files present in the <TWS_home>/monconf directory were unzipped from the deployconf.zip file. The other files in the <TWS_home>/monconf directory have been unzipped from the file <TWS_home>/monconf/deployconf.zip. These files determine the local monitoring conditions and correspond to active rules related to this workstation.
6.3.8 Event providers implementation

This section describes how the particular event providers are implemented and discusses where they are run. Note: The monitoring process monman utilizes the Netcool SSM agent. This agent has been extended by the Tivoli Event Integration Facility (EIF) in order to be able to send and receive messages in this format. The Event Integration Facility is described in 6.3.5, Communication among the event processor and agents on page 292.
Tivoli Workload Scheduler Object Monitor

This event provider runs by default on all Tivoli Workload Scheduler nodes. It is responsible for monitoring Tivoli Workload Scheduler objects, such as jobs, job streams, prompts, workstations, and so on. Objects are monitored by the batchman process, which detects the objects state changes. Batchman sends the information to the locally running process monman through the mailbox monbox.msg. Workstations state changes are updated by the mailman process. The information is sent to the monbox.msg as well. The following list contains a description of what is monitored where: Jobs are monitored by the workstation where the job runs. If the jobs runs on the extended agent (XA) or standard agent (SA), then the job status is monitored on the workstation that hosts the extended agent or the standard agent. Job streams are monitored by the master domain manager.
296
Workstations are monitored by the workstation itself. Local prompts are monitored by the workstation responsible for monitoring the job or job stream that has a dependency on the prompt. Global prompts are monitored by the master. Events are generated by batchman (or mailman for the workstations) and written to a mailbox file called monbox.msg.
File Monitor
This event provider is based on the following Netcool SSM subagents: The FileMon subagent is responsible for monitoring of files on the file system. The LogMonX subagent is responsible for parsing of log files. This monitor runs on the workstation, where we monitor the specified files.
6.4 Working with event driven workload automation

This section describes how to work with the event driven workload automation. We describe the following topics: 6.4.1, User interfaces interacting with event driven workload automation on page 298 6.4.2, Logging in to the Tivoli Dynamic Workload Console on page 298 6.4.3, Navigation to event driven workload automation portlets on page 299 6.4.4, Creating rules using the rule editor on page 300 6.4.5, Changing the rule status to Complete on page 324 6.4.6, Deploying and activating a rule on page 327 6.4.7, Querying the rule instances on page 329 6.4.8, Querying the triggered actions on page 334 6.4.9, Querying the Operator messages on page 336 6.4.10, Linking the Job Scheduling Console and the Tivoli Dynamic Workload Console on page 337 6.4.11, Useful command-line interface commands on page 338 6.4.12, Event driven workload automation related global options on page 340 6.4.13, Event driven workload automation related local options on page 342
297
6.4.14, Creating generic plug-ins on page 343
6.4.1 User interfaces interacting with event driven workload automation

The following user interfaces can be used for interacting with the event driven workload automation: Tivoli Dynamic Workload Console Command-line interface The Job Scheduling Console by itself does not provide an interface for interaction with event driven workload automation. It just launches the Web browser pointing to the Tivoli Dynamic Workload Console. The Tivoli Dynamic Workload Console provides an excellent intuitive user interface for working with rule definitions, rule management, and querying the rule instances. Important: Internet Explorer V6.0 has a known limitation issue in the implementation of the JavaScript engine. It can utilize CPU up to 100% while working with the rule editor, which is the key feature provided with the event driven workload automation portlets. The fix for this limitation is available at http://support.microsoft.com/kb/942840. Internet Explorer V7.0 (or higher) and Mozilla Firefox V2.0 (or higher) do not have this limitation.
6.4.2 Logging in to the Tivoli Dynamic Workload Console

This section describes how to log in to the Tivoli Dynamic Workload Console. Note: We assume that you have set up the necessary authentication and authorization in order to be able to use Tivoli Dynamic Workload Console for event driven workload automation related tasks. The event driven workload automation security related topics are briefly described in 6.3.3, Event driven workload automation: security on page 287. 1. Open a new browser window and go to the address http://<tdwc_hostname>:29060/ibm/console.
298
2. A log in window appears. Enter your credentials and click Log In. If you have entered the proper credentials, the Tivoli Dynamic Workload Console window appears, as shown in Figure 6-5.
Figure 6-5 Tivoli Dynamic Workload Console
6.4.3 Navigation to event driven workload automation portlets

This section explains how to navigate to the event driven workload automation portlets within the Tivoli Dynamic Workload Console.
299
In the left pane of the Tivoli Dynamic Workload Console, expand the Tivoli Workload Scheduler item, and then expand Workload Definition Event Management (Figure 6-6).
Figure 6-6 Navigation to event driven workload automation portlets
6.4.4 Creating rules using the rule editor

This section explains how to use the event rule editor for creating new rules. The event rule editor is an intuitive and easy-to-use graphical editor that allows you to define new rules or modify already existing ones.
Opening a rule editor for a new rule definition

In this section, we describe how to navigate to the rule editor and open it for a new rule definition. Log on to the Tivoli Dynamic Workload Console and navigate to Tivoli Workload Scheduler Workload Definition Event Management. Click New Event Rule. If you have defined more engine connections, you will have to select which engine to which you want to connect. The Event rule editor appears. If you have only one engine connection defined, you will not be prompted for the engine selection and the Event rule editor appears immediately. Figure 6-7 on page 301 shows the event rule editor.
300
Figure 6-7 Event Rule editor
As shown in Figure 6-7, we can divide the event rule editor into four different panes: Event rule General Information pane Events pane Actions pane Properties pane We describe each of these panes in following sections. The following object types can be inserted into the rule definition: Events Actions
301
Event rule General Information pane

Using this pane, you can specify the general properties of an event rule. Figure 6-8 contains the description for the Event rule General Information pane.
Figure 6-8 Event rule General Information pane
In this pane, you can perform the following tasks: Type the event rule name and description. Specify whether the rule is Draft or not. If the rule is saved with the Draft status, it will not be deployed to monitoring agents nor activated in the Event Correlation Engine. This can be changed either by editing the rule again and unchecking the Draft check box, or by marking the rule as Complete in the event rule list. This topic is described in 6.4.5, Changing the rule status to Complete on page 324. The other rule is Active and is deployed to monitoring agents within the specified deployment frequency interval. Specify validity interval: You can specify the start date and end date when the rule is valid. In addition, you can specify the daily start and daily end. Using this option, you can, for example, create a rule that is valid only between 2007/12/24 and 2007/12/27, starting each day at 8:00:00 AM and ending each day at 4:30:00 PM. In addition, you can determine a corresponding time zone. This pane can be collapsed by clicking on an icon in the upper left corner.
302
Working with objects in the rule editor

In this section, we describe the tasks that are common for both types of objects: events and actions. We describe following operations: Adding a new object into a rule definition. Selecting the object for modification. Querying the object properties. Removing the object from the rule definition. All of these tasks are the same for both object types: actions and events.
Adding new objects

Figure 6-9 shows how a new object can be added. Select either the Events or Actions pane, and expand the desired branch in the navigator view on the left side. Then click the desired object type.
Figure 6-9 Adding new objects
The position of any event object type can be changed by clicking the small arrow icons <and> at the bottom of each event object. This is important when you use the correlation condition event sequence and you want to change the order, in which the events must arrive.
303
Additional operations
Figure 6-10 explains additional operations that can be performed on objects in the event rule editor: Selecting the object for modification. Querying the object properties. Removing the object from the rule definition.
Figure 6-10 Working with object properties
A detailed description related to object properties modification is found in Properties pane on page 314.
304
Events pane
Using this pane, you can define which events must arrive in order to satisfy the event correlation condition of the currently edited event rule. The Events pane is the place where you specify which events must occur in order to trigger the actions. To define an event, you must define the filter criteria that any incoming event of some type must match. For example, you can trigger an action when any job on a workstation with a name starting with Accounting and ends with SVR fails or abends. To specify this filtering criteria, you will add a job status change event and specify Accounting* as the matching condition for the job name and *SVR for the matching condition for the workstation name.
305
Figure 6-11 shows the description of the Event properties pane. We display the Events pane together with the Properties pane. For demonstration purposes, we have collapsed the Actions pane, which is located between the Events pane and Properties pane.
Figure 6-11 Events pane
In this pane, you can perform the following operations: Add new event objects to the rule definition. Expand the desired branch in the navigator in the left. Then click the desired event type.
306
The position of any event object type can be changed by clicking the small arrow icons <and> at the bottom of each event object. This is important when you use the correlation condition event sequence and you want to change the order in which the events must arrive. Remove the events from the rule definition. Click the cross sign in the upper right corner of the event object that you want to remove. Select the event object for modification. Click the event object and then go to the Properties pane. There you can modify the desired values. Modifying the object properties is in detail described in Properties pane on page 314). Specify the event correlation condition (explained in Event correlation conditions on page 307). Optionally, you can specify the timeout that defines the time interval in which the multiple events must arrive. Timeouts and timeout actions are explained in detail in Timeout actions on page 312.
Event correlation conditions

Event correlation conditions determine if the incoming event will be processed by the rule or not. Only the event that matches the correlation condition is accepted. There are the following possible correlation conditions: Single event (also known as filter): In this case, the event rule definition must contain only one event. Note: The correlation condition single event is the default one. If you are defining event rules containing only one event, you need not explicitly specify the single event correlation condition, because it is already preselected. Event set: In this case, the event rule definition must contain at least two events or more and their order is not important. Event sequence: The special case of the event set correlation condition. The event rule definition must contain at least two events or more and their order is important.
307
Figure 6-12 contains the description for event correlation condition. We also mention timeout options, which are explained in detail in Timeout actions on page 312.
Figure 6-12 Event correlation conditions
Click the desired correlation condition icon. If you try to save a rule with an incorrectly specified correlation condition, you will receive an error message. Incorrectly specified correlation conditions are: single event: Two or more events in the rule definition event set or event sequence: Less than two events in the rule definition
Correlate on option
Special attention should be paid to the Correlate on option, which is located in the Events pane (Figure 6-13 on page 309).
308
Figure 6-13 Event pane Correlate on option
Here we explain the Correlate on option: We define one event that should detect that the workstation has unlinked. We define a second event that should detect that the workstation has linked back. For both of these events we specified wildcard * in the workstations host name, which means all workstations. This definition means that the events workstation has linked and workstation has unlinked will be generated by all workstations in our Tivoli Workload Scheduler environment. Without any other refinement, any linked event would pair with any unlinked event, regardless of the value of the workstation attribute. In order to pair only events originating from the same workstation, we need to specify an Correlate on attribute. This will ensure that only events originating from the same workstation would be paired together. If we did not specify the attribute that pairs events together, the results would be unpredictable.
309
Actions pane
Using this pane, you can define which actions will trigger the rule. Using this pane, you can define two types of actions: Response actions: These actions will be triggered when the event correlation condition has been met. Timeout actions: These actions will be triggered if the timeout that has been set on the event correlation condition has expired. There are two workplaces in the actions pane: Actions: Used for working with response actions Timeout actions: Used for working with timeout actions Figure 6-11 on page 306 contains a description of the Actions pane. We display the Actions pane together with the Properties pane. In this figure, we explain how to work with response actions. Timeouts and timeout actions are explained in Timeout actions on page 312.
310
Figure 6-14 Actions pane
In this pane, you can perform the following operations: Add new action objects to the rule definition. Expand the desired branch in the navigator in the left. Click the desired action type. Remove the actions from the rule definition. Click the cross sign in the upper right corner of the action object that you want to remove.
311
Select the action object for modification. Click the action object and then move to the Properties pane. There you can modify the desired values. Modifying the object properties is described in Properties pane on page 314). Switch to the timeout actions pane. Timeouts and timeout actions are explained in Timeout actions on page 312.
Timeout actions
This section demonstrates how to work with timeout actions. The following timeout actions are defined: There are multiple events defined in the Events pane. The correlation condition is set either to event set or event sequence. In addition, a timeout is specified for the correlation condition. Timeout actions are defined for the case when the timeout expires. We explain the timeout concept as follows: We create a rule that contains multiple events, and we define a timeout in the correlation condition. We save the rule, mark it as complete, and the rule is deployed and activated. Our rule runs within the Event Correlation engine. Each incoming event is matched by all active rules, including our rule. The first matching event arrives and the timeout counter is initialized. The timeout counts down. Two results are possible: All other events that are necessary for satisfying the correlation condition arrive in time (before the timeout expires). Then the response actions are triggered. At least one event is necessary for when the correlation condition does not arrive in time (before the timeout expires). The timeout expires and the timeout actions are triggered. Working with the timeout actions is the same as working with the response actions. The only difference is that you must switch to the Timeout actions workplace by clicking the Timeout actions bookmark. Figure 6-15 on page 313 contains the description of the Timeout actions located within the Actions pane. We display the Actions pane together with the Properties pane. In this figure, we explain how to work with Timeout actions.
312
Figure 6-15 Actions Pane - Timeouts
313
In this pane, you can perform following operations: Add new timeout action objects to the rule definition. Expand the desired branch in the navigator. Click the desired action type. Remove the timeout actions from the rule definition. Click the cross sign in the upper right corner of the timeout action that you want to remove. Select the timeout action object for modification. Click the timeout action object and then move to the Properties pane. There you can modify the desired values. Modifying the object properties is described in Properties pane on page 314. Switch to the response actions pane (explained in Actions pane on page 310). Note: The possible action types are the same for response actions and timeout actions.
Properties pane
The properties of the currently selected object can be modified in this pane. You can also can add additional properties, or remove any non-mandatory property. Note: Each object defined in the event rule (either object or an action) has a set of attributes. In the event driven workload automation terminology, the attributes are called properties. When speaking about an object property within this chapter, we speak about the attribute of a particular object. You must select the desired object within the Events or Actions pane first. Then the list of currently defined properties appears within this Properties pane. When working with events definitions, we recommend you collapse the Actions pane in order to see the objects and its properties in the same window. When you working with the action definitions, you do not need to collapse anything, because the Properties pane is located just below the Actions pane. The displayed properties depend on the currently selected object. For example, different properties are available for the Job cancelled and File deleted event objects.
314
Link between the selected object and the Properties pane

Figure 6-16 describes how the content of the Properties pane corresponds to the currently selected object.
Figure 6-16 Link between the selected object and Properties pane
315
Properties pane for Event objects

Figure 6-17 displays the content of the Properties pane when an event object is selected.
Figure 6-17 Properties pane for Event objects
Once you have selected an event object in the Events pane, you can edit its properties located in the Property pane. You must fill in all the mandatory input fields (they are displayed when the object has been inserted to the rule definition). Otherwise, you will not be able to save the event rule (even as a draft). You can also specify additional properties that make the object definition more accurate.
316
Here we describe the functionality of the Properties pane: Text fields have implemented a syntax checker. It evaluates your input and if anything is incorrect, the error message appears immediately below the input field. Some input fields offer you a list of predefined values. Select a desired value from the list. For each input field, you can specify the comparison criteria. The comparison criteria determines if the value from the incoming event must match or must not match the property value from the rule definition. The default comparison criteria is matches. You can add additional properties by clicking -- Select a property to add --. Then click the property name from the drop-down list. The property will be added and you will have to input its value. You can remove any non-mandatory property by the clicking the X sign located to the left of the property. You cannot remove mandatory properties. You can use the mouse to point at icons on the right side of the input fields. The hover help will inform you about following conditions: Whether the field accepts wildcards or not. Whether multiple filters are allowed or not.
Working with multiple filters

Some event object properties allow you to enter more than one value into the input text box. Such properties support multiple filters. You can check each object property to see if it supports multiple filters or not. Figure 6-17 on page 316 describes the multiple filters indicator. The term multiple filters means that you can enter multiple values for the same property. Values must be separated by a semicolon and the semicolon must not be followed by space. Depending on the operator (matches/does not match), you determine the relationship among the multiple values as follows: Positive logic (operator matches) means that the relationship among multiple values is OR. Negative logic (operator does not match) means that the relationship among multiple values is AND.
317
We explain multiple filters on two opposite examples: Example of positive logic: We want to monitor three jobs, A, B, and C. We must define a filter that is satisfied when the job name is either A OR B OR C. To accomplish this task, we define following filter: Job Name matches A;B;C, as shown in Figure 6-18.
Figure 6-18 Multiple filters -positive logic OR relationship
The operator matches specifies that the values have an OR relationship. The filter will be satisfied if the value of the incoming event has a job name attribute equal either to A, B, or C. Note that the values are separated by the semicolon ; character. The semicolon must not be followed by a space. Example of negative logic: We want to monitor all jobs except for jobs A, B, and C. We must define a filter that is satisfied when the job name is not equal to A AND B AND C. To accomplish this task, we define the following filter: Job Name does not match A;B;C, as shown in Figure 6-19.
Figure 6-19 Multiple filters -negative logic AND relationship
The operator does not match specifies that the values have an AND relationship. The filter will be satisfied if the value of the incoming event has a job name different from A, B, and C. Note that the values are separated by the semicolon ; character. The semicolon must not be followed by a space.
Properties pane for Action objects

Figure 6-20 on page 319 displays the content of the Properties pane when an action object is selected.
318
Figure 6-20 Properties pane for Action objects
The manipulation of the properties of action objects is similar to the manipulation of the properties of the event objects. Once you have selected an action object in the Actions pane, you can edit its properties in the Property pane.
319
You must fill in all the mandatory input fields (they are displayed when the object has been inserted into the rule definition). Otherwise, you will not be able to save the event rule (even as a draft). You can also specify additional properties that make the object definition more accurate. The following comments describe the functions of the Properties pane: The text fields have implemented a syntax checker. It evaluates your input and if anything is incorrect, the error message appears immediately below the input field. Some input fields offer you a list of predefined values. Select a desired value from the list. For each input field you can specify the comparison criteria. The comparison criteria determines if the value from the incoming event must match or must not match the property value from the rule definition. The default comparison criteria is matches. You can add additional properties by clicking -- Select a property to add --. Then click the property name from the drop-down list. The property will be added and you will have to input its value. You can remove any non-mandatory property by the clicking the X sign located in the left side of the property. You cannot remove mandatory properties. Some input fields offer you a Lookup function. This function queries the Tivoli Workload Scheduler database and provides you with a list of existing Tivoli Workload Scheduler objects, such as workstations, jobs, or job streams. In order to use this function, click the Lookup... button and then select the function from the list. This function makes the definition more comfortable and can save a significant amount of time, because you do not need to search for the proper values elsewhere. For each defined action property you can use variables. The variables represent a link to the property values of the incoming matched event. Variables are explained in Working with variables on page 320.
Working with variables

This section explains how to use the variables in the properties of the action objects. Variables allow you to use the data from incoming events in your actions.
320
Figure 6-21 on page 322 explains how the variable connects the properties of the event objects to the properties of the action object. We demonstrate the following: Define two events in the correlation condition: The first event notifies you that the domain manager has been stopped. The second event notifies you that the Symphony file on the domain manager has been deleted. Specify that the correlation condition is event set, which means that the events must arrive explicitly in the defined order. Define an action that sends an e-mail to the responsible administrator. In the subject of the message, we include the machines host name. In the body of the message, we include the machines host name and the full path to the deleted Symphony file.
321
This task can be accomplished only by using variables. We show this mechanism in Figure 6-21.
Figure 6-21 Using variables in the rule editor
322
Variables can be added using these steps: 1. Write your input into the property field and stop at the position where you want to insert the variable. 2. Click the Variables... button located in the right side of the property field. A window containing a list of events defined for this rule will pop up. 3. Expand the desired event. 4. Click the desired event property. The event property will be inserted into the text field as the variable. 5. Continue typing the rest of text that you want to enter into the property field. 6. If you have written more text and you want to insert the variable somewhere in the middle, it is not possible; the variable will always be inserted at the end of the written text. You must use the copy/paste mechanism in order to reposition the variable. Make certain to move all the text belonging to the variable.
Differences between event properties and action properties

This section lists the major differences between the event properties and action properties. The following list shows the functions available to event properties only: Wildcards: In the event definition, you can use wildcards for particular properties (for example, job name). Multiple filters: In the event definition, you can specify some property types multiple times (for example, you can specify two different job names that you expect to ABEND). You cannot use this functionality in the action properties; if you want to submit two different jobs, you must define two separate actions. The following list shows the functions available to action properties only: Lookup function: In the action definition, you can query the Tivoli Workload Scheduler database for a list of existing objects. Variables: In the action definition, you can use the variables that point to some properties of event objects.
323
6.4.5 Changing the rule status to Complete

This section describes how to change the state of the rule from Draft to Complete. When the rule is saved in the Draft status, it is only saved in the database. The rule is not built or deployed to target systems. Changing a rule status to Complete is a necessary prerequisite for deploying and activating the rule. Note: You should change the rule status to Complete only if you are sure that the rule definition is correct. Special attention should be paid to event rules that use wildcards in the event object definitions. Such rules can be deployed to hundreds of workstations. We explain two ways how the rules can be marked as Complete. We use the Tivoli Dynamic Workload Console for this task.
Changing the rule status in the rule editor

In this section, we explain how to change the rule status using the rule editor. We assume that you are logged in to the Tivoli Dynamic Workload Console and you are editing the desired rule in the rule editor. Navigate to the General Information pane and uncheck the Draft check box. When you have performed all the necessary changes and are satisfied with the rule definition, click Save. Make sure that the Draft check box is unselected (Figure 6-22).
Figure 6-22 Changing rule status to Complete inside the rule editor
324
Changing the rule status outside the rule editor

the rule editor.
In this section, we explain how to change the rule status to Complete outside We assume that you are logged in to the Tivoli Dynamic Workload Console using the account that has sufficient privileges for working with event rules. Do the following steps: 1. Select Tivoli Workload Scheduler Workload Definition Event Management. 2. Click Event Rules. The content of the right pane changes. Click All Event Rules (directly on the link, not in the check box on the left side) (Figure 6-23).
Figure 6-23 Getting list of defined event rules
3. If you have defined more engine connections, you will have to select which engine to which you want to connect. Select the engine from drop-down list and click Go.
325
The list of defined rules appears (Figure 6-24).
Figure 6-24 Event rule list
4. The term Completion status determines whether you want the rule to be deployed and activated or not. If you are sure that the rule is well defined, activate it by clicking Set as complete (Figure 6-25).
Figure 6-25 Changing rule status to Complete outside the rule editor
326
5. The Completion status of the event changes to Complete. Click Refresh and your window should look similar to Figure 6-26.
Figure 6-26 Rule in Complete status
Note that both states have changed: Completion status: Complete Internal status: Activation pending This status means that during the next deployment time the rule will be deployed and activated.
6.4.6 Deploying and activating a rule

This section explains how the rule deployment process can be initiated. Once the rule is saved into the database and marked as Complete, it will be deployed to the monitoring agents. There are two ways how the rules can be deployed: Periodically: This is the recommended approach. After marking the event rule as Complete, the rule will be deployed automatically. The maximum wait time is specified in the global option deploymentFrequency (df). The default value is 5 minutes. If you want to change the deployment frequency, issue the following command: optman chg df=<frequency_in_minutes>
327
Note: You can disable the periodical deployment by setting the deployment frequency to zero by issuing the following command: optman chg df=0 If you disable the periodical deployment, you must manually deploy any changes made to the event rules. Manually: If you need to deploy the latest changes immediately, or if you have disabled the periodical deployment, you can do it by issuing the following command: planman deploy Both these ways deploy only the recently modified rules (including newly defined rules). If you want to redeploy all the Complete rules stored in the database, issue the following command: planman deploy -scratch Note: This command redeploys all active rules. In addition, it resets the event processor, which may lead to the loss of any active event instances. For example, the rule instances that are waiting for a sequence of events will be lost. Figure 6-27 shows the event rule list with a successfully deployed and activated rule.
Figure 6-27 Active rule
328
Important: So far we were speaking about activating the rules. The reverse process, deactivating the rules, is also possible. You just need to set the rule back to the Draft status. The next deployment time will be the rule removed from monitoring agents configuration and also removed from the event correlation engine.
6.4.7 Querying the rule instances

This section explains how you can query the event rule instances. An instance is the real representation of a rule that has been triggered. The event rule instance is created in these two cases: The correlation condition is completely satisfied and the response actions have been triggered. The timeout set on the correlation condition expired and the timeout actions have been triggered. Event rule instances can be queried using the Tivoli Dynamic Workload Console. You can use the following approaches: Search for the particular rule and then view only the instances of that rule. Getting a list of all instances and then select a desired instance from this list. We describe both of these approaches separately.
Viewing instances of a particular rule

Perform the following steps in order to view instances of a particular rule: 1. Log in to the Tivoli Dynamic Workload Console. 2. Select Tivoli Workload Scheduler Workload Definition Event Management. 3. Click Event Rules. 4. Click All Event Rules. 5. Select the proper engine from the drop-down list and click OK.
329
6. A list of defined event rules appears. Select the check box on the left from the desired event. Then click the drop-down menu --- More Actions --- and select Show Instances, and then click the Go button. You can see these steps in Figure 6-28.
Figure 6-28 Querying the event rule instances -1
7. The list of existing rule instances appears. You should see an output similar to Figure 6-29.
Figure 6-29 Querying the event rule instances - 2
8. Click the rule instance name (directly on the link, not the check box on the left side). Figure 6-30 on page 331 shows the output.
330
Figure 6-30 Querying the event rule instances -3
The instance contains the real values, such as job name, workstation name, and so on. The instance represents a real running of the rule.
Viewing the instance from the instance list

Perform the following steps in order to view instances from the instance list: 1. Log in to the Tivoli Dynamic Workload Console. 2. Select Tivoli Workload Scheduler Workload Tracking.
331
3. Click Event Rule Instances (Figure 6-31).
Figure 6-31 Working with instance list - 1
4. In the right pane, click All Event Rule instances (Figure 6-32).
5. Select the proper engine from the drop-down list and click OK. A list of existing instances appears (Figure 6-33 on page 333).
332
6. Click the rule instance name (directly on the link, not on the check box on the left side). Figure 6-34 shows the output.
The instance contains the real values, such as job name, workstation name, and so on. The instance represents a real run of the rule.
333
6.4.8 Querying the triggered actions

Tivoli Dynamic Workload Console provides you with a list of actions that have been triggered by particular event instances. In this list, you can query any of triggered actions and check its details. Perform the following steps in order to query triggered actions: 1. Log in to the Tivoli Dynamic Workload Console. 2. Select Tivoli Workload Scheduler Workload Tracking. 3. Click Triggered Actions (Figure 6-35).
Figure 6-35 Querying triggered actions - 1
4. In the right pane, click All Triggered Actions (Figure 6-36).
334
5. Select the proper engine from the drop-down list and click OK. A list of triggered actions appears (Figure 6-37).
6. Click the triggered action name (directly on the link, not on the check box on the left side). Figure 6-34 on page 333 shows the output.
335
6.4.9 Querying the Operator messages

Operator messages originate from the Message Logger event provider. Messages logged by this event provider are stored in the internal auditing database. The message logger is used when you need to simplify the rule execution tracing. Using a message logger action in your rules allows you to propagate specific text (that may be composed also of rule instance variables) to the console like view. Operators then have a better ability to see what has been done to important rules. Perform the following steps in order to query the operator messages: 1. Log in to the Tivoli Dynamic Workload Console. 2. Select Tivoli Workload Scheduler Workload Tracking. 3. Click Operator Messages (Figure 6-39).
Figure 6-39 Querying operator messages - 1
4. In the right pane, click All Operator Messages (Figure 6-40 on page 337).
336
5. Select the proper engine from the drop-down list and click OK. A console listing the operator messages appears (Figure 6-41). This list cannot be further expanded.
6.4.10 Linking the Job Scheduling Console and the Tivoli Dynamic Workload Console
This section describes launching the Tivoli Dynamic Workload Console from the Job Scheduling Console. This function allows the user to open the Event Rules query within the Tivoli Dynamic Workload Console with just one click in the Job Scheduling Console. You can define the link on the Job Scheduling Console side. Click Work with Event Rules and select the desired engine. Then you have to provide the host name and port number of the machine where the Tivoli Dynamic Workload Console is installed. You must also specify the browser that you want to use. You can save the configuration information so that you do not need to define the values again. These preferences are saved into Job Scheduling Console preferences file.
337
Figure 6-42 shows the necessary steps.
Figure 6-42 Linking the Job Scheduling Console and the Tivoli Dynamic Workload Console
6.4.11 Useful command-line interface commands

This section lists the extensions to the conman, composer, and planman commands. These new commands are used for managing the event driven workload automation. Table 6-9 on page 339 contains the conman extensions related to the event driven workload automation.
338
Table 6-9 Conmon extensions: managing event driven workload automation Extension startevtproc [domain!]workstation stopevtproc [domain!]workstation switchevtproc [domain!]workstation startmon [domain!]workstation [;noask] startmon [domain!]workstation [;noask] Meaning Starts the event processor on the specified workstation. Stops the event processor on the specified workstation. Switches the event processor to the specified workstation. Starts the monman process on the specified workstation. Stops the monman process on the specified workstation.
Table 6-10 contains the composer extensions related to the event driven workload automation.
Table 6-10 Composer extensions: managing event driven workload automation Extension eventrule Meaning Object specification (like job or job stream or any other object specifications known from previous versions) Abbreviation of eventrule Abbreviation of eventrule
erule er
Table 6-11 contains the planman extensions related to the event driven workload automation.
Table 6-11 Planman extensions: managing event driven workload automation Extension deploy deploy -scratch Meaning Deploys recently changed rules. Deploys all rules. Reinitializes the event processor. All previously active rules are lost.
339
6.4.12 Event driven workload automation related global options

This section lists the global options that can affect the event driven workload automation behavior. All the values can be viewed or changed by using the optman command. Table 6-12 contains the general global options related to the event driven workload automation.
Table 6-12 General event driven workload automation related Global options Option name / shortname enEventDrivenWorkloadA utomation (ed) deploymentFrequency (df) enEventProcessorHttpsPr otocol (eh) Meaning Enables or disables the event driven workload automation feature. deploymentFrequency (df). Enables or disables use of the HTTPS protocol to connect to the event processor server. Port of the Tivoli Event Integration Facility (EIF) for communicating with the event processor server. Default value YES (EDWA is enabled)
5 (minutes) YES (HTTPS is enabled)
eventProcessorEIFPort (ee)
31131
Table 6-13 contains the possible global options related to the TEC Event Forwarder.
Table 6-13 TEC Event Forwarder global options Option name / shortname TECServerName (th) Meaning Host name or TCP/IP address of the Tivoli Enterprise Console (TEC) server. Listening port of the tec_reception process. Default value localhost
TECServerPort (tp)
5529
Table 6-14 on page 341 contains the global options related to the Mail Sender.
340
Table 6-14 Mail Sender global options Option name / shortname smtpServerName (sn) Meaning Host name or IP address of the SMTP server through which outgoing e-mails are delivered. Port of the SMTP server through which outgoing e-mails are delivered. Enables or disables the use of the Secure Sockets Layer (SSL) to secure the connection to the SMTP server. Enables or disables the use of the Transport Layer Security (TLS) to secure the connection to the SMTP server. Enables or disables user/password authentication against the SMTP server. Name of the user to be used to authenticate with the SMTP server (if authentication is enabled). Password of the user to be used to authenticate with the SMTP server (if authentication is enabled). Name of the mail sender to be used for e-mails sent by Tivoli Workload Scheduler. Default value localhost
smtpServerPort (sp)
25
smtpUseSSL (us)
NO (SSL is disabled.)
smtpUseTLS (tl)
NO (TLS is disabled.)
smtpUseAuthentication (ua)
NO (Authentication is disabled.)
smtpUserName (un)
name of the TWS_USER
smtpUserPassword (up)
Not set
mailSenderName (ms)
TWS
341
Table 6-15 contains the general global options related to the Message Logger event provider.
Table 6-15 Message Logger related Global options Option name / shortname logHistory (lh) Meaning Number of days for which the history of triggered rule instances, action runs, and logged messages are kept in the TWS database. Specifies how often to look for history data older than logHistory days, which must be deleteddefault. Default value 10 (days)
logCleanupFrequency (lc)
5 (minutes)
6.4.13 Event driven workload automation related local options

This section describes which local options settings are related to the event driven workload automation. Table 6-16 contains the possible local options related to the event driven workload automation.
Table 6-16 Local options related to the event driven workload automation Option name / shortname CAN BE EVENT PROCESSOR Meaning Event processor can run on this node. Default value Y (for master domain manager or backup master) N (for other workstations) yes (monman starts automatically)
autostart monman
Determines whether the monman process shall start automatically. If set to no, the monman does not start after the machine starts or after the JnextPlan. Without the monman running, the machine is not monitored from the event driven workload automation perspective.
342
6.4.14 Creating generic plug-ins

This section briefly discusses the process of developing new event or action plug-ins.
Plug-ins directory
All plug-ins are located in the directory <TWS_HOME>/eventPlugIn. This directory contains all the built-in event providers and action providers. It is possible to install new plug-ins by placing them into this directory. Every defined plug-in is a jar file consisting of three main components: TWSPlugIn.properties: A file containing the main plug-ins information TWSPluginConfiguration.xml: A file containing the plug-ins configuration One or more Java class files containing the implementation of the plug-in The following template plug-ins are included in the <TWS_HOME>/eventPlugIn directory: GenericActionPlugin.jar GenericEventPlugIn.jar You can look inside the content of these files to get an idea how the plug-in is composed. The detailed explanation of the steps necessary for creating a new plug-in is beyond the scope of this book, so we provide you with a brief description only.
Steps for activating a new plug-in

The steps to implement new events or actions are as follows: 1. Create a new event/action plug-in. 2. Put it inside the directory <TWS_HOME>/eventPlugIn. 3. Restart WebSphere Application Server.
Graphical interface for plug-ins creation

A Workbench based on Eclipse technology is currently being developed. This new graphical interface will significantly simplify the plug-in development process. This development interface is expected to be available in the 1st half of 2008.
343
The expected features of this Workbench are: Create Event plug-ins. Create Action plug-ins. Create applications that will use Tivoli Workload Scheduler public APIs. This Workbench will contain: Sample event plug-ins. Sample action plug-ins.
6.4.15 Defining new events

New events can be defined using the evtdef command. This command has a syntax slightly similar to the dumpsec/makesec Tivoli Workload Scheduler commands. Using this command, you can dump the current generic events definition into a text file. The file has a XML structure. Then you can edit the file and upload it back to the server. The evtdef command can be used as follows: evtdef [connectionParameters] loaddef <file_path> Using the dumpdef function, it is possible to create a file with the actual generic event definitions. evtdef [connectionParameters] dumpdef [<file_path>] Using the loaddef function, it is possible to load generic event definitions. Here we provide an example describing how the event definition can be dumped, modified, and then uploaded back to the server: 1. Run evtdef dumpdef conf.txt. The conf.txt file with generic event definition is created. 2. Copy the conf.txt file to the new new_conf.txt file in order to preserve the original settings. 3. Modify the new_conf.txt file. Add the new event definition into this file. 4. Run evtdef loaddef new_conf.txt. A new event definition is uploaded from the new_conf.txt file.
344
6.4.16 Tivoli Enterprise Console integration in detail

This section describes the tasks that should be performed when integrating the Tivoli Workload Scheduler with Tivoli Enterprise Console using the event driven workload automation. If you are not interested in Tivoli Enterprise Console integration using the event driven workload automation, you may skip this section. Important: In the GA version of Tivoli Workload Scheduler V8.4, there is a problem in the Tivoli Enterprise Console Event Forwarder that is related to the TimeStamp attribute. Events sent to the Tivoli Enterprise Console server contain hardcoded TimeStamp attributes, which contains multiple string values that are not enclosed by quotes. This causes a PARSING FAILED state on the Tivoli Enterprise Console side. It is not possible to modify the value of TimeStamp attribute. This defect is fixed in FP01.
Configuring the Tivoli Workload Scheduler global options

This section describes how to configure the Tivoli Workload Scheduler master domain manager in order to be able to send events to the Tivoli Enterprise Console server. We describe how to gather the necessary Tivoli Enterprise Console configuration parameters and how to apply them on the Tivoli Workload Scheduler master domain manager.
Obtaining the Tivoli Enterprise Console configuration data

This section describes how to determine two important values that must be set on the Tivoli Workload Scheduler master domain manager. You need to determine the following values: Tivoli Enterprise Console host name: This is the network name of the Tivoli Enterprise Console server. Be aware that the machine hosting the Tivoli Enterprise Console server can have multiple network names. Choose the one that can be resolved by the Tivoli Workload Scheduler server. Tivoli Enterprise Console reception port: This is the port where the Tivoli Enterprise Console server listens for incoming events.
345
Perform the following steps in order to determine this value: Source the Tivoli Framework environment. On UNIX/Linux platforms, issue the following command: . /etc/Tivoli/setup_env.sh Note the leading dot at the beginning of the line. On a Windows platform, issue the following command: C:\Windows\system32\drivers\etc\Tivoli\setup_env.cmd Navigate to the following directory: On UNIX/Linux platforms, go to $BINDIR/TME/TEC. On a Windows platform, go to %BINDIR%/TME/TEC.
Open the file .tec_config (note the leading dot in the beginning of the file name). Search for the line containing the keyword tec_recv_agent_port and write down the port value. See the example below: tec_recv_agent_port=5529 Note: The default reception port on Windows platform is 5529. The default reception port on UNIX/Linux platforms is 0. However, you should check the real setting by inspecting the value of tec_recv_agent_port.
Verifying the network communication

This section describes how to verify that the communication between the Tivoli Workload Scheduler and Tivoli Enterprise Console is not blocked. Note: In this section, we discuss the Tivoli Workload Scheduler master domain manager. When discussing communication issues, you should consider any candidate for the Event Processor, which is actually the master domain manager and all Backup Masters. If you plan to switch the Event Processor from one node to another, ensure that communications are open between the server that hosts the Event Processor, and the Tivoli Enterprise Console server. Issue the following command on the master domain manager: telnet <TEC_SERVER_HOSTNAME> <TEC_RECEPTION_PORT> You should get the message that the telnet command has successfully connected to the specified port on the specified host.
346
Example 6-1 shows the successful test result.

Example 6-1 Test of communication between TWS and TEC - successful
sydney:/home/tws> telnet sydney 5529 Trying... Connected to sydney. Escape character is '^]'. Note: Tivoli Enterprise Console server must be up and running when performing this test. Example 6-2 shows the unsuccessful test result.
Example 6-2 Test of communication between TWS and TEC - unsuccessful
sydney:/home/tws> telnet sydney 5529 Trying... telnet: connect: Connection timed out In this case, contact your network and firewall administrator.
Setting the global options on the master domain manager

After determining the necessary configuration values, issue the following commands on the Tivoli Workload Scheduler master domain manager: optman chg th=<TEC_SERVER_HOSTNAME> optman chg tp=<TEC_RECEPTION_PORT> Example 6-3 demonstrates how you can check that the values are properly set.
Example 6-3 Checking the TEC related global options
sydney:/home/tws> optman ls |grep -i tec TECServerName / th = sydney TECServerPort / tp = 5529
Importing the class definition into the Tivoli Enterprise Console rulebase
This section describes the format of events that are sent to Tivoli Enterprise Console server by the Tivoli Enterprise Console Event forwarder. In the current release, only one event type can be generated by the Tivoli Enterprise Console Event Forwarder. The name of the class is TWSEvent. This is hardcoded and cannot be adjusted by the Event Rule editor.
347
Available versions of the TWSEvent class

The GA version of the TWSEvent class is stored on the Tivoli Workload Scheduler master domain manager in the directory <TWS_HOME>/Tec/TecEvent/TWSEvent.baroc. We do not recommend using this GA version. You should use either the version that is available with FP01 or the one that has been developed during the writing of this book. For more information about defects in the GA version of TECEventForwarder, refer to Important note about case sensitivity on page 350. Example 6-4 shows the class definition that is available with FP01.
Example 6-4 TWSEvent class available with the FP01
TEC_CLASS : TWSEvent ISA EVENT DEFINES { msg : default="N/A"; severity: default = WARNING; hostname: default="N/A"; ObjectID: STRING; LOB: STRING; Parm_1: STRING; Parm_2: STRING; Parm_3: STRING; Parm_4: STRING; Parm_5: STRING; Parm_6: STRING; Parm_7: STRING; Parm_8: STRING; Parm_9: STRING; Parm_10: STRING; TimeStamp: STRING; Message: STRING; Severity: STRING; }; END Example 6-5 on page 349 shows the class definition that was developed during this IBM Redbooks project. It removes some unnecessary attributes, adds new attributes, and adjusts their behaviors. These new attributes are designed to better distinguish events originating from the current Tivoli Workload Scheduler plan (such as job status changed and so on).
348
Example 6-5 Adjusted TWSEvent class
##################################################### # BAROC definitions for TWS events from TWS_EDWA # <c> Martin Lisy, IBM # ##################################################### # BAROC definitions for TWS events from TWS_EDWA # <c> Martin Lisy, IBM # # Document control : # ver 1.03, Mar 05 2008 # # Version control: # # 1.00 : TWSEvent # 1.01 : Added tws* attributes # 1.02 : added default values # 1.03 : duplicate detection for important attributes ####################################################### TEC_CLASS : TWSEvent ISA EVENT DEFINES { Parm_1: STRING, default='N/A'; Parm_2: STRING, default='N/A'; Parm_3: STRING, default='N/A'; Parm_4: STRING, default='N/A'; Parm_5: STRING, default='N/A'; Parm_6: STRING, default='N/A'; Parm_7: STRING, default='N/A'; Parm_8: STRING, default='N/A'; Parm_9: STRING, default='N/A'; Parm_10: STRING, default='N/A'; msg: default="N/A"; LOB: STRING, default='N/A'; tws_stream: STRING, default='N/A', dup_detect=yes; tws_job: STRING, default='N/A', dup_detect=yes; tws_status: STRING, default='N/A', dup_detect=yes; tws_start: STRING, default='N/A'; tws_duration: STRING, default='N/A'; tws_event_type: STRING, default='N/A', dup_detect=yes; }; END
349
Note: The TWSEvent definition shown in Example 6-5 on page 349 is not the official one. It has been developed during the creation of our IBM Redbooks scenarios. However, it can help you better distinguish some events originating from the Tivoli Workload Scheduler plan.
Important note about case sensitivity

This section describes one important implementation detail that must be considered when writing rules for the Tivoli Enterprise Console server. When editing the properties of the Tivoli Enterprise Console Event Forwarder in the Event Rule editor, you can add up to 10 custom attributes that can be sent to Tivoli Enterprise Console server. The names of these attributes are Custom slot 1, ..., Custom slot 10 on the Tivoli Workload Scheduler side. On the Tivoli Enterprise Console side are those attributes represented as Parm_1, ..., Parm_10. This is a hardcoded behavior. The names of the attributes on the Tivoli Enterprise Console side start with uppercase characters. This can cause problems when creating the Tivoli Enterprise Console rules. Tivoli Enterprise Console interprets by default any term that starts with an uppercase character as a variable. If you want to handle the content of these attributes in Tivoli Enterprise Console rules, you must enclose such attributes in quotes. We inform you about this fact because it is not common to use attribute names starting with uppercase characters, and most TEC programmers do not use such attributes. Refer to Tivoli Enterprise Console rule handling for the sample mapping on page 354, where we demonstrate a sample usage of custom parameters. The exact syntax is included in Example 6-7 on page 354. If you do not enclose any of the custom attributes by quotes, your rule still could be successfully compiled, but the affected predicates in the rules will fail.
Importing the TWSEvent class into the TEC rulebase

This section describes how to import the TWSEvent class into the Tivoli Enterprise Console rulebase.
350
Note: You should perform the backup of the current rulebase before you make any adjustment to it. Also, any changes to the production rulebase should be done only together with the responsible Tivoli Enterprise Console administrator. Perform the following steps: 1. Choose the TWSEvent class definition that you want to use: Copy the content of Example 6-4 on page 348 to the clipboard if you want to use the TWSEvent class definition that is available with FP01. Copy the content of Example 6-5 on page 349 to the clipboard if you want to use the TWSEvent class definition that has been developed by the IBM Redbooks team. 2. Log on to the Tivoli Enterprise Console server. 3. Launch a text editor and paste the clipboard content. Save the file on your file system as TWSEvent.baroc. 4. Source the Tivoli Framework environment: On UNIX/Linux platforms, issue the following command: . /etc/Tivoli/setup_env.sh Note the leading dot in the beginning of the line. On a Windows platform, issue the following command: C:\Windows\system32\drivers\etc\Tivoli\setup_env.cmd 5. Determine the current rulebase name. Example 6-6 demonstrates how to obtain the rulebase name.
Example 6-6 Determining the current rulebase name
sydney:/ wrb -lscurrb The currently used rule base was loaded from the rule base named 'itso_rb'. 6. Go to the directory where you have saved the TWSEvent.baroc file. 7. Issue following commands: wrb -imprbclass TWSEvent.baroc <your_active_rulebase_name> wrb -comprules <your_active_rulebase_name> wrb -loadrb <your_active_rulebase_name> wstopesvr wstartesvr
351
Your Tivoli Enterprise Console server should now be able to successfully recognize the events coming in from the Tivoli Enterprise Console Event Forwarder.
Defining the sample mapping for the TEC Forwarder

This section offers you a suggestion on how to use the custom attributes that are provided with the Tivoli Enterprise Console Event Forwarder. As already described, you may extend the standard event generated by Tivoli Enterprise Console Event forwarder. There are up to 10 custom attributes that can be sent to Tivoli Enterprise Console server. You may add, modify, and remove these custom attributes in the Event Rule editor. The names of these attributes are Custom slot 1, ..., Custom slot 10 on the Tivoli Workload Scheduler side. On the Tivoli Enterprise Console side, these attributes are represented as Parm_1, ..., Parm_10. This is a hardcoded behavior. You may define a sample mapping that assigns some fixed meaning to each custom attribute. If you strictly follow this mapping in each rule on the Tivoli Workload Scheduler side, you may then create an universal rule on the Tivoli Enterprise Console side. This rule can parse the custom attributes and evaluate their content. We have also reserved the last custom attribute for determining the event type. As already mentioned, TECEventForwarder sends only one class into Tivoli Enterprise Console. This can be a limitation when writing rules for different purposes. We have used the following workaround for this limitation: In the Tivoli Workload Scheduler event rule definition, we use the Custom slot 10 as the attribute carrying the information about the event type. Typical examples of the Custom slot 10 values are shown below: fta_link jobs periodic_jobs job_streams Generally speaking, on the Tivoli Workload Scheduler side you can use any value that will help you distinguish the event type on the Tivoli Enterprise Console side. This will make writing the Tivoli Enterprise Console rules easier.
352
In the Tivoli Enterprise Console rule definition, we map the value of the Custom slot 10 to the attribute tws_event_type. This is shown in Example 6-7 on page 354. We use the value of tws_event_type in the event filter of each rule working with TWSEvent class. The sample Tivoli Enterprise Console rule is shown in Example 6-8 on page 355.
Sample mapping example

Figure 6-43 shows the sample mapping of custom attributes. As you can see, we use the variables for filling in the content of the custom attributes. The last attribute Custom slot 10 is used for determining the event type.
Figure 6-43 Sample mapping of custom attributes
Note: The sample mapping shown in Figure 6-43 is just a suggestion. You can develop your own custom mapping, depending on which events you are most often sending to the Tivoli Enterprise Console server.
353
Tivoli Enterprise Console rule handling for the sample mapping

This section contains a sample Tivoli Enterprise Console rule handling the sample mapping that has been presented in Sample mapping example on page 353. Example 6-7 shows the sample rule that handles the custom attributes mapping. The purpose of this rule is to copy the values of custom attributes to attributes with more descriptive names (tws_job, tws_stream, and so on). This rule can be used only in the conjunction with the TWSEvent class definition that is included in Example 6-5 on page 349. You cannot use this rule with the TWSEvent class definition that is provided with the Tivoli Workload Scheduler V84 GA, or with the version available with FP01.
Example 6-7 Sample TEC rule used handling of custom attributes mapping
/* * Component Name: TWSEvent.rls * * $Revision: 1.0 $ * * Description: * Rules Created for TWS-TEC integration using EDWA * * (C) COPYRIGHT Martin Lisy, IBM * * Document Control : * 1.00 Initial version - performing sample mapping * */ rule: modify_TWS_msg_hostname: ( %directive: trace, event: _event of_class 'TWSEvent' where [ 'Parm_1': _hostname, 'Parm_2': _tws_stream, 'Parm_3': _tws_job, 'Parm_4': _tws_status, 'Parm_5': _tws_start, 'Parm_6': _tws_duration, 'Parm_10': _tws_event_type ], action: set_msg_and_hostname: ( bo_set_slotval(_event,hostname,_hostname), bo_set_slotval(_event,tws_stream,_tws_stream),
354
bo_set_slotval(_event,tws_job,_tws_job), bo_set_slotval(_event,tws_status,_tws_status), bo_set_slotval(_event,tws_start,_tws_start), bo_set_slotval(_event,tws_duration,_tws_duration), bo_set_slotval(_event,tws_event_type,_tws_event_type), bo_set_slotval(_event,source,'TWS'), re_mark_as_modified(_event,_) ) ). Note: Note that the attributes Parm_1, ..., Parm_10 are enclosed by quotes. This is necessary because these attributes start with an uppercase character. Refer to Important note about case sensitivity on page 350 for more information. Example 6-8 shows the sample rule that uses the value of the tws_event_type attribute. This helps you write a more exact event filter and simplifies rule writing.
Example 6-8 Sample TEC rule working with the TWS event type
rule: handle_fta_linked_unlinked: ( event: _event of_class 'TWSEvent' where [ tws_group: equals 'fta_link', tws_status: equals 'Linked', hostname: _hostname ], action: close_unlinked: ( first_instance(event: _unlink_ev of_class 'TWSEvent' where [ tws_group: equals 'fta_link', tws_status: equals 'Unlinked', status: outside ['CLOSED'], hostname: equals _hostname ] ), set_event_status(_unlink_ev,'CLOSED'), re_mark_as_modified(_unlink_ev,_) ), action: drop_itself: ( drop_received_event ) ).
355
Importing a sample rule into the TEC rulebase

This section describes how to import the sample mapping rule into the Tivoli Enterprise Console rulebase. Note: If you want to use the sample mapping rule presented in Tivoli Enterprise Console rule handling for the sample mapping on page 354, you must have already imported the TWSEvent class definition into the rulebase. You must use the TWSEvent class included in Example 6-5 on page 349 in conjunction with our sample mapping rule. Before importing the sample mapping rule, you must complete the steps described in Importing the TWSEvent class into the TEC rulebase on page 350. Perform the following steps: Note: You should perform the backup of the current rulebase before you make any adjustment to it. Also, any changes to the production rulebase should be done only together with the responsible Tivoli Enterprise Console administrator. 1. Copy the contents of Example 6-7 on page 354 to the clipboard. 2. Log on to the Tivoli Enterprise Console server. 3. Launch a text editor and paste the clipboard content. Save the file on your file system as TWSEvent.rls. 4. Source the Tivoli Framework environment. a. On UNIX/Linux platforms, issue the following command: . /etc/Tivoli/setup_env.sh Note the leading dot in the beginning of the line. b. On a Windows platform, issue the following command: C:\Windows\system32\drivers\etc\Tivoli\setup_env.cmd 5. Determine the current rulebase name. Example 6-9 demonstrates how to obtain the rulebase name.
sydney:/ wrb -lscurrb The currently used rule base was loaded from the rule base named 'itso_rb'.
356
6. Go to the directory, where you have saved the TWSEvent.rls file. 7. Issue the following commands: wrb wrb wrb wrb -imprbrule TWSEvent.rls <your_active_rulebase_name> -imptgtrule TWSEvent EventServer <your_active_rulebase_name> -comprules <your_active_rulebase_name> -loadrb -use <your_active_rulebase_name>
Your Tivoli Enterprise Console server should now be able to perform sample attribute mapping.
Switching off the original integration

If you have used integration through a text log file that is specified in the BmEvents.conf file, and you want to switch off this integration, you must perform the steps described in this section. Important: Do not switch off the original integration unless you are absolutely sure that you have created an equivalent Tivoli Workload Scheduler monitoring process using the event driven workload automation. Do the following steps if you want to switch off the original integration: 1. Turn off the logging of Tivoli Workload Scheduler to the log file by modifying the file <$TWS_HOME>/BmEvents.conf. Comment any line that begins with the word FILE and is currently uncommented. The modified line should look as follows: #FILE=/home/tws/stdlist/logs/tws_events.log 2. Switch off the Tivoli Enterprise Console log file adapter on the master domain manager (or on any workstation where the Tivoli Enterprise Console log file adapter parses the Tivoli Workload Scheduler log file). On a Windows platform, stop the service representing the corresponding instance of the Tivoli Enterprise Console log file adapter and switch it to manual mode. On UNIX/Linux platforms, edit the /etc/rc.tecad_logfile and comment the corresponding line representing the corresponding instance of the Tivoli Enterprise Console log file adapter. Also use the content of the line to assemble a stop command to the log file adapter. For example, issue: /tme1/tws/LOGFILE/bin/init.tecad_logfile stop TIV1TEC where TIV1TEC is the name of the Tivoli Enterprise Console log file adapter instance.
357
Note: Consult your Tivoli Enterprise Console administrator if you are unsure about the Tivoli Enterprise Console log file adapters. 3. Remove any rules and class definitions from the Tivoli Enterprise Console server. a. Log on to the Tivoli Enterprise Console server. b. Source the Tivoli Framework environment. On UNIX/Linux platforms, issue the following command: . /etc/Tivoli/setup_env.sh Note the leading dot in the beginning of the line. On a Windows platform, issue the following command: C:\Windows\system32\drivers\etc\Tivoli\setup_env.cmd c. Determine the current rulebase name. Example 6-10 demonstrates how to obtain the rulebase name.
sydney:/ wrb -lscurrb The currently used rule base was loaded from the rule base named 'itso_rb'. d. Determine the current rulebase path. Example 6-11 demonstrates how to obtain the rulebase path.
Example 6-11 Determining the current rulebase path
sydney:/ wrb -lsrb -path itso_rb Rule Base Name Directory -------------- ------------------------------------itso_rb sydney:/usr/local/Tivoli/bin/aix4-r1/TME/TEC/itso_rb Note: You should perform the backup of the current rulebase before you make any adjustment to it. Some commands permanently delete some files from the Tivoli Enterprise Console rulebase! Also, any changes to the production rulebase should be done only together with the responsible Tivoli Enterprise Console administrator. e. Navigate to the current rulebase and go to the TEC_RULES subdirectory. Depending on your master domain manager platform, your ruleset file
358
containing Tivoli Workload Scheduler related rules should be named as follows: maestro.rls on UNIX/Linux platforms maestront.rls on NT platforms
For our demonstration purposes, the file name is maestro.rls. Run the following commands: wrb -deltgtrule maestro EventServer <your_active_rulebase_name> wrb -delrbrule maestro <your_active_rulebase_name> f. Navigate to the current rulebase and go to the TEC_CLASSES subdirectory. Depending on your master domain manager platform, your baroc files containing Tivoli Workload Scheduler related classes should be named as follows: maestro.baroc on UNIX/Linux platforms maestront.baroc on NT platforms
For our demonstration purposes, our file name is maestro.baroc. Run wrb -delrbclass maestro.baroc. Note: This command may fail if any of the classes defined in the file maestro.baroc is referenced by any active ruleset (other than the maestro.rls file that we have deleted in the previous step). In this case, consult your Tivoli Enterprise Console administrator. g. Finally, compile the modified rule base by running the following commands: wrb -comprules <your_active_rulebase_name> wrb -loadrb <your_active_rulebase_name> wstopesvr wstartesvr You have removed the original integration of Tivoli Workload Scheduler with Tivoli Enterprise Console server.
359
6.5 Event driven workload automation demonstration

In this section, we demonstrate some of the capabilities of the event driven workload automation. We provide you with four scenarios: In the first scenario, we provide step by step instructions together with screen captures. This first scenario should serve a guide to event rules creation and querying the instance. In the second scenario, we provide step by step instructions, but we include screen captures only for those steps that were not described in the first scenario. The final two scenarios are described briefly. These scenarios give you an idea of how flexible event driven workload automation is, and for which possible tasks it can be used.
6.5.1 Scenario 1: Simple notification

This section describes how to create a simple notification scenario using event driven workload automation.
Scenario abstract
This scenario demonstrates how to create a rule that monitors the state of particular jobs. When any of the jobs matches the wildcard definition ABENDs, an e-mail is sent automatically to the responsible Tivoli Workload Scheduler administrator. Furthermore, we specify a time validity interval for the event rule, which will cause the rule to be valid only between defined dates. Upon the completion of the steps described in this scenario, you should be able to: Log in to the Tivoli Dynamic Workload Console. Navigate to the event driven workload automation portlets within the Tivoli Dynamic Workload Console. Launch a rule editor. Create a new rule. Specify a rules validity. Add a single event object to the rule. Add a single action object to the rule.
360
Use variables in the actions definition. Activate the rule. List the rule instances. View the rule instances.
Scenario instructions
This section contains the step by step instructions for creating and activating the event rule. We describe how to test the scenario and how to query the existing event rule instance.
Creating an event rule

In this section, we provide step by step instructions for creating the event rule representing this scenario. We provide the instructions in the form of numbered steps. Important: Internet Explorer V6.0 has a known limitation issue in the implementation of JavaScript engine. It can utilize CPU up to 100% while working with the rule editor, which is the key feature provided with the event driven workload automation portlets. The fix for this limitation is available at http://support.microsoft.com/kb/942840. Internet Explorer 7.0 (or higher) and Mozilla Firefox 2.0 (or higher) do not have this limitation. 1. Log in to the Tivoli Dynamic Workload Console using the following steps: Open new browser window and go to the address http://<tdwc_hostname>:29060/ibm/console.
361
The login window appears. Enter your credentials and click Log In. (Figure 6-44). We assume that you are using the account that has sufficient privileges for working with event rules.
Figure 6-44 Simple notification scenario - 1
362
2. Select Tivoli Workload Scheduler Workload Definition Event Management (Figure 6-45).
363
3. Click New Event Rule. If you have defined more engine connections, you will have to select which engine to which you want to connect (Figure 6-46). Select the engine from drop-down list and click Go. If you have only one engine connection defined, you will not be prompted for engine selection and the Event rule editor appears immediately.
4. When the back-end Tivoli Workload Scheduler engine has been selected (either automatically or selected by you), the Event rule editor appears (Figure 6-47 on page 365).
364
5. Fill in the general rule properties. Go to the General Properties pane and fill in the following values: Rule name: SimpleNotification. Description: This rule monitors jobs ACCOUNTING_@ on server SYDNEY. Time zone: Leave blank. Valid from: Select first day, since the rule is valid. Click the calendar sign and select the date. We have used 12/1/07 in our scenario. Valid to: Select last day, since the rule is valid. Click the calendar sign and select the date. We have used 12/31/07 in our scenario. Daily start: Specify the hour and minute when the rule becomes active each day. We have used 03:00:00 AM in our scenario.
365
Daily end: Specify the hour and minute when the rule becomes inactive each day. We have used 06:30:00 PM in our scenario. Note: The time format must be strictly HH:MM:SS {AM|PM}. It is necessary to provide the time in AM/PM format, including the AM/PM selector in the end. Otherwise, the syntax validator will not accept the value. Leave the Draft check box checked. You should see a result similar to Figure 6-48.
6. Go to the Events pane. Expand the Tivoli Workload Scheduler plan events and select Job status Changed (Figure 6-49 on page 367).
366
7. The event object will be added to the workplace on the right side (Figure 6-50).
367
8. Fill in the properties of the event object. Click the newly added event object. Scroll down until you see the Properties pane (Figure 6-51).
368
9. As you can see, there is large blank space between your selected event object and the Properties pane. Collapse the Actions pane by clicking the mark in the upper left corner of the Actions pane (Figure 6-52).
369
10.Now your window should look like Figure 6-53.
370
11.Go to the Properties pane and fill in the following values: Event name: AccountingJobAbend Job name: Accounting* Leave the other values unchanged. The default value * (asterisk) is a wildcard. The contents of the Properties pane should look like Figure 6-54.
12.This definition is not sufficient for our purposes. We want to monitor a specific set of jobs on a specific workstation. The event object that we have defined so far evaluates only the job names, but does not consider the workstation name.
371
You must add a new property to the event definition. Click -- Select Property to add -- and select Job workstation from the drop-down list (Figure 6-55).
13.The selected property has been added. Fill in the value of the workstation that you want to monitor. The value should correspond to workstation name in your Tivoli Workload Scheduler database. We use SYDNEY as a workstation name in our scenario. When you fill in all the values, your window should look like Figure 6-56 on page 373. Note that the icon representing the event object has dynamically updated its description.
372
This is the last step in the event object definition.
373
14.Now you must define the action. Expand the Actions pane that you previously collapsed (Figure 6-57).
374
15.Your window should look like Figure 6-58.
375
16.In the Actions pane, expand the Mail sender plug-in and select Send mail (Figure 6-59).
17.The action object will be added to the workplace on the right side (Figure 6-61 on page 377). The red color of an action object indicates that there is an error in one or more property values. In our case, it is caused by blank values in the mandatory properties (Figure 6-60).
18.Fill in the properties of the action object. Click the action object Send mail and scroll down to the bottom of the Properties pane (Figure 6-61 on page 377).
376
19.Go to the Properties pane and fill in the following values: Action description: Send e-mail to the administrator. To (recipient): Type the administrators e-mail address here. We use a locally defined e-mail account called tws@sydney.itsc.austin.ibm.com. Note: You must have already configured the Mail sender properties, as described in Mail Sender on page 283. The configuration steps consist of providing the proper values for the SMTP server name, communication port, and authentication. The configuration changes are performed by a change of a few global options using the optman command.
377
Subject: Accounting job ABENDed. Your window should look like Figure 6-62.
20.Add the property for the body of the e-mail. Click -- Select Property to add -and select Body from the drop-down list (Figure 6-63).
21.The selected property has been added. Fill in the body of the e-mail. We want to include some fixed text and then the exact name of the job that ABENDed. We use variables for this task. Perform the following steps: a. Type the following text into the body textbox: Hello admin, we inform you that the job. b. Click the Variables... button. The variable selector appears (Figure 6-64 on page 379).
378
22.Continue filling in the body property. In the variable list, click Job name. The variable will appear in the body textbox, as shown in Figure 6-65.
379
23.Finish filling in the bodys properties: a. Continue filling in the bodys properties. Click back to the body textbox and continue typing The actual duration of the job was. b. Click Variables... and select Actual duration. The result should look like Figure 6-66.
This was the last step in the action object definition. 24.Save the rule definition. Scroll up to the top of the rule editor. While scrolling up, make sure that both event and action objects are not red. This would mean that something is wrong with the object definition. Make sure that the Draft check box is selected. Click the Save button. You should see an output similar to Figure 6-67 on page 381.
380
You have finished the rule definition. Close the rule editor by clicking Close.
Making the rule active

In this section, we provide step by step instructions for querying and activating the event rule outside the rule editor. We provide the instructions in the form of numbered steps. We assume that you are logged into Tivoli Dynamic Workload Console using the account that has sufficient privileges for working with event rules. 1. Select Tivoli Workload Scheduler Workload Definition Event Management (Figure 6-68).
381
2. Click Event Rules. The content of the right pane changes. Click All Event Rules (directly on the link, not on the check box on the left side) (Figure 6-69).
3. Select the proper engine from the drop-down list and click OK (Figure 6-70).
382
4. The list of already defined rules appears. If you have defined just your first rule, the list should look like in the Figure 6-71.
We explain the terms Completion status and Internal status in Figure 6-71. Basically, they have the following meaning: Completion status: Rule developer determines whether the rule is complete or is in draft status. Draft rules cannot be active in the Tivoli Workload Scheduler environment. It is possible to set a complete rule to draft and vice versa. Internal status: Determines whether the rule is built and deployed to target systems. Such a rule is called Active. If the rule does not behave well, it can be deactivated by setting it to Draft. During the next deployment process the rule will be deactivated. If the deployment process in your Tivoli Workload Scheduler environment is periodical (this is the default behavior), we can say that the following relationship is between Completion status and Internal status: The rule that has not been completed yet has not been activated yet. The rule that has been set to Complete will become Active soon (depending on the deployment period; the default value is 5 minutes).
383
The active rule that has been set back to Draft will be deactivated soon (depending on deployment period; the default value is 5 minutes). 5. Have a look at the rule definition. Click the rule name (directly on the link, not on the check box on the left side) You will see the content of the event rule. This view gives you a good opportunity to see all rule details. The object included in the view can be collapsed (Figure 6-72).
6. When you have checked the content of the rule, close the view by clicking the Close View button (Figure 6-73).
384
7. If you are satisfied with the content of the event rule, you can activate it by clicking Set as complete (Figure 6-74).
8. The Completion status of the event changes to Complete. Click Refresh and then your window should look similar to Figure 6-75.
Note that both states have changed: Completion status: Complete. Internal status: Activation pending. This status means that the rule is about to be deployed when the next deployment time occurs. The default behavior is periodical deployment that takes place every five minutes. 9. If you have set the default deployment values, then the Internal status of this rule should change within five minutes. Wait some time and click Refresh.
385
After several attempts (but no longer than five minutes), the Internal status should change to Active (Figure 6-76).
You have now completed the definition tasks related to this scenario. You have created a rule that monitors the status of the job SYDNEY#ACCOUNTING@ and then you have activated this rule. After some time, the rule becomes active. If it does not, check the global options that determine your event driven workload automation settings.
Testing the scenario

This section describes how you can test this sample scenario. In order to test this scenario, do the following steps: 1. Make sure that the current time is within the validity interval of the event rule. Check the date and time range that have you specified during the event rule definition. 2. Create the job definition with the following properties: Name: ACCOUNTING_1 Workstation: SYDNEY (use the same value, as in the rule definition, in the event properties) Task type: Your machines platform Login: Any suitable user ID Task: System command exit 1 3. Submit this job into the current plan. 4. Check the mailbox of the user that you have specified in the rule definition. An e-mail similar to the one shown in Example 6-12 on page 387 should arrive.
386
Example 6-12 Simple notification scenario - incoming e-mail
Message 6: From TWS Thu Dec 27 07:22:35 2007 Date: Thu, 27 Dec 2007 07:22:35 +0100 (GMT+01:00) From: TWS To: tws@sydney.itsc.austin.ibm.com Subject: Accounting job ABENDed Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Hello admin, we inform you that the job ACCOUNTING_1 ABENDed. The actual duration of the job was 1
Checking the rule instances in the Tivoli Dynamic Workload Console This section explains how you can check the instances of the event rule.
An instance is the real representation of a rule that has been triggered. The event rule instance is created in these two cases: The correlation condition is completely satisfied and the response actions have been triggered. The timeout set on the correlation condition expired and the timeout actions have been triggered. Event rule instances can be queried using the Tivoli Dynamic Workload Console. You can use the following approaches: Search for the particular rule and then view only the instances of that rule. Getting a list of all instances and then select a desired instance from this list. In this scenario, we demonstrate only the first mentioned approach: searching for a rule and the viewing its instances. Perform the following steps in order to view the rule instances: 1. Log in to the Tivoli Dynamic Workload Console. 2. Select Tivoli Workload Scheduler Workload Definition Event Management. 3. Click Event Rules. 4. Click All Event Rules. 5. Select the proper engine from the drop-down list and click OK.
387
6. A list of defined event rules appears. Select the check box on the left of the SIMPLENOTIFICATION event. Then, click the drop-down menu --- More Actions --- and select Show Instances, Then click the Go button. You can see these steps in Figure 6-77.
7. The list of existing rule instances appears. You should see an output similar to Figure 6-78.
8. Click the instance name SIMPLENOTIFICATION (directly on the link, not on the check box on the left side). Figure 6-79 on page 389 shows the output.
388
The instance contains the real values such as job name, workstation name, and so on. The instance represents a real run of the rule.
6.5.2 Scenario 2: Trigger TWS Agents status

This section describes how to use event driven workload automation for monitoring the link status of workstations. If any workstation becomes unlinked for too long, we trigger operative and notification actions.
Scenario abstract
This scenario demonstrates how to create a rule that monitors the state of a particular workstation. If the workstation is unlinked for more than 10 minutes, then a defined job stream is submitted and an event is sent to the Tivoli Enterprise Console (TEC). This rule does not use a time validity interval. We assume that you have completed the scenario in 6.5.1, Scenario 1: Simple notification on page 360. There you have learnt how to: Log in to the Tivoli Dynamic Workload Console. Navigate to the event driven workload automation portlets within the Tivoli Dynamic Workload Console. Launch a rule editor. Create a new rule. Specify rule validity.
389
Add a single event object to the rule. Add a single action object to the rule. Use variables in the properties of an action object. Activate the rule. List the rule instances. View the rule instances. Upon the completion of the steps described in this scenario, you should be able to perform these additional tasks: Add multiple events to an event rule. Set a correlation condition. Define a timeout. Add a timeout action. Use the Lookup function.
This section contains the step by step instructions for creating the event rule representing this scenario. We do not provide screen captures for the tasks that have been already explained in 6.5.1, Scenario 1: Simple notification on page 360. We provide screen captures only for the tasks that have not been demonstrated yet.
Creating an event rule

In this section, we provide step by step instructions for creating the event rule representing this scenario. Important: Internet Explorer V6.0 has a known limitation issue in the implementation of the JavaScript engine. It can utilize CPU up to 100% while working with the rule editor, which is the key feature provided with the event driven workload automation portlets. The fix for this limitation is available at http://support.microsoft.com/kb/942840. Internet Explorer 7.0 (or higher) and Mozilla Firefox 2.0 (or higher) do not have this limitation. 1. Log in to the Tivoli Dynamic Workload Console. 2. Select Tivoli Workload Scheduler Workload Definition Event Management.
390
3. Click New event rule. 4. If you have defined more engine connections, you will have to select which engine to which you want to connect. Select the engine from the drop-down list and click Go. If you have only one engine connection defined, you will not be prompted for engine selection and the Event rule editor appears immediately. When the back-end Tivoli Workload Scheduler engine has been selected (either automatically or selected by you), the Event rule editor appears. 5. Fill in the general rule properties. Go to the General Properties pane and fill in the following values: Rule name: AlertFTA. Description: When FTA is unlinked for a long period of time, it sends a TEC event and submits a job stream. Leave the values for Time zone, Valid from, Valid to, Daily start, and Daily end blank. Uncheck the Draft check box. 6. Go to the Events pane. Expand the Tivoli Workload Scheduler plan events and select Child Workstation Link Changed. The event object will be added to the workplace on the right side. 7. Fill in the properties of the event object. Click the currently added event object and scroll down until you see the Properties pane. If necessary, collapse the Actions pane. With this newly added object selected, perform the following steps in the Properties pane: Workstation: Leave the * (asterisk). This event will be generated from any unlinked workstation. Click -- Select property to add -- and select Link status. The selected property will be added. Select the Unlinked value from the list.
391
The Properties pane should look like Figure 6-80.
Figure 6-80 FTA scenario - 1
8. Return to the Events pane. Add the same object type again. Expand the Tivoli Workload Scheduler plan events and select Child Workstation Link Changed. The second event object will be added to the workplace on the right side. 9. Fill in the properties of the event object. Click the currently added event object and scroll down until you see the Properties pane. If necessary, collapse the Actions pane. With this newly added object selected, perform the following steps in the Properties pane: Workstation: Leave the * (asterisk). This event will be generated from any unlinked workstation. Click -- Select property to add -- and select Link status. The selected property will be added. Select the Linked value from the list. 10.There are two similar event objects in the Events pane. Specify the property that should serve as a correlation key. We want to correlate events based on the workstation name because we want to pair the events Linked and Unlinked only if they originate from the same workstation. In the column Correlate events on of the Events pane, select the Workstation check box (Figure 6-81 on page 393).
392
11.Set the correlation condition to event sequence. Click the event sequence icon. 12.Select the Timeout check box and input the value of 10. Change the units in the drop-down menu to Minutes (Figure 6-82).
You have performed all the necessary tasks for event objects definition. 13.Expand the Actions Pane and click the Timeout actions bookmark. 14.Expand the Tivoli Workload Scheduler actions action provider and click Submit job stream. The action object will be added to the workplace on the right side.
393
15.Click the newly added action object and go to the Properties pane. Fill in the following properties: a. Click Lookup... next to the field for the Job stream name. A search window will pop up (Figure 6-83).
b. In the search window, leave the asterisks in both fields and click Search. The window fills up with the list of job streams defined in your Tivoli Workload Scheduler database. c. Double-click the desired job stream name. The fields in the Properties pane Job stream name and Job stream workstation name are populated by your selection (Figure 6-84 on page 395).
394
16.Now add a second action to the Timeout actions workplace. Expand the Tivoli Enterprise Console event forwarder event provider and select Forward event to Tivoli Enterprise Console. This second action object will be added to the workplace on the right side. 17.Click the newly added action object and go to the Properties pane. Fill in the following properties: Message: Start typing i. Workstation.
395
ii. Click Variables.... Expand the first offered event and select Workstation (Figure 6-85).
iii. Continue typing has been unlinked for more that 10 minutes! The complete message should look as follows: Workstation %{childWksLnkChgEvt4.Workstation} has been unlinked for more that 10 minutes! Severity: WARNING You have performed all tasks necessary for the action objects definition. 18.Scroll up to the top of the window. Click Save. Because we have already unchecked the Draft check box, the rule will be marked as Complete. During the next deployment time, it will be built and deployed to the target workstations. Because we have specified the wildcard * as the workstation name (in the event property definition), this rule will be deployed to all workstations in the Tivoli Workload Scheduler environment. Note: Usually you should be careful and comprehensively check the rule definition before deploying it to all workstations. In this case, we demonstrated a different approach than in the first scenario. We recommend you save such global rules as Draft when you create them. Then, after review, you can mark them as Complete and they will be deployed.
396
6.5.3 Scenario 3: Submit a Job Stream when FTP transfer completes

This scenario gives you an idea of what else can be accomplished by leveraging the event driven workload automation. We do not provide detailed instructions for this scenario, because all the essential steps necessary for working with event driven workload automation have been already described in previous scenarios. We just offer you an idea of what else can be done using this flexible feature.
Scenario abstract
You can define an event rule that performs the following: When a file is created on some workstation, this file is modified, and then the file modification finishes, we assume that a file transfer started and, after some time, has completed. Based on this fact, we want to reply to a prompt and submit a job stream.
You can accomplish this task by performing the following steps: 1. Add an event based on the File Monitor provider. The selected event type is Modification completed. Specify a workstation name and the file that you want to observe. 2. Add an action based on the Tivoli Workload Scheduler Action provider. The action type is Reply to prompt. Fill in the prompt name and select the reply type (YES/NO). 3. Add action based on Tivoli Workload Scheduler Action provider. The action type is Submit job stream. Fill in the job stream name and the name of the workstation where the job stream runs. Use a Lookup function that will allow you to get the job stream name from the Tivoli Workload Scheduler database. 4. Uncheck the Draft check box and save the rule. 5. After the defined deployment period, the rule becomes active within the Tivoli Workload Scheduler. The other way how to activate the rule immediately is by issuing planman deploy from the command line.
6.5.4 Scenario 4: Trigger a shopping online transaction

This scenario gives you an idea about how custom events can significantly extend the scope of event driven workload automation. We give you suggestions on how you can integrate your business applications with Tivoli Workload Scheduler. Using this integration, you can implement batch workload automation driven by events originating from your business applications.
397
By using custom defined events you can define any condition you like. These events do not need to originate from the Tivoli Workload Scheduler or from the set of built-in event providers. It is up to you to decide what custom event you define. As for the event source, you can define your own generic event plug-in for generating the custom events, or you may leverage the command-line utility sendevent. This command-line utility can be called as an external program from your business applications. Note: The graphical workbench that should simplify the plug-ins development will be available in the first half of 2008.
Scenario abstract
Your IT department operates a business critical application. This application is responsible for handling customers shopping transactions. In order to track the response time, implement the following scenario: When a customer initiates a shopping request, your operation will perform the usual tasks, like authentication and so on. In addition, your application will generate the custom event shopping_request_initiated. You can generate this event either by implementing a generic event plug-in or using the sendevent utility. If everything is OK, your application allows the users to start shopping. In addition, a custom event shopping_transaction_permitted is sent to the Tivoli Workload Scheduler event processor. If any error occurred and the customer did not get a shopping permission, the custom event shopping_transaction_permitted would not be generated. This incorrect application behavior on the Tivoli Workload Scheduler side is handled as follows: When the custom event shopping_request_initiated is received and the custom event shopping_transaction_permitted is not received within one minute, an e-mail should be sent to the user that initiated the transaction. Furthermore, the Ad Hoc job performing some corrective actions will be submitted.
In this section, we give you a brief description of the necessary steps for implementing this scenario.
Preparing the event source

It is your choice if you develop your own event generic event plug-in or you use the sendevent utility. Choose any of these possible ways for integrating the Tivoli Workload Scheduler with your business application.
398
Defining the custom events

On the Tivoli Workload Scheduler event processor, use the evtdef utility to define these two custom events: Shopping_request_initiated: An event that describes when the user initiates the request. Shopping_transaction_perimtted: An event that describes when the users request for shopping has been permitted.
Creating the event rule

Create the event rule using the following steps: 1. Add the event object shopping_request_initiated to the rule definition. 2. Add the event object shopping_transaction_permitted to the rule definition. 3. Specify the event sequence correlation condition. 4. Specify a timeout with a value of one minute. 5. Add the timeout action based on Mail Sender. Select the action Send mail. a. In the recipient name field, use the variable that originates from the event shopping_request_initiated. Provide a user ID variable. b. In the subject and body of the message, use the variable that originates from the event shopping_request_initiated. Provide a transaction ID variable. 6. Add the timeout action based on the Tivoli Workload Scheduler Action provider. The action type is Submit ad hoc job. 7. Fill in the workstation name. 8. Fill in the login name. 9. Fill in the task. Provide a full path to the script or command that you want to execute. Supply a variable to this script/command. Use the variable that originates from the event shopping_request_initiated. Provide a user ID and transaction ID variables. 10.Uncheck the Draft check box and save the rule. 11.After the defined deployment period, the rule becomes active. Using these steps, you have implemented an approach that allows your business applications to influence the behavior of Tivoli Workload Scheduler. If particular conditions in your application occurred, Tivoli Workload Scheduler by itself evaluates these conditions. Then Tivoli Workload Scheduler automatically reacts by submitting a batch workload.
399
400
Part 3
Part
Generic branch job

In this section, we discuss a custom made solution for Tivoli Workload Scheduler: generic branch job.
401
402
Chapter 7.
Generic branch job

In this chapter, we provide a custom made solution for Tivoli Workload Scheduler: generic branch job. Tivoli Workload Scheduler by itself provides a broad range of scheduling functions. But it is also possible to extend these functions for specific needs. Generic branch job will give you an idea of how you can accomplish such a custom solution. This chapter has the following sections: Introduction on page 404 Branch job functionality on page 406 Sample scenarios on page 412 Working with the branch job on page 488 Working with the branch job parameters on page 509 Important notes about the branch job on page 528 Sample scenarios installation on page 530 Generic branch job script source code on page 545
403
7.1 Introduction
Tivoli Workload Scheduler V8.4 comes with many new features. It offers new reporting capabilities, provides the concept of event driven scheduling, and so on. These new features significantly extend the products functionality. However, some tasks can be performed only with additional programming, such as the logical evaluation of a process flow within the job stream. This section describes the generic branch job that allows you to evaluate a particular job status or output. Based on specific conditions, the generic branch job decides which jobs shall be executed within the job stream. The conditions that determine which part of the job stream should run can be very simple (for example, the predecessor ended with the SUCC or ABEND state) or can result in a very complex Boolean/Arithmetical condition. We will demonstrate many of these ways in the following sections. Figure 7-1 on page 405 shows the essential concepts of the generic branch job.
404
Figure 7-1 Purpose of the branch job
The functionality described in this chapter is not a native functionality of the product. It has been developed by IBM specialists during various customer Tivoli Workload Scheduler implementations. The design of the generic branch job leverages the open interface of Tivoli Workload Scheduler. The source code of the generic branch job is included in Appendix C, Generic branch job source code on page 593.
Chapter 7. Generic branch job
405
Note: Even if this chapter is quite long, the basic usage of the branch job is very easy. It takes a very short time to implement the simple branching based on predecessor job status (SUCC/ABEND). However, the more complex scenarios (such as pattern searching and numeric comparisons) require you to specify some input parameters to the branch job. We provide you with all the necessary information in the following sections.
7.2 Branch job functionality

This section briefly describes the functionality of the branch job. We will not go into deep detail here because all the possible usage types are described in 7.3, Sample scenarios on page 412. Note: We list the terminology and functionality at the beginning of this chapter because we use this terminology in the following sections. However, you may skip this section and go directly to 7.3, Sample scenarios on page 412, and then you can return here if you are unsure about the terminology.
7.2.1 Terminology
We have defined several terms in order to be able to describe the branch job functionality and behavior: Parent (sometimes referred also as evaluated job): The job whose status or other properties we want to evaluate. Condition: The condition that we are running against the parent job. The condition may be as simple as look at parent status or very complex. Good child: The closest successor to the branch job that is selected to run if the condition has been evaluated as TRUE. Bad child: The closest successor to the branch job that is selected to stop if the condition has been evaluated as FALSE. Branch: A sequence of jobs that are ordered using the FOLLOWS dependency. Run branch: The branch selected to run based on the condition result. The run branch starts with the good child if the condition has been evaluated as TRUE. If the condition has been evaluated as FALSE the run branch starts with the bad child.
406
Stop branch: The branch selected to stop based on the condition result. The stop branch starts with the bad child if the condition has been evaluated as TRUE. If the condition has been evaluated as FALSE, the stop branch starts with the good child. Input parameter: An argument that is passed to the specific branch job. For some parameters, the default value is used when the parameter is not specified. Branch job suffix: Distinguishes between the multiple occurrences of branch jobs within the same job stream. Note: The meaning of these terms can be confusing at first. The differences between these terms are further elaborated up on and described in Figure 7-2 on page 408 and Figure 7-3 on page 409. Figure 7-2 on page 408 shows descriptions for the following terms: Parent Good child and good branch Bad child and bad branch Where condition resides
407
Figure 7-2 Terms related to job stream definition
It is necessary to understand these terms while defining a job stream managed by one or more branch jobs. Figure 7-3 on page 409 extends our explanation with additional terms that are determined during the job stream run: Run branch Stop branch
408
Figure 7-3 Terms related to job stream run (concrete job stream instance)
Figure 7-3 demonstrates the difference between good/bad and run/stop terms. These terms are equal only in the case when the CONDITION=TRUE. If CONDITION=FALSE, then run branch=bad branch and stop branch=good branch. This is the concept of the branch job evaluating logic.
7.2.2 Branch job capabilities

When describing the generic branch job capabilities, we must break the branching process into two parts: Evaluation part: The branch job always takes its parent as the input. Then, based on the input parameters, it constructs one of the following sub-conditions: a. Checks to see if the parent ended with the SUCC state. b. Checks to see if the parent ended with the ABEND state.
409
c. Constructs a complex condition from one or more of the following sub-conditions: Get the parents joblog and check to see if it contains a row with a specified text pattern (the pattern is passed to the branch job as the input parameter). (optional) Another pattern must exist on the same row. (optional) A numeric value must exist on the same row. This numeric value is compared against a defined number using a defined arithmetical operator (the number and arithmetical operator are passed to the branch job as the input parameters).
These sub-conditions are joined together using Boolean AND/OR operators. Then the complex condition is evaluated at once (AND/OR operators are passed to each sub-condition as the input parameter). The result of the evaluation part (even if the condition is simple or complex) is either TRUE or FALSE. Action part: Based on the condition result, the branch job decides which branch should run and which branch should stop. Then it performs different actions on the run branch and on the stop branch. The possible actions on stop branch are as follows: CANCEL the whole stop branch: This cancels all the jobs within the stop branch. PAUSE the stop branch: Pauses the stop branch (holds the bad child). The jobs in the stop branch cannot run, because their predecessor is held. DO NOTHING: Just let the run branch run. RELEASE: If the first job of the run branch is held, it is then released.
The possible actions on the run branch are as follows:
In addition, there is a special action called SIGNAL. This action does nothing; it just recommends the confirmation of the branch job. This special version of the branch job must have set the flag Requires confirmation. Refer to 7.3.17, Signal action scenario on page 479 for more information about the SIGNAL branch job. Evaluation criteria and consecutive actions can be combined in any manner.
410
7.2.3 Branch job design advantages

This section highlights the main advantages of the generic branch job: There is only one branch job defined in the Tivoli Workload Scheduler database. The generic branch job is represented by just one job definition pointing to one shell script. The script does not take any command-line arguments that would be pointing to the branch jobs parent and children. The information about parent (predecessor) and children (successors) are evaluated automatically. (There is also another signal job definition that will be explained later.) You do not need to specify any input parameters if you use the most common branch job scenarios. You do not need to specify any parameters when evaluating the parent job result state (SUCC/ABEND). You just put the branch job into the job stream, link the FOLLOWS dependencies, and adjust the names of the children jobs in order to specify which one of them is the good child and which is the bad child. The branch job has the structured job log, which contains detailed information about the branch jobs environment, input parameters, evaluated condition, performed actions, and so on. By reading this job log, you can easily check what activities the branch job has performed. The branch job leverages the representation of Tivoli Workload Scheduler objects within the current Plan. That means that all objects within the Plan (such as jobs and job streams) are referenced using the keyword schedid. We ensure that all actions launched against the Plan objects point exactly to the unique object. This functionality is leveraged in all cases of the job stream occurrence in the current plan: Any occurrence of the job stream submitted without specifying the alias Any occurrence of the job stream submitted with the specified alias The generic branch job can run on both UNIX and Windows Master Domain Managers. The branch job is written in the shell script, so it runs natively on UNIX. On Windows systems, it is necessary to use a UNIX shell interpreter. The installation steps for both platforms are included at the end of this chapter. The generic branch job can run even if the job stream is defined on the workstation class. The branch job itself must be defined on the master.
411
7.3 Sample scenarios

This section demonstrates the possible purposes for which the generic branch job can be used. We start with the most simple scenarios and then continue to the more complex ones. The final scenarios will demonstrate the most generic possibilities, such as building the complex evaluation formulas and so on. Note: Even if the scenario names carry different branch job names, such as simple branch and complex branch, they all use only one job definition from the Tivoli Workload Scheduler database. This one job points to only one script and this script is called without any comman-line parameters. The special case is the signal scenario, which uses a variation of the branch job. It uses a signal job, which will be discussed in 7.3.17, Signal action scenario on page 479. Each scenario description has the following structure: Scenario introduction Scenario usage Sample job stream definition Final state of the job stream submitted into the plan Some scenarios contain a demonstration for the following cases: The case when the evaluated job met the evaluation criteria (for example, when the parent job ended with the SUCC state or the complex evaluation condition has been fulfilled). The case when the evaluated job did not meet the evaluation criteria (for example, when the parent job ended with the ABEND state, or the complex evaluation condition has not been fulfilled). Some scenarios contain only a demonstration of the state when the evaluating condition has been met. For such scenarios, we do not include the demonstration of the opposite state, because the negative state is easy to extrapolate from the original state. The joblog of the generic branch job The input parameters that must be passed to the branch job in order to perform branching properly Instructions for placing of the branch job into the job stream and adjusting the child job names, if necessary Link to the sample scenario name
412
Note: We provide the sample scenarios as the supplemental files with this book. You can use them in your Tivoli Workload Scheduler environment in order to get familiar with the generic branch job usage. We do not cover the installation steps of the sample scenarios in this section. For the complete description of the sample scenarios installation, refer to 7.7, Sample scenarios installation on page 530.
7.3.1 Scenarios based on condition type

In the following sections, we demonstrate the generic branch job scenarios based on the condition type. Then we will demonstrate the scenarios based on the action type. In order to be able to distinguish between the terms condition and action, we repeat the meaning of these two terms: Condition: Determines what criteria should be used for determining the run branch (what shall continue) and the stop branch (what shall stop). Action: Determines what should be done on the run branch and what should be done on the stop branch. There are two types of actions that can be performed on the stop branch and two types of actions that can be performed on the run branch. In addition, there is one special Signaling action. The following sections include a description of the scenarios based on the condition type. The scenarios based on the action type will be discussed in 7.3.14, Scenarios based on action type on page 466.
7.3.2 Simple branch

This scenario describes the most common and also the most simple branch job.
Simple branch usage

Simple branching is used in cases where we need to evaluate the status of the particular job. Then, based on the job status, we want to decide which branch should run. If the job ends with a SUCC status, we want to continue in the good branch. If the job ABENDs, we want to continue in the bad branch.
Simple branch demonstration: SUCC

This scenario demonstrates the behavior of the generic branch job if the parent job ended with the SUCC state.
413
Figure 7-4 shows the job stream definition.
Figure 7-4 Simple branch (SUCC) definition
Figure 7-5 shows the final state of the job stream that ran within the current plan.
Figure 7-5 Simple branch (SUCC) final status
In this case, the parent job ended with the SUCC state. As you can see, the bad child has been cancelled while the good child has been able to run. Figure 7-6 on page 415 contains the commented output of the generic branch job that describes the whole evaluation process in detail.
414
Figure 7-6 Simple branch (SUCC) commented joblog
As you can see, the joblog is divided into logical parts. You can easily check the branching process by looking into the generic branch job joblog.
Simple branch demonstration: the ABEND example

This example demonstrates the simple branch scenario in the case where the parent job abended. Figure 7-7 on page 416 shows the job stream definition.
415
Figure 7-7 Simple branch (ABEND) definition
Figure 7-8 demonstrates how this job has run in the plan.
Figure 7-8 Simple branch (ABEND) final status
Note: We just again emphasize the fact that the evaluated job (in our terminology the parent job) must have the Recovery option set to Continue. Otherwise the ABENDed job would not release the branch job from the FOLLOWS dependency and the whole job stream would end in STUCK state. This comment is valid for all parent jobs, for which we evaluate the result state, because we count on that any of them may abend.
416
Figure 7-9 shows the joblog of the instance of the generic branch job.
Figure 7-9 Simple branch (ABEND) joblog
Necessary input parameters

As already mentioned above, branching based on evaluating the status of the parent job is the most common usage of the generic branch job. That is why this branching type does not need any input parameters to be defined for the branch job.
417
Placing the branch job into the job stream

Put the generic branch job into the job stream just after the parent job and rename the good child with the G_ prefix and the bad child with the B_ prefix. Also, follow the best practice and rename the branch job so that it has a suffix constructed from the underscore character and numeric value. A typical name of the first branch job within a job stream is BRANCH_1.
Job stream name within demo scenarios

The generic branch job described in this chapter is available as a supplemental file that is available with this book. Together with the branch job source code, we provide you with the sample scenarios that are demonstrated in this chapter. If you follow the instructions described in 7.7, Sample scenarios installation on page 530, you will also install the sample scenarios. The name of the job stream representing the SUCC version of this sample scenario is GBJ_SIMPLE_SUCC. The name of the job stream representing the ABEND version of this sample scenario is GBJ_SIMPLE_ABEND. Note: All the sample scenarios are named with the GBJ_ prefix. This allows you to create dedicated lists in your Job Scheduling Console.
7.3.3 Long branch

This section describes another type of the simple branch scenario.
Long branch usage

Long branch is just the recursive demonstration of the simple branch. The main meaning of this scenario is the demonstration of the fact that the generic branch job is able to cancel ALL the jobs in the stop branch, even if there is a whole tree of jobs to cancel. This functionality is necessary because of the following Tivoli Workload Scheduler design feature: If any job is cancelled, all the jobs successors are released from the FOLLOWS dependency, that is, jobs that are dependent on the cancelled job, will start immediately. This may be unwanted behavior in many cases. That is why the generic branch job cancels the first stop job and all of its successors.
418
Note: From a programming point of view, the generic branch job uses recursive function calls to go through all the successors of the first stop child of the generic branch job.
Long branch demonstration - SUCC example

Figure 7-10 shows the job stream containing the complex structure of successors either in the good branch or the bad branch.
Figure 7-10 Long branch (SUCC) definition
419
Figure 7-11 demonstrates how the job stream has run if the evaluated job succeeded.
Figure 7-11 Long branch(SUCC) final status
Example 7-1 contains the output of the joblog of the generic branch job instance.
Example 7-1 Long branch (SUCC) joblog
============ START of branch job BRANCH_1 ========== ========================================================== ============= Job environment ============= MASTER_PLATFORM=UNIX STREAM_NAME=GBJ_LONG_SUCC STREAM_CPU=SYDNEY BRANCH_JOB_NAME=BRANCH_1 PARENT=IMPORTANT_JOB_SUCC ========================================================== ============= Input parameters ============= CONDITION_SWITCH=PARENT_SUCCESS ACTION_SWITCH=CANCEL
420
========================================================== ============= MAIN DECISION MAKING ============= Evaluation dependent on PARENT_SUCCESS TRUE: Searched for SUCC parent. Status of PARENT JOB(IMPORTANT_JOB_SUCC) is SUCC. ========================================================== ============= Action on STOP Branch ============= Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAEC3.B_DO_THE_BAD_THING %cj SYDNEY#0AAAAAAAAAAAAEC3.B_DO_THE_BAD_THING;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_LONG_SUCC[(2154 12/16/07),(0AAAAAAAAAAAAEC3)].B_DO_THE_BAD_THING Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAEC3.SOME_BAD_JOB %cj SYDNEY#0AAAAAAAAAAAAEC3.SOME_BAD_JOB;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_LONG_SUCC[(2154 12/16/07),(0AAAAAAAAAAAAEC3)].SOME_BAD_JOB Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAEC3.ABEND_JOB %cj SYDNEY#0AAAAAAAAAAAAEC3.ABEND_JOB;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_LONG_SUCC[(2154 12/16/07),(0AAAAAAAAAAAAEC3)].ABEND_JOB Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAEC3.ANOTHER_JOB_IN_BAD_BRANCH %cj SYDNEY#0AAAAAAAAAAAAEC3.ANOTHER_JOB_IN_BAD_BRANCH;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_LONG_SUCC[(2154 12/16/07),(0AAAAAAAAAAAAEC3)].ANOTHER_JOB_IN_BAD_BRANCH ========================================================== ============= Action on RUN Branch ============= Performing action RELEASE on job SYDNEY#0AAAAAAAAAAAAEC3.G_DO_THE_GOOD_THING Releasing of job SYDNEY#0AAAAAAAAAAAAEC3.G_DO_THE_GOOD_THING is NOT NECESSARY, because priority=10 ========================================================== ============= Statistics of branch job BRANCH_1 ============= TRUE: Searched for SUCC parent. Status of PARENT JOB(IMPORTANT_JOB_SUCC) is SUCC. For action CANCEL - RUN_BRANCH=G_DO_THE_GOOD_THING and STOP_BRANCH=B_DO_THE_BAD_THING BRANCH selected to STOP: B_DO_THE_BAD_THING BRANCH selected to CONTINUE: G_DO_THE_GOOD_THING CANCELLED_JOBS: B_DO_THE_BAD_THING, SOME_BAD_JOB, ABEND_JOB, ANOTHER_JOB_IN_BAD_BRANCH PAUSED_JOB: RELEASED_JOB: ============ END of branch job BRANCH_1 ==========
421
Note: In this section, we will provide the branch joblogs in the text format instead of screen captures.
Long branch demonstration - ABEND example

Figure 7-12 demonstrates how the job stream has run if the evaluated job abended.
Figure 7-12 Long branch(ABEND) final status
Note: The evaluated job (generic branch jobs parent) must have the recovery option set to Continue in order to be able to release the successors from the FOLLOWS dependency. This parameter can be set only within the job definition, not in the job stream definition. Example 7-2 on page 423 contains the output of the joblog of the generic branch job instance.
422
Example 7-2 Long branch (ABEND) joblog
============ START of branch job BRANCH_1 ========== ========================================================== ============= Job environment ============= MASTER_PLATFORM=UNIX STREAM_NAME=GBJ_LONG_ABEND STREAM_CPU=SYDNEY BRANCH_JOB_NAME=BRANCH_1 PARENT=IMPORTANT_JOB_ABEND ========================================================== ============= Input parameters ============= CONDITION_SWITCH=PARENT_SUCCESS ACTION_SWITCH=CANCEL ========================================================== ============= MAIN DECISION MAKING ============= Evaluation dependent on PARENT_SUCCESS FALSE: Searched for SUCC parent. Status of PARENT JOB(IMPORTANT_JOB_ABEND) is ABEND. ========================================================== ============= Action on STOP Branch ============= Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAEC4.G_DO_THE_GOOD_THING %cj SYDNEY#0AAAAAAAAAAAAEC4.G_DO_THE_GOOD_THING;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_LONG_ABEND[(2159 12/16/07),(0AAAAAAAAAAAAEC4)].G_DO_THE_GOOD_THING Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAEC4.SOME_GOOD_1 %cj SYDNEY#0AAAAAAAAAAAAEC4.SOME_GOOD_1;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_LONG_ABEND[(2159 12/16/07),(0AAAAAAAAAAAAEC4)].SOME_GOOD_1 Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAEC4.SOME_GOOD_2 %cj SYDNEY#0AAAAAAAAAAAAEC4.SOME_GOOD_2;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_LONG_ABEND[(2159 12/16/07),(0AAAAAAAAAAAAEC4)].SOME_GOOD_2 ========================================================== ============= Action on RUN Branch ============= Performing action RELEASE on job SYDNEY#0AAAAAAAAAAAAEC4.B_DO_THE_BAD_THING Releasing of job SYDNEY#0AAAAAAAAAAAAEC4.B_DO_THE_BAD_THING is NOT NECESSARY, because priority=10 ========================================================== ============= Statistics of branch job BRANCH_1 ============= FALSE: Searched for SUCC parent. Status of PARENT JOB(IMPORTANT_JOB_ABEND) is ABEND.
423
For action CANCEL - RUN_BRANCH=B_DO_THE_BAD_THING and STOP_BRANCH=G_DO_THE_GOOD_THING BRANCH selected to STOP: G_DO_THE_GOOD_THING BRANCH selected to CONTINUE: B_DO_THE_BAD_THING CANCELLED_JOBS: G_DO_THE_GOOD_THING, SOME_GOOD_1, SOME_GOOD_2 PAUSED_JOB: RELEASED_JOB: ============ END of branch job BRANCH_1 ==========

As mentioned above, long branching is just the common case of simple branching. This branching type does not need any input parameters to be defined for the branch job.

Job stream name within the demo scenarios

The generic branch job described in this chapter is available as a supplemental file that is available with this book. Together with the branch job source code, we provide you with the sample scenarios that are demonstrated in this chapter. If you follow the instructions described in 7.7, Sample scenarios installation on page 530, you will also install the sample scenarios. The name of the job stream representing the SUCC version of this sample scenario is GBJ_LONG_SUCC. The name of the job stream representing the ABEND version of this sample scenario is GBJ_LONG_ABEND. Note: All the sample scenarios are named with the GBJ_ prefix. This allows you to create dedicated lists in your Job Scheduling Console.
424
7.3.4 Multiple branch

This scenario demonstrates the possibility of having multiple different branch jobs within one single job stream.
Usage
The purpose of having more branch jobs in one job stream is simple: We need to perform branching multiple times. You can see an example of a job stream managed by multiple branch jobs in Figure 7-13.
Figure 7-13 Multiple branch jobs within one job stream
425

The necessity of providing input parameters depends on the particular branch jobs used. Jobs from the following scenarios do not need input parameters: Simple branch (described in 7.3.2, Simple branch on page 413) Long branch (described in 7.3.3, Long branch on page 418) Jobs from the following scenarios need input parameters: Pattern branch (Described in 7.3.7, Complex branch - Pattern on page 432) Pattern within pattern branch (Described in 7.3.9, Complex branch - Pattern within pattern row on page 442) Numeric value comparison branch (Described in 7.3.11, Complex branch Numeric value comparison on page 452) Complex branch (Described in 7.3.12, Complex scenario - multiple conditions on page 458) Pausing branch (Described in 7.3.15, Pause/Release actions scenario on page 467) Signaling branch (Described in 7.3.17, Signal action scenario on page 479) Refer to the related scenarios to determine which input parameters are required for each branch job within the job stream.
Placing the branch jobs into the job stream

For each branch job, it is necessary to put the generic branch job into the job stream just after the parent job and rename the good child with the G_ prefix and the bad child with the B_ prefix. Of course, it is necessary to distinguish the particular branch jobs by branch suffix, which should be composed of an underscore character and a number. Note: The best practice is to create the branch suffix using numbers in ascending order. That means that multiple branch jobs within one job stream should be named BRANCH_1, BRANCH_2, and so on.
Job stream name within the demo scenarios

The generic branch job described in this chapter is available as a supplemental file that is available with this book. Together with the branch job source code, we provide you with the sample scenarios that are demonstrated in this chapter.
426
If you follow the instructions described in 7.7, Sample scenarios installation on page 530, you will also be able to install the sample scenarios. The name of the job stream representing this sample scenario is GBJ_MULTIPLE. Note: All the sample scenarios are named with the GBJ_ prefix. This allows you to create dedicated lists in your Job Scheduling Console.
7.3.5 Parent abend

This section describes the inverted case of the simple branch scenario. This scenario is the first described scenario that takes input parameters.
Parent abend usage

This scenario describes the following functional requirements: Get parent job status. If the parent job status is SUCC, we consider this to be BAD. If the parent job status is ABEND, we consider this to be GOOD. We provide only one demonstration for this scenario: what is going to happen when the parent ends with the SUCC state.
Parent abend demonstration - SUCC example

Figure 7-14 on page 428 shows the job stream demonstrating the PARENT_ABEND functionality. At first sight, the job stream looks like the simple branch. The only difference is that the parameter CONDITION_SWITCH=PARENT_ABEND has been passed to the branch job.
427
Figure 7-14 Parent abend (SUCC) definition
Figure 7-15 demonstrates how the job stream has run if the evaluated job succeeded.
Figure 7-15 Parent abend (SUCC) final status
As you can see, the good branch has been cancelled when the parent job ended with the SUCC state. This reverted functionality of the simple branch has been invoked by specifying the input parameter CONDITION_SWITCH=PARENT_ABEND. Example 7-3 on page 429 contains the output of the joblog of the generic branch job instance.
428
Example 7-3 Parent abend (SUCC) joblog
============ START of branch job BRANCH_1 ========== ========================================================== ============= Job environment ============= MASTER_PLATFORM=UNIX STREAM_NAME=GBJ_PARENT_ABEND STREAM_CPU=SYDNEY BRANCH_JOB_NAME=BRANCH_1 PARENT=IMPORTANT_JOB_SUCC ========================================================== ============= Input parameters ============= CONDITION_SWITCH=PARENT_ABEND ACTION_SWITCH=CANCEL ========================================================== ============= MAIN DECISION MAKING ============= Evaluation dependent on PARENT_ABEND FALSE: Searched for ABEND parent. Status of PARENT JOB(IMPORTANT_JOB_SUCC) is SUCC. ========================================================== ============= Action on STOP Branch ============= Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAEDA.G_DO_THE_GOOD_THING %cj SYDNEY#0AAAAAAAAAAAAEDA.G_DO_THE_GOOD_THING;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_PARENT_ABEND[(2314 12/16/07),(0AAAAAAAAAAAAEDA)].G_DO_THE_GOOD_THING ========================================================== ============= Action on RUN Branch ============= Performing action RELEASE on job SYDNEY#0AAAAAAAAAAAAEDA.B_DO_THE_BAD_THING Releasing of job SYDNEY#0AAAAAAAAAAAAEDA.B_DO_THE_BAD_THING is NOT NECESSARY, because priority=10 ========================================================== ============= Statistics of branch job BRANCH_1 ============= FALSE: Searched for ABEND parent. Status of PARENT JOB(IMPORTANT_JOB_SUCC) is SUCC. For action CANCEL - RUN_BRANCH=B_DO_THE_BAD_THING and STOP_BRANCH=G_DO_THE_GOOD_THING BRANCH selected to STOP: G_DO_THE_GOOD_THING BRANCH selected to CONTINUE: B_DO_THE_BAD_THING CANCELLED_JOBS: G_DO_THE_GOOD_THING PAUSED_JOB: RELEASED_JOB: ============ END of branch job BRANCH_1 ==========
429

Table 7-1 contains the necessary input parameters for the negative branch scenario.
Table 7-1 Input parameters for the negative branch job scenario Parameter name CONDITION_SWITCH Parameter value PARENT_ABEND
Example 7-4 demonstrates how the parameter definition looks. The text is entered into the Comments field of the job stream definition.
Example 7-4 Parent abend scenario parameters definition
BRANCH_1-BEGIN CONDITION_SWITCH=PARENT_ABEND BRANCH_1-END Note: The instructions related to the branch job parameters are described in 7.5, Working with the branch job parameters on page 509.

Put the generic branch job into the job stream just after the parent job and rename the good child with the G_ prefix and the bad child with the B_ prefix. Also, follow the best practice and rename the branch job so that it has a suffix constructed from the underscore character and numeric value. A typical name of the first branch job within a job stream is BRANCH_1. If you follow the instructions described in 7.7, Sample scenarios installation on page 530, you will also install the sample scenarios.

The generic branch job described in this chapter is available as a supplemental file that is available with this book. Together with the branch job source code, we provide you with the sample scenarios that are demonstrated in this chapter. If you follow the instructions described in 7.7, Sample scenarios installation on page 530, you will also install the sample scenarios. The name of the job stream representing this sample scenario is GBJ_PARENT_ABEND.
430
Note: All the sample scenarios are named with the GBJ_ prefix. This allows you to create dedicated lists in your Job Scheduling Console.
7.3.6 Complex branch scenarios

The following sections describe the complex usage scenarios of the generic branch job. In the previous sections, we described the scenarios that were based on the evaluation of the status of the parent job. Complex branch job scenarios are based on the evaluation of the joblog of the parent job. We have already briefly listed the complex conditions in 7.2.1, Terminology on page 406. In the following sections, we provide you with scenarios that demonstrate the flexibility of the generic branch job. A complex condition can be constructed of multiple, atomic sub-conditions. An example of a complex condition may look as follows: Sub-condition 1 Search for the text patterns within the parents joblog (the text pattern is supplied as a parameter). In the row where the pattern has been found, isolate the numeric value. Compare this numeric value with a specified number. For this comparison, use the specified arithmetical operator (the number and operator are supplied as parameters). If the arithmetical comparison has been successful, it will return TRUE. For example, search for the row that contains pattern Disk free. If you find this row, search for a number within this row. If this number is greater than 90, it will return TRUE. Sub-condition 2 Search for another text pattern within the parents joblog (the text pattern is supplied as a parameter). If the pattern is found, negate the result and return FALSE (for example, we want to return the FALSE result if the parents joblog contains the pattern Error). Connect the first and second sub-condition results with a Boolean operator (the Boolean operator is supplied as a parameter, and the possible values are AND/OR).
431
Evaluate the final result of the whole condition (TRUE/FALSE). As you can see, the defined condition can be very flexible and can cover many typical situations. We show several complex branch scenarios in the following sections. We demonstrate how to: Search for a specific text pattern within the parents joblog. Search for a specific text pattern within the parents joblog. If the pattern has been found, search for an additional text pattern within the same row. Search for a specific text pattern within the parents joblog. If the pattern has been found, search for a numeric value in within the same row. Then the value (if found) will be compared against the supplied number using the supplied arithmetical operator. Join several conditions into one using the Boolean AND/OR operators.
7.3.7 Complex branch - Pattern

This section describes the complex branch scenario where we are searching for a specified text pattern within the parents joblog. Actually, the case where we just search for one text pattern within the parents joblog is the most simple case of the complex condition.
Pattern scenario usage

This scenario is used if we want to find a specific text in the joblog of the important job within the job stream. The searched text can be any string, such as ended successfully, mounted ALL tape drives, and so on. In general, it should represent the positive message included in the parents joblog. Note: We say that pattern search should demonstrate the positive message from parents joblog. In some cases, we want to implement reversed logic. For example, the patterns Error or Unsuccessfully, Not Enough Space, and so on, represent negative messages from the parents joblog. The generic branch job is also prepared for this scenario. We demonstrate it in 7.3.8, Complex branch - negated pattern on page 437.
432
The pattern branch is designed to provide the following functionality: If the text pattern is found, then the CONDITION=TRUE. Otherwise the CONDITION=FALSE.
Pattern scenario demonstration

Figure 7-16 shows the job stream definition for the pattern branch scenario. At first sight the job stream looks like the simple branch scenario. The only difference is that some additional parameters are defined. In this case, the following parameters are defined: CONDITION_SWITCH=COMPLEX PATTERN_1=completed successfully
Figure 7-16 Pattern scenario - definition
433
Figure 7-17 demonstrates how the job stream has run when the searched pattern has been found.
Figure 7-17 Pattern scenario final status
Example 7-5 Pattern scenario joblog
============ START of branch job BRANCH_1 ========== ========================================================== ============= Job environment ============= MASTER_PLATFORM=UNIX STREAM_NAME=GBJ_PATTERN STREAM_CPU=SYDNEY BRANCH_JOB_NAME=BRANCH_1 PARENT=PATTERN_JOB ========================================================== ============= Input parameters ============= CONDITION_SWITCH=COMPLEX ACTION_SWITCH=CANCEL CONDITION_COUNT=1 PATTERN[1]=completed successfully IS_CASE_SENSITIVE[1]=YES IS_REGULAR_EXPRESSION[1]=NO
434
NEGATE_CONDITION_RESULT[1]=NO ========================================================== ============= MAIN DECISION MAKING ============= COMPLEX condition evaluation ----------ATOMIC CONDITION 1-----------Searching for "completed successfully" in JOBLOG of PATTERN_JOB Pattern FOUND, performing further tests. No additional value defined for specified pattern. Condition evaluated as TRUE. ATOMIC CONDITION RESULT [1]= TRUE -------------------------------------------- COMPLEX CONDITION ---------[ TRUE ] CONDITION_RESULT=TRUE TRUE: The result of complex condition is TRUE. ========================================================== ============= Action on STOP Branch ============= Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAED4.B_DO_THE_BAD_THING %cj SYDNEY#0AAAAAAAAAAAAED4.B_DO_THE_BAD_THING;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_PATTERN[(1733 12/17/07),(0AAAAAAAAAAAAED4)].B_DO_THE_BAD_THING ========================================================== ============= Action on RUN Branch ============= Performing action RELEASE on job SYDNEY#0AAAAAAAAAAAAED4.G_DO_THE_GOOD_THING Releasing of job SYDNEY#0AAAAAAAAAAAAED4.G_DO_THE_GOOD_THING is NOT NECESSARY, because priority=10 ========================================================== ============= Statistics of branch job BRANCH_1 ============= TRUE: The result of complex condition is TRUE. For action CANCEL - RUN_BRANCH=G_DO_THE_GOOD_THING and STOP_BRANCH=B_DO_THE_BAD_THING BRANCH selected to STOP: B_DO_THE_BAD_THING BRANCH selected to CONTINUE: G_DO_THE_GOOD_THING CANCELLED_JOBS: B_DO_THE_BAD_THING PAUSED_JOB: RELEASED_JOB: ============ END of branch job BRANCH_1 ==========
435

Table 7-2 contains the necessary input parameters for the negated branch scenario.
Table 7-2 Input parameters for the pattern job scenario Parameter name CONDITION_SWITCH PATTERN_1 Parameter value COMPLEX Completed successfully
Example 7-6 Pattern scenario parameters definition
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=completed successfully BRANCH_1-END
Note: The instructions related to the branch job parameters are described in 7.5, Working with the branch job parameters on page 509.


The generic branch job described in this chapter is available as a supplemental file that is available with this book. Together with the branch job source code, we provide you with the sample scenarios that are demonstrated in this chapter. If you follow the instructions described in 7.7, Sample scenarios installation on page 530, you will also install the sample scenarios. The name of the job stream representing this sample scenario is GBJ_PATTERN.
436
7.3.8 Complex branch - negated pattern

In this section, we demonstrate the inverted case of the pattern branch scenario.
Negated Pattern scenario usage

We have demonstrated the pattern branch scenario in 7.3.7, Complex branch Pattern on page 432. We mention that finding the specified pattern sometimes does not result in the positive message. For example, the occurrence of the pattern Error within the parents joblog usually results in the negative message. In this case, the generic branch job allows you to negate each defined sub-condition of the complex condition. In this section, we demonstrate the scenario where finding the searched pattern will result into CONDITION=FALSE. Not finding the pattern will result in CONDITION=TRUE.
Negated pattern scenario demonstration

Figure 7-18 on page 438 shows the job stream definition for the pattern branch scenario. In this case, the following parameters are defined: CONDITION_SWITCH=COMPLEX PATTERN_1=Error NEGATE CONDITION_RESULT_1=YES
437
Figure 7-18 Negated Pattern scenario definition
Figure 7-19 on page 439 demonstrates how the job stream has run in the case where the search pattern has been found.
438
Figure 7-19 Negated Pattern scenario final status
Example 7-7 Negated Pattern joblog
============ START of branch job BRANCH_1 ========== ========================================================== ============= Job environment ============= MASTER_PLATFORM=UNIX STREAM_NAME=GBJ_PATTERN_NEG STREAM_CPU=SYDNEY BRANCH_JOB_NAME=BRANCH_1 PARENT=PATTERN_JOB_ERROR ========================================================== ============= Input parameters ============= CONDITION_SWITCH=COMPLEX ACTION_SWITCH=CANCEL CONDITION_COUNT=1 PATTERN[1]=Error IS_CASE_SENSITIVE[1]=YES IS_REGULAR_EXPRESSION[1]=NO NEGATE_CONDITION_RESULT[1]=YES
439
========================================================== ============= MAIN DECISION MAKING ============= COMPLEX condition evaluation ----------ATOMIC CONDITION 1-----------Searching for "Error" in JOBLOG of PATTERN_JOB_ERROR Pattern FOUND, performing further tests. No additional value defined for specified pattern. Condition evaluated as TRUE. ==NEGATED== ATOMIC CONDITION RESULT [1]= FALSE -------------------------------------------- COMPLEX CONDITION ---------[ FALSE ] CONDITION_RESULT=FALSE FALSE: The result of complex condition is FALSE. ========================================================== ============= Action on STOP Branch ============= Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAED3.G_DO_THE_GOOD_THING %cj SYDNEY#0AAAAAAAAAAAAED3.G_DO_THE_GOOD_THING;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_PATTERN_NEG[(1730 12/17/07),(0AAAAAAAAAAAAED3)].G_DO_THE_GOOD_THING ========================================================== ============= Action on RUN Branch ============= Performing action RELEASE on job SYDNEY#0AAAAAAAAAAAAED3.B_DO_THE_BAD_THING Releasing of job SYDNEY#0AAAAAAAAAAAAED3.B_DO_THE_BAD_THING is NOT NECESSARY, because priority=10 ========================================================== ============= Statistics of branch job BRANCH_1 ============= FALSE: The result of complex condition is FALSE. For action CANCEL - RUN_BRANCH=B_DO_THE_BAD_THING and STOP_BRANCH=G_DO_THE_GOOD_THING BRANCH selected to STOP: G_DO_THE_GOOD_THING BRANCH selected to CONTINUE: B_DO_THE_BAD_THING CANCELLED_JOBS: G_DO_THE_GOOD_THING PAUSED_JOB: RELEASED_JOB: ============ END of branch job BRANCH_1 ==========

Table 7-3 on page 441 contains the necessary input parameters for the negated branch scenario.
440
Table 7-3 Input parameters for the pattern job scenario Parameter name CONDITION_SWITCH PATTERN_1 NEGATE_CONDITION_RESULT_1 Parameter value COMPLEX Error YES
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=Error NEGATE_CONDITION_1=YES BRANCH_1-END


The generic branch job described in this chapter is available as a supplemental file that is available with this book. Together with the branch job source code, we provide you with the sample scenarios that are demonstrated in this chapter. If you follow the instructions described in 7.7, Sample scenarios installation on page 530, you can also install the sample scenarios. The name of the job stream representing this sample scenario is GBJ_PATTERN_NEG.
441
7.3.9 Complex branch - Pattern within pattern row

This scenario demonstrates the more complex functionality of the pattern searching.
Pattern within pattern row scenario usage

This scenario extends the functionality of the pattern scenario described in 7.3.7, Complex branch - Pattern on page 432. The purpose of this scenario is as follows: 1. Get the parents joblog. 2. Within this joblog, identify a row containing a specific pattern. 3. If such a row has been found, try to find another pattern within this row. 4. If you find the second pattern, it returns TRUE. The typical usage scenario may look like Example 7-9, where we see an extract from the parents joblog.
Example 7-9 Example of parents joblog - 1
About to stop component XYZ... Sending STOP signal to component XYZ: SUCCESS Stopping component XYZ: SUCCESS As you can see, a simple search for the text pattern SUCCESS would not show that the component had really stopped. There are multiple occurrences of pattern SUCCESS and by using the simple pattern search we would not determine the correct result. For example, the parents joblog might also look different, as you can see in Example 7-10.
Example 7-10 Example of parents joblog - 1
About to stop component XYZ... Sending STOP signal to component XYZ: SUCCESS Stopping component XYZ: FAILED If we used just the simple pattern search, the result would be CONDITION=TRUE because we would in fact find the pattern SUCCESS. But in this case, we would not evaluate the parents joblog correctly.
442
In order to be able to correctly evaluate the parents joblog, we must use the pattern within pattern row scenario in the following way: Search for the pattern Stopping component. If such a row is found, search for the pattern SUCCESS. If both searches were successful, they should return TRUE. We demonstrate this scenario in Pattern within pattern row scenario.
Pattern within pattern row scenario

Figure 7-20 shows the definition for the pattern branch scenario.
Figure 7-20 Pattern within pattern row definition
443
Figure 7-21 demonstrates how the job stream has run if only part of the condition has been fulfilled. The first pattern text is found, but then the second pattern is not present in the pattern row. Therefore, the whole condition is evaluated as CONDITION=FALSE.
Figure 7-21 Pattern within pattern row final status
Example 7-11 Pattern within pattern row branch joblog
============ START of branch job BRANCH_1 ========== ========================================================== ============= Job environment ============= MASTER_PLATFORM=UNIX STREAM_NAME=GBJ_PATTERN_PATT STREAM_CPU=SYDNEY BRANCH_JOB_NAME=BRANCH_1 PARENT=PATTERN_PATTERN_JOB ========================================================== ============= Input parameters =============
444
CONDITION_SWITCH=COMPLEX ACTION_SWITCH=CANCEL CONDITION_COUNT=1 PATTERN[1]=Stopping component VALUE[1]=SUCCESS IS_CASE_SENSITIVE[1]=YES IS_REGULAR_EXPRESSION[1]=NO NEGATE_CONDITION_RESULT[1]=NO ========================================================== ============= MAIN DECISION MAKING ============= COMPLEX condition evaluation ----------ATOMIC CONDITION 1-----------Searching for "Stopping component" in JOBLOG of PATTERN_PATTERN_JOB Pattern FOUND, performing further tests. Searching for STRING=SUCCESS within the row "Stopping component XYZ: FAILED". String "SUCCESS" NOT found within the row "Stopping component XYZ: FAILED". ATOMIC CONDITION RESULT [1]= FALSE -------------------------------------------- COMPLEX CONDITION ---------[ FALSE ] CONDITION_RESULT=FALSE FALSE: The result of complex condition is FALSE. ========================================================== ============= Action on STOP Branch ============= Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAED2.G_DO_THE_GOOD_THING %cj SYDNEY#0AAAAAAAAAAAAED2.G_DO_THE_GOOD_THING;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_PATTERN_PATT[(1634 12/17/07),(0AAAAAAAAAAAAED2)].G_DO_THE_GOOD_THING ========================================================== ============= Action on RUN Branch ============= Performing action RELEASE on job SYDNEY#0AAAAAAAAAAAAED2.B_DO_THE_BAD_THING Releasing of job SYDNEY#0AAAAAAAAAAAAED2.B_DO_THE_BAD_THING is NOT NECESSARY, because priority=10 ========================================================== ============= Statistics of branch job BRANCH_1 ============= FALSE: The result of complex condition is FALSE. For action CANCEL - RUN_BRANCH=B_DO_THE_BAD_THING and STOP_BRANCH=G_DO_THE_GOOD_THING BRANCH selected to STOP: G_DO_THE_GOOD_THING BRANCH selected to CONTINUE: B_DO_THE_BAD_THING CANCELLED_JOBS: G_DO_THE_GOOD_THING
445
PAUSED_JOB: RELEASED_JOB: ============ END of branch job BRANCH_1 ==========

Table 7-4 contains the necessary input parameters for the pattern within pattern row scenario.
Table 7-4 Input parameters for the pattern within pattern row scenario Parameter name CONDITION_SWITCH PATTERN_1 VALUE_1 Parameter value COMPLEX Stopping component SUCCESS
Example 7-12 shows how the parameter definition looks. The text is entered into the Comments field of the job stream definition.
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=Stopping component VALUE_1=SUCCESS BRANCH_1-END

446

The generic branch job described in this chapter is available as a supplemental file that is available with this book. Together with the branch job source code, we provide you with the sample scenarios that are demonstrated in this chapter. If you follow the instructions described in 7.7, Sample scenarios installation on page 530, you can also install the sample scenarios. The name of the job stream representing this sample scenario is GBJ_PAT_PAT. Note: All the sample scenarios are named with the GBJ_ prefix. This allows you to create dedicated lists in your Job Scheduling Console.
7.3.10 Pattern within pattern row - negated

This scenario briefly describes the reversed case of the previous pattern within pattern row scenario.
Negated pattern within pattern row scenario usage

The purpose of this scenario is simple: we have already demonstrated that you can negate the result of a simple pattern search. We have demonstrated this functionality in 7.3.8, Complex branch - negated pattern on page 437. Now we want just to emphasize the fact that you can use the negated approach for any complex scenario. It is not important if you are just performing a simple pattern search (such as find the occurrence of ERROR in the parents joblog) or a complex condition. In any case of the complex condition, you may use the approach that negates the result. You decide how you wish to parse the parents joblog. Based on your understanding of the joblog content, you decide whether the output of particular rows contains the either the positive or negative message. Based on this knowledge, you decide whether to negate the particular sub-condition result or leave it as it is.
Negated pattern within pattern row scenario

In the following section, we demonstrate the usage of the negated pattern within pattern row scenario.
447
The evaluation logic is as follows: 1. Search for the pattern row. 2. Try to find the main identifier, such as Backup on Primary device. 3. If such a row is found, try to find the negative message ERROR within this row. 4. Negate the result. This approach would cover the scenario where we use outputs like SUCCESS, OK, and COMPLETED as positive messages and outputs like FAILED and ERROR as negative messages. Figure 7-22 shows the definition for the pattern branch scenario.
Figure 7-22 Pattern within pattern row negated definition
Figure 7-23 on page 449 demonstrates how the job stream has run when both searched pattern have been found within the same row. Because we have negated the result, the final result has been evaluated as CONDITION=FALSE.
448
Figure 7-23 Pattern within pattern row negated final status
Example 7-11 on page 444 contains the output of the joblog of the generic branch job instance.
Example 7-13 Pattern within pattern row branch joblog
============ START of branch job BRANCH_1 ========== ========================================================== ============= Job environment ============= MASTER_PLATFORM=UNIX STREAM_NAME=GBJ_PAT_PAT_NEG STREAM_CPU=SYDNEY BRANCH_JOB_NAME=BRANCH_1 PARENT=PATTERN_PATTERN_ERROR_JOB ========================================================== ============= Input parameters ============= CONDITION_SWITCH=COMPLEX ACTION_SWITCH=CANCEL CONDITION_COUNT=1 PATTERN[1]=Backup of Primary device VALUE[1]=ERROR
449
IS_CASE_SENSITIVE[1]=YES IS_REGULAR_EXPRESSION[1]=NO NEGATE_CONDITION_RESULT[1]=YES ========================================================== ============= MAIN DECISION MAKING ============= COMPLEX condition evaluation ----------ATOMIC CONDITION 1-----------Searching for "Backup of Primary device" in JOBLOG of PATTERN_PATTERN_ERROR_JOB Pattern FOUND, performing further tests. Searching for STRING=ERROR within the row "Backup of Primary device: ERROR". String "ERROR" found within the row "Backup of Primary device: ERROR". ==NEGATED== ATOMIC CONDITION RESULT [1]= FALSE -------------------------------------------- COMPLEX CONDITION ---------[ FALSE ] CONDITION_RESULT=FALSE FALSE: The result of complex condition is FALSE. ========================================================== ============= Action on STOP Branch ============= Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAEEA.G_DO_THE_GOOD_THING %cj SYDNEY#0AAAAAAAAAAAAEEA.G_DO_THE_GOOD_THING;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_PAT_PAT_NEG[(1941 12/17/07),(0AAAAAAAAAAAAEEA)].G_DO_THE_GOOD_THING ========================================================== ============= Action on RUN Branch ============= Performing action RELEASE on job SYDNEY#0AAAAAAAAAAAAEEA.B_DO_THE_BAD_THING Releasing of job SYDNEY#0AAAAAAAAAAAAEEA.B_DO_THE_BAD_THING is NOT NECESSARY, because priority=10 ========================================================== ============= Statistics of branch job BRANCH_1 ============= FALSE: The result of complex condition is FALSE. For action CANCEL - RUN_BRANCH=B_DO_THE_BAD_THING and STOP_BRANCH=G_DO_THE_GOOD_THING BRANCH selected to STOP: G_DO_THE_GOOD_THING BRANCH selected to CONTINUE: B_DO_THE_BAD_THING CANCELLED_JOBS: G_DO_THE_GOOD_THING PAUSED_JOB: RELEASED_JOB: ============ END of branch job BRANCH_1 ==========
450
Important: The previous and following scenarios contain demonstrations of complex conditions usage. Note that in any scenario where you use the complex condition, you may also negate the result of each particular sub-condition. So far we have demonstrated the complex scenarios that are based only on one sub-condition. We demonstrate the usage of multiple atomic sub-conditions in 7.3.12, Complex scenario - multiple conditions on page 458. There you can learn how to use multiple sub-conditions, where some of them are negated and the others are left as they are.

Table 7-5 contains the necessary input parameters for the negated pattern within the pattern row scenario.
Table 7-5 Input parameters for negated pattern within pattern row scenario Parameter name CONDITION_SWITCH PATTERN_1 VALUE_1 NEGATE_CONDITION_RESULT_1 Parameter value COMPLEX Backup of Primary device ERROR YES
Example 7-14 shows how the parameter definition looks. The text is entered into the Comments field of the job stream definition.
Example 7-14 Negated pattern within pattern scenario parameters definition
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=Backup of Primary device VALUE_1=ERROR NEGATE_CONDITION_RESULT_1=YES BRANCH_1-END
Note: The instructions related to the branch job parameters are described in n 7.5, Working with the branch job parameters on page 509.

Put the generic branch job into the job stream just after the parent job and rename the good child with the G_ prefix and the bad child with the B_ prefix.
451
Also, follow the best practice and rename the branch job so that it has a suffix constructed from the underscore character and numeric value. A typical name of the first branch job within a job stream is BRANCH_1.

The generic branch job described in this chapter is available as a supplemental file that is available with this book. Together with the branch job source code, we provide you with the sample scenarios that are demonstrated in this chapter. If you follow the instructions described in 7.7, Sample scenarios installation on page 530, you can also install the sample scenarios. The name of the job stream representing this sample scenario is GBJ_PAT_PAT_NEG. Note: All the sample scenarios are named with the GBJ_ prefix. This allows you to create dedicated lists in your Job Scheduling Console.
7.3.11 Complex branch - Numeric value comparison

This scenario demonstrates pattern searching combined with the numeric value comparison.
Pattern within pattern row branch usage

This scenario extends the functionality of the pattern scenario described in 7.3.7, Complex branch - Pattern on page 432. The purpose of this scenario is as follows: 1. Get the parents joblog. 2. Within this joblog, identify a row containing a specific pattern. 3. If such row has been found, try to find numeric value within the row. 4. Compare this number against another number that has been supplied as the input parameter. For the comparison, use the arithmetical operator that has been also supplied as the input parameter. The typical usage scenario may look as shown in the extract from the parents joblog shown in Example 7-9 on page 442.
452
Example 7-15 Example of parents joblog numeric value comparison
Checking free space... Free space on volume ABC is 50 %. We want to perform the following evaluation: 1. Search for the pattern Free space on volume. 2. Then, if such a row is found, try to extract a numeric value from the row. 3. Compare this numeric value as follows: If (numeric_value > 30) Then CONDITION=TRUE Else CONDITION=FALSE
Note: The number 30 and operator > are parameters passed to the branch job. You can use any of the arithmetical operators such as <, <=, >, and so on. The way the numbers and operators can be passed to the branch job is described in 7.5, Working with the branch job parameters on page 509. We demonstrate this scenario below. Note: In this scenario, we can invert the evaluation logic. Normally this is not necessary, because you can reach the negated condition result just by using the opposite operator (such as < instead of >).
453
Numeric value comparison demonstration

Figure 7-24 shows the definition for the numeric value comparison scenario.
Figure 7-24 Numeric comparison branch definition
Figure 7-25 on page 455 demonstrates how the job stream has run if both parts of the condition have been fulfilled. The pattern text is found and the numeric value is successfully extracted from the pattern row. Then the arithmetical comparison is performed with a successful result. Thus, the whole condition is evaluated as CONDITION=TRUE.
454
Figure 7-25 Numeric comparison branch final status
Example 7-16 Numeric comparison branch joblog
============ START of branch job BRANCH_1 ========== ========================================================== ============= Job environment ============= MASTER_PLATFORM=UNIX STREAM_NAME=GBJ_PATTERN_NUM STREAM_CPU=SYDNEY BRANCH_JOB_NAME=BRANCH_1 PARENT=PATTERN_NUMBER_JOB ========================================================== ============= Input parameters ============= CONDITION_SWITCH=COMPLEX ACTION_SWITCH=CANCEL CONDITION_COUNT=1 PATTERN[1]=Free space on volume IS_CASE_SENSITIVE[1]=YES
455
IS_REGULAR_EXPRESSION[1]=NO VALUE[1]=30 ARITHMETICAL_OPERATOR[1]=-gt NEGATE_CONDITION_RESULT[1]=NO ========================================================== ============= MAIN DECISION MAKING ============= COMPLEX condition evaluation ----------ATOMIC CONDITION 1-----------Searching for "Free space on volume" in JOBLOG of PATTERN_NUMBER_JOB Pattern FOUND, performing further tests. Searching for NUMBER withing row... Number found=50. Evaluating arithmetical expression [ 50 -gt 30 ] Arithmetical expression [ 50 -gt 30 ] evaluated as TRUE. ATOMIC CONDITION RESULT [1]= TRUE -------------------------------------------- COMPLEX CONDITION ---------[ TRUE ] CONDITION_RESULT=TRUE TRUE: The result of complex condition is TRUE. ========================================================== ============= Action on STOP Branch ============= Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAEET.B_DO_THE_BAD_THING %cj SYDNEY#0AAAAAAAAAAAAEET.B_DO_THE_BAD_THING;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_PATTERN_NUM[(2113 12/17/07),(0AAAAAAAAAAAAEET)].B_DO_THE_BAD_THING ========================================================== ============= Action on RUN Branch ============= Performing action RELEASE on job SYDNEY#0AAAAAAAAAAAAEET.G_DO_THE_GOOD_THING Releasing of job SYDNEY#0AAAAAAAAAAAAEET.G_DO_THE_GOOD_THING is NOT NECESSARY, because priority=10 ========================================================== ============= Statistics of branch job BRANCH_1 ============= TRUE: The result of complex condition is TRUE. For action CANCEL - RUN_BRANCH=G_DO_THE_GOOD_THING and STOP_BRANCH=B_DO_THE_BAD_THING BRANCH selected to STOP: B_DO_THE_BAD_THING BRANCH selected to CONTINUE: G_DO_THE_GOOD_THING CANCELLED_JOBS: B_DO_THE_BAD_THING PAUSED_JOB: RELEASED_JOB: ============ END of branch job BRANCH_1 ==========
456

Table 7-6 contains the necessary input parameters for the pattern within pattern row scenario.
Table 7-6 Input parameters for the Numeric comparison scenario Parameter name CONDITION_SWITCH PATTERN_1 VALUE_1 ARITHMETICAL_OPERATOR Parameter value COMPLEX Free space on volume 30 -gt
Important: It is necessary to understand the order how the numbers are passed to the arithmetical expression. The functionality is as follows: number_from_the_joblog compared_against number_supplied_as_input_parameter The compared_against represents the arithmetical operator that is also passed as the input parameter. If this input parameter is not specified, then the default value -eq (equals) is used. Example 7-17 shows how the parameter definition looks. The text is entered into the Comments field of the job stream definition.
Example 7-17 Numeric comparison scenario parameters definition
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=Free space on volume VALUE_1=30 ARITHMETICAL_OPERATOR_1=-gt BRANCH_1-END
457

Put the generic branch job into the job stream just after the parent job and rename the good child with the G_ prefix and the bad child with the B_ prefix.

The generic branch job described in this chapter is available as a supplemental file that is available with this book. Together with the branch job source code, we provide you with the sample scenarios that are demonstrated in this chapter. If you follow the instructions described in 7.7, Sample scenarios installation on page 530, you can also install the sample scenarios. The name of the job stream representing this sample scenario is GBJ_PATTERN_NUM. Note: All the sample scenarios are named with the GBJ_ prefix. This allows you to create dedicated lists in your Job Scheduling Console.
7.3.12 Complex scenario - multiple conditions

This section describes the usage of the complex branch job when there are multiple sub-conditions set at the same time.
Complex condition usage

In the previous sections, we demonstrate atomic elements of the complex condition. We demonstrate the following functionality that evaluates the parents joblog: Searching for a text pattern. Searching for two separate text patterns within one row. Searching for a text pattern and extracting a numeric value from an identified row. Then the value has been compared against the number supplied as the input parameter. The arithmetical operator used for this comparison has been also supplied as the input parameter. Optional negating of any sub-condition. In this section, we explain how to put all the logic together. The generic branch job will get the parents joblog and will run a complex condition against it.
458
Complex condition demonstration

In this section, we show how the generic branch job gets the parents joblog and runs a complex condition against it. The following requirements must be met: The joblog must not include the pattern Error.
and
One of two of the following atomic conditions must be fulfilled: There should be information about the free space on the Primary device. The number describing the free space amount must be greater than 50.
or
There should be information about the free space on the Secondary device. the number describing the free space amount must be greater than 60.
459
Figure 7-26 shows the definition for the complex branch scenario.
Figure 7-26 Complex condition definition
Figure 7-27 on page 461 shows how the complex branch runs based on a set of defined sub-conditions.
460
Figure 7-27 Complex condition final status
461
Figure 7-27 on page 461 contains a step by step explanation of the complex branch scenario. It lists the input parameters of the branch job (in the condition box) and then explains how each particular atomic sub-condition has been evaluated. Finally, the evaluation of the complex condition is explained. Example 7-18 contains the output of the joblog of the generic branch job instance.
Example 7-18 Complex condition joblog
============ START of branch job BRANCH_1 ========== ========================================================== ============= Job environment ============= MASTER_PLATFORM=UNIX STREAM_NAME=GBJ_COMPLEX STREAM_CPU=SYDNEY BRANCH_JOB_NAME=BRANCH_1 PARENT=COMPLEX_JOB ========================================================== ============= Input parameters ============= CONDITION_SWITCH=COMPLEX ACTION_SWITCH=CANCEL CONDITION_COUNT=3 PATTERN[1]=Error IS_CASE_SENSITIVE[1]=YES IS_REGULAR_EXPRESSION[1]=NO NEGATE_CONDITION_RESULT[1]=YES PATTERN[2]=Free space on Primary device IS_CASE_SENSITIVE[1]=YES IS_REGULAR_EXPRESSION[1]=NO VALUE[2]=50 ARITHMETICAL_OPERATOR[2]=-gt BOOLEAN OPERATOR[2]=&& NEGATE_CONDITION_RESULT[2]=NO PATTERN[3]=Free space on Secondary device IS_CASE_SENSITIVE[1]=YES IS_REGULAR_EXPRESSION[1]=NO VALUE[3]=60 ARITHMETICAL_OPERATOR[3]=-gt BOOLEAN OPERATOR[3]=|| NEGATE_CONDITION_RESULT[3]=NO ========================================================== ============= MAIN DECISION MAKING ============= COMPLEX condition evaluation ----------ATOMIC CONDITION 1-----------Searching for "Error" in JOBLOG of COMPLEX_JOB
462
Pattern NOT FOUND, condition evaluated as FALSE. ==NEGATED== ATOMIC CONDITION RESULT [1]= TRUE ----------ATOMIC CONDITION 2-----------Searching for "Free space on Primary device" in JOBLOG of COMPLEX_JOB Pattern FOUND, performing further tests. Searching for NUMBER withing row... Number found=55. Evaluating arithmetical expression [ 55 -gt 50 ] Arithmetical expression [ 55 -gt 50 ] evaluated as TRUE. ATOMIC CONDITION RESULT [2]= TRUE ----------ATOMIC CONDITION 3-----------Searching for "Free space on Secondary device" in JOBLOG of COMPLEX_JOB Pattern FOUND, performing further tests. Searching for NUMBER withing row... Number found=10. Evaluating arithmetical expression [ 10 -gt 60 ] Arithmetical expression [ 10 -gt 60 ] evaluated as FALSE. ATOMIC CONDITION RESULT [3]= FALSE -------------------------------------------- COMPLEX CONDITION ---------[ TRUE ] && [ TRUE ] || [ FALSE ] CONDITION_RESULT=TRUE TRUE: The result of complex condition is TRUE. ========================================================== ============= Action on STOP Branch ============= Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAEEW.B_DO_THE_BAD_THING %cj SYDNEY#0AAAAAAAAAAAAEEW.B_DO_THE_BAD_THING;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_COMPLEX[(2219 12/17/07),(0AAAAAAAAAAAAEEW)].B_DO_THE_BAD_THING ========================================================== ============= Action on RUN Branch ============= Performing action RELEASE on job SYDNEY#0AAAAAAAAAAAAEEW.G_DO_THE_GOOD_THING Releasing of job SYDNEY#0AAAAAAAAAAAAEEW.G_DO_THE_GOOD_THING is NOT NECESSARY, because priority=10 ========================================================== ============= Statistics of branch job BRANCH_1 ============= TRUE: The result of complex condition is TRUE. For action CANCEL - RUN_BRANCH=G_DO_THE_GOOD_THING and STOP_BRANCH=B_DO_THE_BAD_THING BRANCH selected to STOP: B_DO_THE_BAD_THING BRANCH selected to CONTINUE: G_DO_THE_GOOD_THING CANCELLED_JOBS: B_DO_THE_BAD_THING PAUSED_JOB: RELEASED_JOB:
463
============ END of branch job BRANCH_1 ==========

Table 7-7 contains the necessary input parameters for the complex branch scenario.
Table 7-7 Input parameters for the complex condition scenario Parameter name CONDITION_SWITCH PATTERN_1 NEGATE_CONDITION_RESULT_1 PATTERN_2 VALUE_2 ARITHMETICAL_OPERATOR_2 BOOLEAN OPERATOR_2 PATTERN_3 VALUE_3 ARITHMETICAL_OPERATOR_3 BOOLEAN OPERATOR_3 Parameter value COMPLEX Error YES Free space on Primary device 50 -gt && Free space on Secondary device 60 -gt ||
Example 7-19 Complex condition scenario parameters definition
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=Error NEGATE_CONDITION_RESULT_1=YES PATTERN_2=Free space on Primary device VALUE_2=50 ARITHMETICAL_OPERATOR_2=-gt BOOLEAN_OPERATOR_2=&& PATTERN_3=Free space on Secondary device VALUE_3=60 ARITHMETICAL_OPERATOR_3=-gt BOOLEAN_OPERATOR_3=||
464
BRANCH_1-END


The generic branch job described in this chapter is available as a supplemental file that is available with this book. Together with the branch job source code, we provide you with the sample scenarios that are demonstrated in this chapter. If you follow the instructions described in 7.7, Sample scenarios installation on page 530, you can also install the sample scenarios. The name of the job stream representing this sample scenario is GBJ_COMPLEX. Note: All the sample scenarios are named with the GBJ_ prefix. This allows you to create dedicated lists in your Job Scheduling Console.
7.3.13 Additional string parameters

This section describes two additional parameters that refine the pattern search. The pattern search is performed using the grep command. This command takes various input parameters. The generic branch job is able to use the following parameters: Switching on/off case sensitive search Switching on/off search based on regular expressions The following parameters are used for this functionality: IS_CASE_SENSITIVE_i (The default is YES.) IS_REGULAR_EXPRESSION_i (The default is NO.)
465
These parameters must have the suffix _i, where i represents the index of the particular sub-condition. Note: The instructions related to the branch job parameters are described in 7.5, Working with the branch job parameters on page 509.
Using these specified parameters allows you to define a generic pattern search. We demonstrate this functionality in two sample scenarios that are not documented in this chapter. They are available as the sample scenarios that you can install into your Tivoli Workload Scheduler environment. The names of these sample scenarios are as follows: GBJ_PATTERN_CASE: Demonstrates the pattern search when case sensitivity is switched off. GBJ_PAT_REGEXP: Demonstrates the pattern search using the regular expression. For detailed information about the sample scenarios installation, refer to 7.7, Sample scenarios installation on page 530.
7.3.14 Scenarios based on action type

So far we have demonstrated generic branch job scenarios based on the condition type. Now we will demonstrate scenarios based on the action type. First, we repeat a few terms from the branch job terminology: Condition: Determines what criteria should be used for determining the run branch (what shall continue) and the stop branch (what shall stop). Action: Determines what should be done on the run branch and on the stop branch. There are two types of actions that can be performed on the stop branch and two types of actions that can be performed on the run branch. In addition, there is one special action. The list of possible actions are: Stop branch CANCEL: The whole stop branch is cancelled. This is the most frequently used action that is performed on the stop branch. We have used this action in all of the previous scenarios. PAUSE: The first job of the stop branch is paused (HOLD).
466
We explain the usage of this action in 7.3.15, Pause/Release actions scenario on page 467. Run branch No action: Just let the run branch run. This is the most frequently used action that is performed on the run branch. We have used this action in all of the previous scenarios. Release: If the first job of the run branch is paused (HOLD), then its priority is raised (RELEASE). We explain the usage of this action in 7.3.15, Pause/Release actions scenario on page 467. Special action SIGNAL: This action does not do anything with any of the branches. It recommends what confirmation should be performed by the Tivoli Workload Scheduler operator. We explain the usage of this action in 7.3.17, Signal action scenario on page 479.
7.3.15 Pause/Release actions scenario

This section describes the usage of the pause/release action pair.
Pause/Release action usage

In this section, we demonstrate the scenario where we need to manage the job stream that is sensitive to some important job result. In this description, we concentrate on the branch job usage when the action performed by the important job did not end successfully. In the previous sections, we described the most common branch job usage, that is, based on the condition, we have been deciding which branch will be canceled and which we will let run. The pause/release scenario describes different approaches. In case of the error state that has been identified by the branch job, we do not want to cancel any of the branches. Instead of immediate cancelling, we will run a sequence of corrective actions that could help resolve the error state. If the corrective actions succeed, we want to continue in the original direction as though no error occurred.
467
For this non-trivial scenario, we use the pause/release approach. We need to use (at least) two branch jobs within one job stream. The process flow looks as follows: We have the important job followed by the first branch job. The branch job is followed by a good branch and a bad branch. The good branch includes the jobs that run if everything is okay. Let us call it the OK branch. The bad branch includes a sequence of jobs that perform corrective actions (usually more than one). Let us call it the corrective branch. The first branch job evaluates the condition run against the parent job (our important job). If CONDITION=TRUE, then everything is okay and the stop branch is cancelled. All the jobs in the corrective branch are cancelled, because no corrective action is needed. If CONDITION=FALSE, then the stop branch is not cancelled. Instead, it is just paused. This is achieved by pausing the good child (the first job of the stop branch). By pausing the good child, the OK branch is being HELD. While the OK branch is being paused, the corrective branch starts corrective actions. After the sequence of corrective actions finishes, the second branch job (placed within the corrective branch) is launched and evaluates the result of the corrective actions. If the corrective actions have succeeded, then the OK branch is released. This is achieved by releasing the good child. If the corrective actions have failed, then the OK branch is cancelled and the job stream continues to run in the bad branch of the second branch job. The bad branch of the second branch job mostly contains only one ABEND job (a job that performs an exit 1 command). It is a good practice to end the bad branch of the corrective branch with the ABEND job, because it ensures that the whole job stream abends (the previous abended jobs had Recovery option=CONTINUE, so they did not propagate the ABEND status to the final job stream status). Important: Both the branch jobs must point to the same good child! This is absolutely crucial, because otherwise the concept will not work!
468
Pause/Release action demonstration

Figure 7-28 on page 470 shows the job stream definition for the pause/release scenario. In this case, the following parameter is defined for the first branch job: ACTION_SWITCH=PAUSE No parameter is defined for the second branch job.
469
Figure 7-28 Pause/Release action definition
Figure 7-29 on page 471 demonstrates how the job stream has run when the first branch job finished.
470
Figure 7-29 Pause/Release action status after first branch job
As you can see, the stop branch (the OK branch) has not been cancelled; it has just been paused and the jobs in the run branch (the corrective branch) perform a sequence of corrective actions.
471
Example 7-20 contains the joblog of the first branch job instance.
Example 7-20 Pause/Release action - joblog of the 1st branch job
============ START of branch job BRANCH_1 ========== ========================================================== ============= Job environment ============= MASTER_PLATFORM=UNIX STREAM_NAME=GBJ_PAUSE STREAM_CPU=SYDNEY BRANCH_JOB_NAME=BRANCH_1 PARENT=IMPORTANT_JOB_ABEND ========================================================== ============= Input parameters ============= CONDITION_SWITCH=PARENT_SUCCESS ACTION_SWITCH=PAUSE ========================================================== ============= MAIN DECISION MAKING ============= Evaluation dependent on PARENT_SUCCESS FALSE: Searched for SUCC parent. Status of PARENT JOB(IMPORTANT_JOB_ABEND) is ABEND. ========================================================== ============= Action on STOP Branch ============= Performing action PAUSE on job SYDNEY#0AAAAAAAAAAAAEEX.G_DO_THE_GOOD_THING %altpri SYDNEY#0AAAAAAAAAAAAEEX.G_DO_THE_GOOD_THING;schedid;0;noask Command forwarded to batchman for SYDNEY#GBJ_PAUSE[(2300 12/17/07),(0AAAAAAAAAAAAEEX)].G_DO_THE_GOOD_THING ========================================================== ============= Action on RUN Branch ============= Performing action RELEASE on job SYDNEY#0AAAAAAAAAAAAEEX.B_PERFORM_CORRECTIVE_ACTIONS Releasing of job SYDNEY#0AAAAAAAAAAAAEEX.B_PERFORM_CORRECTIVE_ACTIONS is NOT NECESSARY, because priority=10 ========================================================== ============= Statistics of branch job BRANCH_1 ============= FALSE: Searched for SUCC parent. Status of PARENT JOB(IMPORTANT_JOB_ABEND) is ABEND. For action PAUSE - RUN_BRANCH=B_PERFORM_CORRECTIVE_ACTIONS and STOP_BRANCH=G_DO_THE_GOOD_THING BRANCH selected to STOP: G_DO_THE_GOOD_THING BRANCH selected to CONTINUE: B_PERFORM_CORRECTIVE_ACTIONS CANCELLED_JOBS: PAUSED_JOB: G_DO_THE_GOOD_THING RELEASED_JOB:
472
============ END of branch job BRANCH_1 ========== Figure 7-30 demonstrates how the job stream has run when the second branch job finished.
Figure 7-30 Pause/Release action after second branch job
473
As you can see, the corrective actions were successful, so the OK branch has been released. Example 7-21 contains the joblog of the second branch job instance.
Example 7-21 Pause/Release action - joblog of the 1st branch job
============ START of branch job BRANCH_2 ========== ========================================================== ============= Job environment ============= MASTER_PLATFORM=UNIX STREAM_NAME=GBJ_PAUSE STREAM_CPU=SYDNEY BRANCH_JOB_NAME=BRANCH_2 PARENT=SOME_CORRECTIVE_JOB_2 ========================================================== ============= Input parameters ============= CONDITION_SWITCH=PARENT_SUCCESS ACTION_SWITCH=CANCEL ========================================================== ============= MAIN DECISION MAKING ============= Evaluation dependent on PARENT_SUCCESS TRUE: Searched for SUCC parent. Status of PARENT JOB(SOME_CORRECTIVE_JOB_2) is SUCC. ========================================================== ============= Action on STOP Branch ============= Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAEEX.B_ABEND_JOB %cj SYDNEY#0AAAAAAAAAAAAEEX.B_ABEND_JOB;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_PAUSE[(2300 12/17/07),(0AAAAAAAAAAAAEEX)].B_ABEND_JOB ========================================================== ============= Action on RUN Branch ============= Performing action RELEASE on job SYDNEY#0AAAAAAAAAAAAEEX.G_DO_THE_GOOD_THING Releasing SYDNEY#0AAAAAAAAAAAAEEX.G_DO_THE_GOOD_THING, because priority=0 %altpri SYDNEY#0AAAAAAAAAAAAEEX.G_DO_THE_GOOD_THING;schedid;10;noask Command forwarded to batchman for SYDNEY#GBJ_PAUSE[(2300 12/17/07),(0AAAAAAAAAAAAEEX)].G_DO_THE_GOOD_THING ========================================================== ============= Statistics of branch job BRANCH_2 ============= TRUE: Searched for SUCC parent. Status of PARENT JOB(SOME_CORRECTIVE_JOB_2) is SUCC. For action CANCEL - RUN_BRANCH=G_DO_THE_GOOD_THING and STOP_BRANCH=B_ABEND_JOB BRANCH selected to STOP: B_ABEND_JOB
474
BRANCH selected to CONTINUE: G_DO_THE_GOOD_THING CANCELLED_JOBS: B_ABEND_JOB PAUSED_JOB: RELEASED_JOB:G_DO_THE_GOOD_THING ============ END of branch job BRANCH_2 ==========

Table 7-8 contains the necessary input parameters for the first branch job of the pause/release scenario. The second branch job does not need any action related input parameters.
Table 7-8 Input parameters for the pause/release scenario Parameter name ACTION_SWITCH Parameter value PAUSE
Important notes: The parameter ACTION_SWITCH=PAUSE is necessary only for the first branch job within the job stream. The second branch job must have the ACTION SWITCH=CANCEL. You do not need to specify this parameter because ACTION SWITCH=CANCEL is the default value. Both branch jobs must point to the same good child. It is also important that each branch job must have a different suffix. For example, in this simple pause/release scenario, two branch job names should be used: BRANCH_1 and BRANCH_2. Example 7-22 shows how the parameter definition looks. The text is entered into the Comments field of the job stream definition.
Example 7-22 Pause/Release scenario parameters definition
BRANCH_1-BEGIN ACTION_SWITCH=PAUSE BRANCH_1-END
475

Put the generic branch job into the job stream just after the parent job and rename the good child with the G_ prefix and the bad child with the B_ prefix. The first branch job determines the OK branch (followed by the good child) and the corrective branch (followed by the bad child). The job representing the good child must have the G_ prefix while the job representing the bad child must have the B_ prefix. Both branch jobs must point to the same good child! This means that the good child of the first branch job must be identical to the good child of the second branch job. The best practice is to place the ABEND job as the bad child of the second branch job. The ABEND job just calls system command exit 1, which causes the job to ABEND. Having an ABEND job in the bad branch ensures that the ABEND status will be propagated also on the job stream level. Any previously ABENDed jobs would not propagate the ABEND state on the job stream level if the job had the recovery option set to Continue. Actually, all the branch job parents need to have this option specified in order to be able to allow the branch job to run.

The generic branch job described in this chapter is available as a supplemental file that is available with this book. Together with the branch job source code, we provide you with the sample scenarios that are demonstrated in this chapter. If you follow the instructions described in 7.7, Sample scenarios installation on page 530, you can also install the sample scenarios. The name of the job stream representing this sample scenario is GBJ_PAUSE. Note: All the sample scenarios are named with the GBJ_ prefix. This allows you to create dedicated lists in your Job Scheduling Console.
7.3.16 Multiple pause/release scenario

The purpose of the pause/release scenario may be sometimes hard to explain. The question that is often asked is: The Tivoli Workload Scheduler has the recovery jobs implemented by default, so why do we need such a complicated scenario?
476
The answer has its roots in one customers implementation. The customer required the following functionality: Stop the VMWare machine in order to be able to unmount its drives. If the stop was not successful, try to stop the instance again. So far it sounds like a common usage of the recovery job. But then the customer requested: Try to stop the VmWare machine three times. If you are not able to do it within three attempts, then ABEND. This was the original reason why the branch job was extended with the pause/release functionality. This concept allows you to run a sequence of corrective actions. In addition to the classical pause/release scenario, this approach lets you exit the corrective branch in the middle of the corrective process. When any of the corrective actions are successful, the involved branch job will cancel the rest of the corrective branch and release the OK branch.
477
We show this functionality in Figure 7-31.
Figure 7-31 Multiple pause/release scenario definition
478
Important: It is necessary to set the input parameter ACTION_SWITCH=PAUSE for all branch jobs except the very last one. In our scenarios, the following branch jobs must set the ACTION_SWITCH=PAUSE parameters: BRANCH_1, BRANCH_2, and BRANCH_3. If you did not specify these parameters, the good child would get cancelled by some middle branch job. All branch jobs must point to the same good child. It is also important that each branch job have a different suffix. For example, in this multiple pause/release scenario, the following branch job names should be used: BRANCH_1, BRANCH_2, BRANCH_3, and BRANCH_4. The best practise is to set the ABEND job as the bad child of the last branch job. The ABEND job just calls the system command exit 1. This causes the job to ABEND and this status is also propagated to the job stream level.
7.3.17 Signal action scenario

This section describes the signal action concept.
Signal action usage

This scenario describes special branch job usage. It originates from the following requirements: The branch job should evaluate the condition run against the parents properties (the parents status or a condition constructed upon the parents joblog). Allows the operator to manually influence the decision making based on the
condition result.
In essence, the signal scenario gives you prompt-like functionality. But unlike the classical Tivoli Workload Scheduler prompts, the signal scenario has the following advantages: The Tivoli Workload Scheduler operator receives already preprocessed recommendations for confirmation (SUCC/ABEND, which represents the YES/NO functionality of prompts) Instead of blocking the content, the run branch is selected and the job stream continues. This functionality extends the approach that is available with the Tivoli Workload Scheduler prompts.
479
The signal scenario represents the combination of prompts with the capabilities of the branch job. In addition, the information necessary for an operators decision making is preprocessed and offered to the operator in the joblog of the signal job. The design of the signal scenario is not trivial. We had to clone the original branch job into a special case called the signal job. From the Tivoli Workload Scheduler perspective, this job is identical to the branch job, and differs only for two parameters. From the logical perspective, the signal job and branch job are different in their last step, which is the performed action. While the branch job always cancels, pauses, or releases its children, the signal job just prints the recommendation. This recommendation is used by the operator and instructs him in decision making. The following design fulfills the requirements or our scenario: 1. There are two sequentially ordered jobs: The signal job The branch job 2. The first job is the signal job. It is just a variation of the branch job with two different properties: The property within the job definition Recovery Option is set to CONTINUE (instead of STOP, which is the value used for the classical branch job). It has the flag Requires Confirmation set within the job stream definition. In addition, it defines the parameter ACTION_SWITCH=SIGNAL. 3. The signal job performs the evaluation logic (evaluates the condition against the parents properties), but does not cancel or pause any of its children. It just places a confirmation recommendation into its joblog. 4. The Requires Confirmation flag will cause the signal job to stop processing of the job stream. After the signal job finishes, it will remain in the PEND status. This status requires the operators confirmation (either SUCC or ABEND) in order to release the successors from the FOLLOWS dependency. 5. The joblog of the signal job contains the complete condition evaluation process. It is accompanied by the confirmation recommendation. It means that the signal job evaluates the condition and the places the recommendation (Confirm SUCC or Confirm ABEND) in its joblog. 6. The operator looks into the signal jobs joblog and confirms the job with either a SUCC or ABEND status.
480
7. The subsequent branch job will not start until the operator confirms the signal job. Then it will evaluate the status of the parent job, which is in fact the signal job. This state has been directly set by the operator during the confirmation process (Confirm SUCC or Confirm ABEND). 8. Now the branch job will start. It determines that its parent is the signal job. The branch job determines the status of the signal job. The status of the signal job has been previously set by the operator (SUCC/ABEND). The branch job then determines the run branch and stop branch. This last step is just the usage of the simple branching that was presented in the very first scenario of this chapter.
Signal action demonstration

Figure 7-32 shows the job stream definition for the signal scenario. In this case, the following parameter is defined for the signal job: ACTION_SWITCH=SIGNAL
Figure 7-32 Signal action definition
481
Figure 7-33 demonstrates how the job stream has run when the first branch job finished.
Figure 7-33 Signal action state after the signal job
482
As you can see, the signal job job is being HELD (in fact, it is in the PEND status). This state requires the operators confirmation. Without the confirmation, the jobs successors cannot run. Example 7-23 contains the joblog of the signal job. Note the lines in bold text that represent important steps.
Example 7-23 Signal action joblog of the 1st branch job
============ START of branch job SIGNAL_1 ========== ========================================================== ============= Job environment ============= MASTER_PLATFORM=UNIX STREAM_NAME=GBJ_SIGNAL STREAM_CPU=SYDNEY BRANCH_JOB_NAME=SIGNAL_1 PARENT=PATTERN_JOB ========================================================== ============= Input parameters ============= CONDITION_SWITCH=COMPLEX ACTION_SWITCH=SIGNAL CONDITION_COUNT=1 PATTERN[1]=completed successfully IS_CASE_SENSITIVE[1]=YES IS_REGULAR_EXPRESSION[1]=NO NEGATE_CONDITION_RESULT[1]=NO ========================================================== ============= MAIN DECISION MAKING ============= COMPLEX condition evaluation ----------ATOMIC CONDITION 1-----------Searching for "completed successfully" in JOBLOG of PATTERN_JOB Pattern FOUND, performing further tests. No additional value defined for specified pattern. Condition evaluated as TRUE. ATOMIC CONDITION RESULT [1]= TRUE -------------------------------------------- COMPLEX CONDITION ---------[ TRUE ] CONDITION_RESULT=TRUE TRUE: The result of complex condition is TRUE. ========================================================== ============= Statistics of branch job SIGNAL_1 ============= ******Recommended confirmation for this job is SUCC.****** ============ END of branch job SIGNAL_1 ==========
483
Figure 7-34 demonstrates how the job stream has run when the subsequent branch job finished.
Figure 7-34 Signal action state after the subsequent branch job
484
Now when the signal job has been confirmed by the operator, the subsequent branch job could start. It has evaluated the parents (the signal jobs) status and determined the run branch and the stop branch. Example 7-24 contains the joblog of the subsequent branch job instance.
Example 7-24 Signal action - joblog of the 2nd branch job
============ START of branch job BRANCH_1 ========== ========================================================== ============= Job environment ============= MASTER_PLATFORM=UNIX STREAM_NAME=GBJ_SIGNAL STREAM_CPU=SYDNEY BRANCH_JOB_NAME=BRANCH_1 PARENT=SIGNAL_1 ========================================================== ============= Input parameters ============= CONDITION_SWITCH=PARENT_SUCCESS ACTION_SWITCH=CANCEL ========================================================== ============= MAIN DECISION MAKING ============= Evaluation dependent on PARENT_SUCCESS TRUE: Searched for SUCC parent. Status of PARENT JOB(SIGNAL_1) is SUCC. ========================================================== ============= Action on STOP Branch ============= Performing action CANCEL on job SYDNEY#0AAAAAAAAAAAAEI6.B_DO_THE_BAD_THING %cj SYDNEY#0AAAAAAAAAAAAEI6.B_DO_THE_BAD_THING;schedid;noask Command forwarded to batchman for SYDNEY#GBJ_SIGNAL[(0012 12/21/07),(0AAAAAAAAAAAAEI6)].B_DO_THE_BAD_THING ========================================================== ============= Action on RUN Branch ============= Performing action RELEASE on job SYDNEY#0AAAAAAAAAAAAEI6.G_DO_THE_GOOD_THING Releasing of job SYDNEY#0AAAAAAAAAAAAEI6.G_DO_THE_GOOD_THING is NOT NECESSARY, because priority=10 ========================================================== ============= Statistics of branch job BRANCH_1 ============= TRUE: Searched for SUCC parent. Status of PARENT JOB(SIGNAL_1) is SUCC. For action CANCEL - RUN_BRANCH=G_DO_THE_GOOD_THING and STOP_BRANCH=B_DO_THE_BAD_THING BRANCH selected to STOP: B_DO_THE_BAD_THING BRANCH selected to CONTINUE: G_DO_THE_GOOD_THING CANCELLED_JOBS: B_DO_THE_BAD_THING PAUSED_JOB:
485
RELEASED_JOB: ============ END of branch job BRANCH_1 ==========

Table 7-9 contains the necessary input parameters for the signal job. The subsequent branch job does not take any parameters.
Table 7-9 Input parameters for the signal action scenario Parameter name ACTION_SWITCH Parameter value SIGNAL
Example 7-25 shows how the parameter definition looks. The text is entered into the Comments field of the job stream definition. Note: Example 7-25 also lists some parameters that are not mandatory for the signal scenario. We demonstrate such a scenario when the signal job is decided because of the pattern search within the parents joblog. This is not mandatory, but in most cases, the signal scenario is being used when a parsing of parents joblog must be performed. This is the place where the power of signal scenario lays. It performs the complex parsing of particular jobs output and saves the operators time. However, the final decision is still in the operators hands.
Example 7-25 Complex condition scenario - parameters definition
SIGNAL_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=completed successfully ACTION_SWITCH=SIGNAL SIGNAL_1-END
Placing the branch jobs into the job stream

The signal job must be placed just after the evaluated job (the important job). It takes the name containing the string SIGNAL and the suffix. In our scenario, the jobs name was SIGNAL_1.
486
The subsequent branch job is the immediate successor of the signal job. It takes its common name with the appropriate suffix. If it is the first branch job within the job stream, its name is BRANCH_1. Note: In our scenario, we have used one signal job and one branch job. Both jobs start with index 1, so the job names are SIGNAL_1 and BRANCH_1. The children of the branch job must follow the common guidelines: The good childs name must begin with the G_ prefix. The bad childs name must begin with the B_ prefix.

The generic branch job described in this chapter is available as a supplemental file that is available with this book. Together with the branch job source code, we provide you with the sample scenarios that are demonstrated in this chapter. If you follow the instructions described in 7.7, Sample scenarios installation on page 530, you can also install the sample scenarios. The name of the job stream representing this sample scenario is GBJ_SIGNAL. Note: All the sample scenarios are named with the GBJ_ prefix. This allows you to create dedicated lists in your Job Scheduling Console.
7.3.18 Important scenario notes

In the previous sections, we demonstrated various usage scenarios of the generic branch job. Some of them are used very often, while others are used only occasionally. We have shown scenarios of two basic types: Scenarios based on condition Scenarios based on action In the scenarios based on condition, we have only used ACTION_SWITCH=CANCEL. We want to begin our explanation with the easiest and then to continue to the more complex scenario. Therefore, we did not mix conditions with actions.
487
In the scenarios based on action, we have mostly used the simple branch scenario (CONDITION SWITCH=PARENT_SUCCESS). Again, for the same reason, we have focused on the essential topic of the scenario, that is, ACTIONS usage. However, you may combine any type of condition with any type of action. You decide if you want to use only the simplest scenario or if you want to pause some branch based on the condition some pattern must not be present in the parents joblog. When you are unsure about what did happen during the branching process, check the particular branch jobs joblog.
7.4 Working with the branch job

This section contains a step by step description of the tasks that must been taken in order to be able to use the generic branch job in your existing Tivoli Workload Scheduler environment. These step by step instructions cover the following topics: Branch job prerequisites Placing the branch job shell script onto the file system of your master Defining the branch job in the Tivoli Workload Scheduler database Placing the branch job into the correct place of the job stream Passing the input parameters to the branch job, if necessary Note: Other important notes are listed in 7.6, Important notes about the branch job on page 528. The installation process is manual. You must follow the step-by-step instructions described in this chapter. Even if the steps included in this section describe only steps related to job definition, only a tailored Tivoli Workload Scheduler should perform them. Important: We strongly recommend installing the branch job in the test environment first. Only when you are familiar with the branch job functionality should you move it into the production environment.
488
7.4.1 Branch job prerequisites

This section lists the prerequisites that must be met in order to run the generic branch job successfully in the Tivoli Workload Scheduler environment. The following list contains all the known prerequisites: The minimal level of the Tivoli Workload Scheduler master domain manager is V8.3. The current version of Tivoli Workload Scheduler, where the generic branch job has been tested, is V8.4. Tivoli Workload Scheduler versions prior to Version 8.3 have a different representation of job stream instances in the plan, and because of that the generic branch job cannot run on a version lower than V8.3. The branch job must be placed on the master domain manager. Theoretically, it could be put on any machine that runs the Tivoli Workload Scheduler Command Line client, but this functionality has not been tested yet. The branch job must run under the same user that is specified when you install your master domain manager.
7.4.2 Branch job shell script installation

This section describes how to place the branch job shell script onto the master file system. We cover the installation steps for UNIX and Windows platforms. Important: Branch job functionality has been tested for the case where the branch job shell script is placed onto a master domain manager and the Tivoli Workload Scheduler job is defined on the master domain manager as well.
Installation on UNIX systems

This section describes the installation of the generic branch job shell script on UNIX systems. 1. Download the installation package from the ITSO Web site. Refer to Appendix D, Additional material on page 615 for instructions on how to download the code. The name of the file for the UNIX platform is SG247528_Unix.tar. This file contains the branch.sh script together with the sample scenarios. At this time, we are interested only in the branch.sh file. 2. Transfer the file to your master domain manager. 3. Log in as the TWS_USER (owner of the master domain manager instance).
489
4. Save the file to a directory where the TWS_USER has full read/write/execute permissions. 5. Unpack the package by entering tar xvf generic_branch.job.tar. The directory tree generic_branch_job will be created. The content of the installation package for UNIX platforms is shown in Example 7-26.
Example 7-26 Content of the installation package for UNIX platforms
generic_branch_job generic_branch_job/branch generic_branch_job/branch/branch.sh generic_branch_job/definitions generic_branch_job/definitions/gbj_job.templates generic_branch_job/definitions/gbj_sched.templates generic_branch_job/scenario_installer.sh generic_branch_job/scenario_scripts generic_branch_job/scenario_scripts/gbj_pattern.sh generic_branch_job/scenario_scripts/gbj_pattern_pattern.sh generic_branch_job/scenario_scripts/gbj_pattern_pattern_error.sh generic_branch_job/scenario_scripts/gbj_multiple_conditions.sh generic_branch_job/scenario_scripts/gbj_pattern_error.sh generic_branch_job/scenario_scripts/gbj_pattern_number.sh 6. Determine the directory where you usually put the script files on your UNIX master domain manager. 7. The important file branch.sh is highlighted in bold in Example 7-26. The file is already in the UNIX format and it is not necessary to perform any CR/LF conversion. If you have extracted the tar package on another system and then you plan to transfer it through FTP/SCP, do not use the ASC type transfer. 8. Transfer the file to the directory that you have determined in the previous step. 9. On your UNIX master domain manager, go to the directory where you have placed the branch.sh file. 10.Change the ownership of the branch.sh file to the user under which the Tivoli Workload Scheduler UNIX master is installed. For example, if the Tivoli Workload Scheduler master runs under tws user, which is a member of the UNIX group tivoli, issue the following command: chown tws:tivoli branch.sh You must be in the directory where you have placed the branch.sh script in order to run this command successfully.
490
11.Change the branch.sh file permissions. Issue the following command: chmod +rx branch.sh You must be in the directory where you have placed the branch.sh script in order to run this command successfully. Now you have performed all the necessary steps for putting the branch.sh shell script onto your UNIX master.
Installation on Windows systems

This section describes the installation of the generic branch job shell script on Windows systems. Note: A Windows platform cannot natively interpret UNIX shell scripts. You must install a shell interpreter to be able to use the branch.sh shell script on the Windows master domain manager. We tested the functionality of the branch.sh shell script together with Cygwin. We provide detailed instructions of the Cygwin installation in Chapter 8, Installation of Cygwin onto a Windows master on page 547. 1. Make sure that you have Cygwin installed (another software that allows UNIX shell script interpretation on Windows is also allowed but has not been tested). 2. Go to the %TWS_HOME% directory and insert the following line into the jobmanrc.cmd file: set PATH=C:\cygwin\bin;%PATH% Important: Make a copy of your jobmanrc.cmd file before you edit it. If you find any other statement in the jobmanrc.cmd file that refers to the PATH variable, you can just extend this statement by using C:\cygwin\bin. Be aware that the delimiter on Windows platform is a semicolon character (;). Also, C:\cygwin\bin should point to the bin subdirectory of your Cygwin installation directory. If you have installed Cygwin into another directory than the default, you must use the correct path in this step.
491
3. Download the installation package from the ITSO Web site. Refer to Appendix D, Additional material on page 615 for instructions on how to download the code. The name of the file for the Windows platform is SG247528_Windows.zip. This file contains the branch.sh script file together with the sample scenarios. At this time, we are interested only in the branch.sh file. 4. Transfer the file to your master domain manager. 5. Log in as the TWS_USER (owner of the master domain manager instance). 6. Save the file to a directory where the TWS_USER has full read/write/execute permissions. 7. Unpack the package with any archive program that understands the zip algorithm. The directory tree generic_branch_job will be created. The content of the installation package for Windows platforms is shown in Example 7-27.
Example 7-27 Content of the installation package for Windows platforms
generic_branch_job generic_branch_job\branch generic_branch_job\branch\branch.sh generic_branch_job\definitions generic_branch_job\definitions\gbj_job.templates generic_branch_job\definitions\gbj_sched.templates generic_branch_job\scenario_installer.sh generic_branch_job\scenario_scripts generic_branch_job\scenario_scripts\gbj_pattern.cmd generic_branch_job\scenario_scripts\gbj_pattern_pattern.cmd generic_branch_job\scenario_scripts\gbj_pattern_pattern_error.cmd generic_branch_job\scenario_scripts\gbj_multiple_conditions.cmd generic_branch_job\scenario_scripts\gbj_pattern_error.cmd generic_branch_job\scenario_scripts\gbj_pattern_number.cmd 8. Determine the directory where you usually put the script files on your Windows master domain manager. 9. The important file branch.sh is highlighted in bold in Example 7-27. The file is already in the UNIX format that is understandable by Cygwin. The branch.sh file must not be converted into the Widows/DOS file format. Transfer the file to the directory that you have determined in the previous step. Now you have performed all the necessary steps for putting the branch.sh shell script onto your Windows master domain manager.
492
7.4.3 Branch job definition and signal job definition in the database
This section describes how to define the branch job and the signal job in the Tivoli Workload Scheduler database. We assume that you have already placed the branch.sh shell script onto your master domain manager and performed the other necessary steps, as described in 7.4.2, Branch job shell script installation on page 489. You can choose if you want to add the branch job definition and the signal job definition either using the graphical Job Scheduling Console interface or the composer command.
Two job definitions pointing to one shell script

This section shortly discusses why we need two job definitions pointing to one shell script. The branch job definition is necessary for all described scenarios. In addition, for the signal scenario, you must also add the definition of the signal job. Both jobs point to the same shell script file, only differ in the value for the Recovery Option: The branch job must have the Recovery Option set to STOP. The signal job must have the Recovery Option set to CONTINUE. The reason for having two different jobs pointing to the same shell script file is to protect against incorrect placement of the branch job (or the signal job) into the job stream: The classical branch job checks to see if it is correctly placed into the job stream. If not, it ABENDs. To prevent the successors from running, the branch job must have the Recovery Option set to STOP. The signal job must have the Recovery Option set to CONTINUE. The reason for this setting is explained in 7.3.17, Signal action scenario on page 479. The signal job performs the same checks for correct positioning within the job stream. When it is not correctly positioned, it just prints an error message and exits with a non-zero return code. Even if the Recovery Option is set to Continue, the job will not release its successors from the dependency, because it has set the flag Requires Confirmation (within the job stream definition). Because of this flag, the signal job remains in the PEND status and expects the operator to check its joblog. See 7.3.17, Signal action scenario on page 479 if you are unsure about the signal scenario.
493
Adding the job definitions using the Job Scheduling Console

This section describes how to add the job definitions for the branch job and the signal job using the Job Scheduling Console.
Steps for the UNIX master domain manager

Perform the following steps to create the branch job definition: 1. Open a job definition editor by clicking New Job Definition and selecting the proper engine. 2. Fill in the following fields in the General pane: Task type: UNIX. Name: BRANCH. Workstation name: Your master CPU. Login: The user under whom the master domain manager is installed. Recovery Options: Stop.
494
Refer to Figure 7-37 on page 498 for more details.
Figure 7-35 Branch job definition on UNIX master domain manager - 1
495
Switch to the Task pane and do the following: Select the Script radio button. In the Task field, provide the full path to the branch.sh shell script. Use forward slashes / in the path. Refer to Figure 7-38 on page 499 for more details.
Figure 7-36 Branch job definition on UNIX master domain manager - 2
Note: You can use the Tivoli Workload Scheduler parameters, as in any other job definition. Perform the following steps to create the signal job definition: 1. Open the job definition editor by clicking New Job Definition and selecting the proper engine.
496
2. Fill in the following fields in the General Pane: Task type: UNIX Name: SIGNAL Workstation name: Your master CPU Login: The user under whom the master domain manager is installed. Recovery Options: Continue (It is absolutely necessary for the signal job to have the recovery option set to Continue). 3. Switch to the Task pane and do the following: Select the Script radio button. In the Task field, provide the full path to the branch.sh shell script. Use forward slashes / in the path. Refer to Figure 7-38 on page 499 for more details. Note: Another approach for creating the signal job definition is using the Create another... function of Job Scheduling Console. Using this feature, you can clone the branch job definition and then just replace the name as Signal and switch the Recovery Options to Continue. You can use the Tivoli Workload Scheduler parameters as in any other job definition.
Steps for the Windows master domain manager

Perform the following steps to create the branch job definition: 1. Open a job definition editor by clicking New Job Definition and selecting the proper engine. 2. Stay in the General pane and fill in the following fields: Task type: Windows. Name: BRANCH. Workstation name: Your master CPU. Login: The user under whom the master domain manager is installed. Recovery Options: Stop.
497
Refer to Figure 7-37 for more details.
Figure 7-37 Branch job definition on Windows master domain manager - 1
3. Switch to the Task pane and do the following: Select the Script radio button. Task: You must provide two paths in the task definition: The first path points to Cygwin. Provide the full path to the Cygwin bash executable. Use standard Windows notation, that is, use backslashes (\) as the directory separator. The second path points to the shell script. Provide the full path to the shell script branch.sh. Use forward slashes (/) in the path. If the path contains any spaces, you must quote the path by double quotes.
498
Figure 7-38 shows the completed window.
Figure 7-38 Branch job definition on Windows master domain manager - 2
Note: You can use the Tivoli Workload Scheduler parameters as you would in any other job definition. Perform the following steps to create the signal job definition: 1. Open a job definition editor by clicking New Job Definition and selecting the proper engine. 2. Fill in the following fields in the General pane: Task type: UNIX. Name: SIGNAL.
499
Workstation name: Your master CPU. Login: The user under whom the master domain manager is installed. Recovery Options: Continue. (It is absolutely necessary for the signal job to have the recovery option set to Continue.) 3. Switch to the Task pane and do the following: Select the Script radio button. Task: You must provide two paths in the task definition: The first path points to Cygwin. Provide the full path to the Cygwin bash executable. Use standard Windows notation, that is, use backslashes (\) as the directory separator. The second path points to the shell script. Provide the full path to the shell script branch.sh. Use forward slashes (/) in the path. If the path contains any spaces, you must quote the path with double quotes.
Note: Another approach for creating the signal job definition is using the Create another... function of Job Scheduling Console. Using this feature, you can clone the branch job definition and then just replace the name with Signal and switch the Recovery Options to Continue. You can use the Tivoli Workload Scheduler parameters as you would in any other job definition.
Defining the branch job using composer

This section describes how to add the branch job and signal job definitions using the composer command. Do the following steps for the UNIX master domain manager: 1. Log on to the master domain manager as the user, who has the right to ADD jobs 2. Create a text file with content similar to that shown in Example 7-28.
Example 7-28 UNIX branch job definition
$JOBS SYDNEY#BRANCH SCRIPTNAME "/opt/ibm/tws_scripts/branch.sh" STREAMLOGON tws TASKTYPE UNIX RECOVERY STOP SYDNEY#SIGNAL SCRIPTNAME "/opt/ibm/tws_scripts/branch.sh"
500
STREAMLOGON tws TASKTYPE UNIX RECOVERY CONTINUE Important: In our scenario, we have worked on the master domain manager called SYDNEY. Change the occurrence of the string SYDNEY to the name of your master domain manager. We put the scripts into the /opt/ibm/tws_scripts/ directory. Instead of this value, use the directory where you have placed the branch.sh shell script. We use tws as the user under whom the Tivoli Workload Scheduler has been installed. Replace this string with the user under whom you have installed your Tivoli Workload Scheduler master domain manager. You must have all three mentioned values entered correctly before you run the composer command. Both job definitions point to the same file. They differ only in names and value for the Recovery Option. 3. Save the file somewhere on your file system. Remember the full path to the file. Go to your Tivoli Workload Scheduler installation directory and run the following commands: a. . ./tws_env.sh: To source the Tivoli Workload Scheduler environment b. composer add <your_definition_file>: To import the definition from file to the Tivoli Workload Scheduler database, where <your_definition_file> is the name of the file that you have created in the previous step. Do the following steps for the Windows master domain manager: 1. Log on to the master domain manager as the user who has the right to ADD jobs. 2. Create a text file with the content shown in the Example 7-29.
Example 7-29 Windows branch job definition
$JOBS HELSINKI#BRANCH SCRIPTNAME "c:\cygwin\bin\bash \"c:/Program Files/IBM/tws/tws/scripts/branch.sh\"" STREAMLOGON tws TASKTYPE WINDOWS RECOVERY STOP $JOBS
501
HELSINKI#BRANCH SCRIPTNAME "c:\cygwin\bin\bash \"c:/Program Files/IBM/tws/tws/scripts/branch.sh\"" STREAMLOGON tws TASKTYPE WINDOWS RECOVERY CONTINUE Important: In our scenario, we have worked on the master domain manager called HELSINKI. Change the string HELSINKI to the name of your master domain manager. We use the c:\cygwin directory as the directory where Cygwin is installed. If you have installed Cygwin into another directory, or if you are using another shell interpeter, supply the correct value here. We use the value \c:/Program Files/IBM/tws/tws/scripts/branch.sh\ as a pointer to the shell script located on the Windows file system. We use the forward slashes in the path because Cygwin understands this notation. Because we use the directory name that contains the space character, we must use the double quotes. Each of them must be contained by the backslash character. If you use the directory that does not include a space within its name, you do not need to use quotes or backslashes. We use tws as the user under whom the Tivoli Workload Scheduler has been installed. Replace this string with the user under whom you have installed your Tivoli Workload Scheduler master domain manager. You must have all four mentioned values entered correctly before you run the composer command. Both job definitions point to the same file. They differ only in the names and values for the Recovery Option. 3. Save the file somewhere into your file system. Remember the full path to the file. Go to the %TWS_HOME% directory and run the following commands: a. tws_env.cmd: To source the Tivoli Workload Scheduler environment. b. composer add <your_definition_file>: To import the definition from file to the Tivoli Workload Scheduler database, where <your_definition_file> is the name of the file that you have created in the previous step.
502
7.4.4 Placing the branch job into the job stream

The steps in this section describe how to place the generic branch job into the job stream. We use the Job Scheduling Console for this task.
General rules
You must follow a few simple rules in order to place the branch job into the job stream correctly: You have only one branch job definition in the database, as described in 7.4.3, Branch job definition and signal job definition in the database on page 493. When you are inserting the branch job into the job stream, you must give it an alias that describes the branch jobs positioning within the job stream. The first branch job should have the name BRANCH_1. The second branch job should have the name BRANCH_2. And so on. Figure 7-39 on page 504 shows an example of the branch job suffix within the branch job alias.
503
Figure 7-39 Branch job suffix within the branch job alias
Rules valid for all scenarios except the SIGNAL action scenario
The following steps describe all the possible scenarios of branch job usage, except for the SIGNAL action scenario: 1. The branch job must have only one predecessor. Draw the FOLLOWS dependency from the job that you want to evaluate to the corresponding branch job. 2. The branch job must have exactly two children: a. Draw the dependency from the branch job to the good child. b. Rename the good child so that its name begins with the G_ prefix. c. Draw the dependency from the branch job to the bad child.
504
d. Rename the bad child so that its name begins with the B_ prefix. Figure 7-40 shows an example of the process.
Figure 7-40 Common placing of the branch job into the job stream
505
Rules valid for the SIGNAL action scenario

The following steps describe the usage of the branch job in the SIGNAL action scenario: 1. You must use two sequentially ordered jobs: Signal job Branch job 2. Place these jobs into the job stream as follows: a. Insert the signal job into the job stream and give it the correct suffix. b. Insert the branch job into the job stream and give it the correct suffix. Note: The name of the signal job starts with string SIGNAL and the name of the branch job starts with the string BRANCH. Therefore, both jobs can have the same suffix. For example, they can be named SIGNAL_1 and BRANCH_1. 3. The signal job must have only one child. This child is the subsequent branch job. Draw the FOLLOWS dependency from the signal job to the subsequent branch job. Note: The signal job must have set the input parameter ACTION_SWITCH=SIGNAL. See 7.5, Working with the branch job parameters on page 509 for more information about branch job parameters. 4. The signal job must have set the flag Requires Confirmation. Edit the branch jobs properties within the job stream editor and check the flag Requires confirmation, as shown in Figure 7-41 on page 507.
506
Figure 7-41 Setting the flag Requires Confirmation for the first branch job
5. The signal job must have only one predecessor. Draw the FOLLOWS dependency from the job that you want to evaluate to the signal job. 6. Draw the FOLLOWS dependency from the signal job to the subsequent branch job. 7. The branch job must have exactly two children: a. Draw the dependency from the branch job to the good child. b. Rename the good child so that its name begins with the G_ prefix. c. Draw the dependency from the branch job to the bad child. d. Rename the bad child so that its name begins with the B_ prefix.
507
Figure 7-42 shows an example of these steps.
Figure 7-42 Placing jobs into the job stream for the SIGNAL action scenario
7.4.5 Using the ABEND job

This section describes the term ABEND, which we have mentioned in the sections related to pause/release scenarios. Actually, the usage of the ABEND job is useful in any scenario where we want to propagate the ABEND state of the job stream status. If something bad occurs in your job stream and this is detected by the particular branch job, you may want to propagate this bad state also on the job stream level. This can be accomplished by putting the ABEND job into the bad branch following the branch job. The ABEND job just calls system command exit 1. This causes the job to ABEND. Having an ABEND job in the bad branch ensures that the ABEND status also will be propagated on the job stream level. Any of the previously ABENDed jobs will not propagate the ABEND state on the job stream level if they have the recovery option set to Continue. Actually, all the branch job parents that are evaluated
508
against their status need to have set the recovery option=Continue in order to be able to allow the branch job to run. That is why the abended jobs would not propagate their status on the job stream level (jobs with recovery option=Continue do not do so), so you need to use the special ABEND job for this purpose. You can see an example of the ABEND job in Figure 7-40 on page 505.
7.4.6 Passing the input parameters to the branch job

The most often used scenario does not require any input parameters. Branching based on the PARENT_SUCCESS status requires the correct placing of the branch job into the job stream. However, any other branching scenarios require at least one parameter to be specified. Because understanding the branch job input parameters is a complex task, we have dedicated 7.5, Working with the branch job parameters on page 509 to this task.
7.5 Working with the branch job parameters

This section provides detailed instructions for working with the generic branch job parameters. Passing parameters to the branch job is straightforward. All the parameters are written directly into the job stream that contains the affected branch job. The parameters are put into the Comments field in the job stream editor. Figure 7-43 on page 510 shows how the parameters are defined for multiple branch jobs within one job stream.
509
Figure 7-43 Parameters for multiple branch jobs within one job stream
Note: Do not confuse the job streams Comments field with the job streams Description field.
510
7.5.1 Putting a parameter into job stream Comments field

This section shows you how to insert the correct name of a parameter into the job streams Comments field. We also explain how to distinguish parameters that belong to different branch jobs. We explain the syntax of parameter separators and then we explain how to construct each particular parameter.
Separator syntax
In this section, we describe how to construct parameter separators. Parameter separators are necessary, even if you specify parameters for only one branch job. Parameters for each branch job must be enclosed by parameter separators. There is a begin separator and an end separator. You must enter all the parameters related to a single branch job between the begin separator and the end separator. Both separator names must follow the strict syntax. The separators are constructed as follows: Begin separator: Consists of a variable part that represents the name of the branch job and the fixed part -BEGIN. The generic syntax of the begin separator is <branch_job_name>-BEGIN. The sample begin separator may look like BRANCH_1-BEGIN. End separator: Consists of a variable part that represents the name of the branch job and the fixed part -END. The generic syntax of the begin separator is <branch_job_name>-END. The sample begin separator may look like BRANCH_1-END. The parameters belonging to one job must be put between these two separators. This is a necessary requirement.
Separator examples for branch jobs

In this section, we demonstrate the sample parameter sets together with their separators.
511
Example 7-30 shows a sample parameter set definition.

Example 7-30 Sample parameter set put inside the separators
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=Error NEGATE_CONDITION_RESULT_1=YES PATTERN_2=Free space on Primary device VALUE_2=50 ARITHMETICAL_OPERATOR_2=-gt BOOLEAN_OPERATOR_2=&& PATTERN_3=Free space on Secondary device VALUE_3=60 ARITHMETICAL_OPERATOR_3=-gt BOOLEAN_OPERATOR_3=|| BRANCH_1-END Example 7-31 demonstrates the sample parameter definition for a job stream that uses two branch jobs.
Example 7-31 Sample parameters definition for job stream with two branch jobs
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=Error NEGATE_CONDITION_RESULT_1=YES PATTERN_2=Free space on Primary device VALUE_2=50 ARITHMETICAL_OPERATOR_2=-gt BOOLEAN_OPERATOR_2=&& PATTERN_3=Free space on Secondary device VALUE_3=60 ARITHMETICAL_OPERATOR_3=-gt BOOLEAN_OPERATOR_3=|| BRANCH_1-END BRANCH_2-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=Backup of Primary device VALUE_1=ERROR NEGATE_CONDITION_RESULT_1=YES BRANCH_2-END
512
Note: The empty lines between two parameter sets are not necessary, but they make the definition more readable.
Special note about separators for SIGNAL jobs

Signal jobs are a special variation of the common branch job. Because the name of any signal job must start with the string SIGNAL, the parameter separators also must keep this syntax. The sample separators for a signal job with name SIGNAL_1 are shown in Example 7-32.
Example 7-32 Separator syntax for SIGNAL jobs
SIGNAL_1-BEGIN ACTION_SWITCH=SIGNAL SIGNAL_1-END
7.5.2 Parameters reference

This section explains the syntax and meaning of possible branch job parameters. There are two types of parameters: Fixed parameters: Parameters of this type may appear only once for each job. A typical example of this parameter type is CONDITION_SWITCH. Indexed parameters: Parameters of this type may appear multiple times for one job, or do not need to appear at all. A typical example of this parameter type is PATTERN_i (where i is the index).
Fixed parameters
The following list contains all the possible fixed parameters with their possible values: CONDITION_SWITCH: Specifies the type of condition that is run against the parent. PARENT_SUCCESS: This condition is TRUE if the parent ended with the SUCC state. The most simple usage of this condition is demonstrated in 7.3.1, Scenarios based on condition type on page 413. This is the default value. If the parameter CONDITION_SWITCH is not specified, then the parameter value CONDITION_SWITCH=PARENT_SUCCESS is considered.
513
PARENT_ABEND: This condition is TRUE if the parent ended with the ABEND state. This condition is demonstrated in 7.3.5, Parent abend on page 427. COMPLEX: This condition is built from one or multiple sub-conditions connected with Boolean operators (AND/OR) and is evaluated with Boolean logic. The complex condition is demonstrated in 7.3.12, Complex scenario - multiple conditions on page 458. ACTION_SWITCH: This parameter specifies what to do with the stop branch. Possible actions are as follows: CANCEL: The stop branch is cancelled. We have demonstrated this action in most scenarios. This is the default value. If the parameter ACTION_SWITCH is not specified, then the parameter value ACTION_SWITCH=PARENT_SUCCESS is considered. PAUSE: The stop branch is paused. We explain the usage of the pause/release approach in 7.3.15, Pause/Release actions scenario on page 467. SIGNAL: No branch is being cancelled. Only the recommendation for operators confirmation is printed. We explain the usage of the pause/release approach in 7.3.17, Signal action scenario on page 479.
Indexed parameters
Indexed parameters are used only together with the fixed parameter CONDITION_SWITCH=COMPLEX; otherwise, they are ignored during the branching process.
The complex condition and sub-conditions

If the fixed parameter CONDITION_SWITCH=COMPLEX is specified, the branch job will evaluate a complex condition. The complex condition consists of one or more sub-conditions. Each sub-condition has its own index. An index starts with the number 1 and is incremental. Each sub-condition must have defined at least one Pattern_i parameter. The i suffix represents the relationship between the sub-condition and the corresponding parameter. The suffix looks like <indexed_parameter_name>_i, where _i is the suffix.
514
An example of a parameter name is as follows: PATTERN_2=find this row and number on this row VALUE_2=50 ARITHMETICAL_OPERATOR_2=-lt These three parameters belong to the same sub-condition (the second sub-condition within the complex condition). Their affinity is expressed by the same suffix, _2, which represents the index of the sub-condition. Parameters related to one sub-condition are grouped together using the same index. Sub-conditions are evaluated separately. They then are connected together (using Boolean operators) and the complex condition is evaluated. Note: When working with the branch job parameter, just specify the parameters. By specifying parameters with a suffix, you are also defining the sub-condition. There is no separate place for entering sub-conditions.
Index usage examples

The examples in this section explain the meaning of the index used in the parameter names. Example 7-33 demonstrates what the parameters would look like if you needed to specify three patterns that must be found in the parents joblog. As you can see, the index acts as the incremental counter. The parameters in Example 7-33 belong to three separate sub-conditions.
Example 7-33 Parameter index - incremental counter
PATTERN_1=first pattern to find PATTERN_2=second pattern to find PATTERN_3=third pattern to find Another notation is used for the parameters related to one sub-condition, for example, searching for a pattern, then for a number on the same row and the subsequent arithmetical comparison. The number and arithmetical operator are supplied as the input parameters.
515
The parameters for this task would look like the ones shown in Example 7-34. As you can see, all related parameters share the same index.
Example 7-34 Parameter index - incremental counter
PATTERN_1=Free space on Primary device VALUE_1=50 ARITHMETICAL_OPERATOR_1=-gt
Indexed parameters meaning

The following list contains all the possible indexed parameters with their possible values. All of these parameters can be used to create a single sub-condition. PATTERN_i: Search for the text pattern (for example, ended successfully). If the pattern is found, the condition result is TRUE. Related parameters can be specified for the PATTERN_i parameter. The following parameters are dependent on the PATTERN_i parameter. If the PATTERN_i parameter is not present, the following parameters with the same index are ignored. VALUE_i: Can be either STRING or NUMERIC (determined automatically when reading the particular value parameter during the branch job startup). The content of the parameter VALUE_i is searched for within the same row that has been identified during the search for the related string specified by the parameter PATTERN_i. There are two possible value types and they are determined automatically by parsing the content of the VALUE_i parameter: String value: Searches for another text pattern within the same row (this row has been identified in the previous step when the content of the PATTERN_i was found). If both patterns have been found within the same row, the condition result is determined as TRUE. This functionality has been demonstrated in 7.3.9, Complex branch Pattern within pattern row on page 442. Numeric value: Searches for the numeric value within the same row (this row has been identified in the previous step when the content of the PATTERN_i was found). The defined arithmetical operator (like greater than or equal, and so on) is then used to perform the arithmetical comparison. If the arithmetical comparison succeeded, the condition is TRUE. A dedicated arithmetical operator is defined for each numeric value.
516
This functionality has been demonstrated in 7.3.11, Complex branch Numeric value comparison on page 452. ARITHMETICAL_OPERATOR_i: Used for arithmetical comparison. This functionality is described in the previous bullet. NEGATE_CONDITION_RESULT_i: This argument negates the result of the particular sub-condition. That means it swaps the TRUE/FALSE result of the sub-condition. BOOLEAN_OPERATOR_i: The defined sub-conditions are joined together by the Boolean operator (AND/OR). The Boolean operator can be used because i=2. This means that the index of the Boolean operator must be at least 2. For example, we have two parameters in the list. Each of them represents one atomic sub-condition. Each of those sub-conditions is evaluated separately and their result is returned either as TRUE or FALSE. In order to be able to evaluate the whole condition, we must join the particular results together. The meaning of the BOOLEAN_OPERATOR_i parameter is that the connect result of this sub-condition to the result of the preceding sub-condition uses the Boolean operator AND/OR (value of the BOOLEAN_OPERATOR_i parameter).
Reference tables
This section includes reference tables for branch job parameters. The parameter references are shown in Table 7-10.
Table 7-10 Parameters reference table Parameter name CONDITION_SWITCH Possible values PARENT_SUCCESS PARENT_ABEND COMPLEX CANCEL PAUSE SIGNAL Any string Any string Any numeric value (integer or real) Default value PARENT_SUCCESS
ACTION_SWITCH
CANCEL (for branch jobs) SIGNAL (for signal jobs)
PATTERN_i, where i is the incremental index VALUE_i, where i is the incremental index
517
Parameter name ARITHMETICAL_OPERATOR_i, where i is the incremental index
Possible values -lt -le -eq -ne -ge -gt YES NO YES NO YES NO && ||
Default value -eq
IS_CASE_SENSITIVE_i, where i is the incremental index IS_REGULAR_EXPRESSION_i, where i is the incremental index NEGATE_CONDITION_RESULT_i, where i is the incremental index BOOLEAN OPERATOR_i, where i is the incremental index
YES NO NO &&
Note: The default values shown in Table 7-10 on page 517 are used when they are not supplied as input parameters. For the most common usage of the generic branch job, CONDITION SWITCH=PARENT_SUCCESS and ACTION_SWITCH=CANCEL are used. So, if the parameters for a particular branch job has are not defined, the default values are used and the branch job just evaluates the status of its parent and cancels the stop branch. The values for arithmetical and boolean operators use UNIX notation. Their meaning is explained in Table 7-11.
Table 7-11 Arithmetical operators explanation Parameter UNIX value -lt -le -eq -ne -ge -gt && Parameter value interpretation < <= = != >= > AND Parameter value meaning Less than Less or equal Equal Not equal Greater or equal Greater than Logical AND
518
Parameter UNIX value ||
Parameter value interpretation OR
Parameter value meaning Logical OR
Note: When specifying the parameters, it is necessary to use the exact syntax in Table 7-10 on page 517. We stress this fact especially for the arithmetical operators; you must include the preceding dash sign (-).
7.5.3 Case sensitivity

This section briefly lists which parts of the parameter entries are case sensitive and which are not. The parameter names are not case sensitive. The values of fixed parameters are not case sensitive. The patterns that you want to search in the parents joblog are case sensitive. You can override this behavior by specifying the following parameter: IS_CASE_SENSITIVE_i=NO where i represents the current sub-condition index. For example, for the following parameter: PATTERN_2=some text you would switch the case sensitive pattern search by supplying this additional parameter: IS_CASE_SENSITIVE_2=NO If you are searching for two patterns within the same row, this parameter affects both of them. The branch job separators that you must use during parameter sets definitions are case sensitive. The separators must be in uppercase letters. If this condition is not met, the parameters will not be read and the default values will be used.
519
7.5.4 Sample condition examples

In the previous sections, we explained the following terms: Parameter separators Parameters Fixed parameters Indexed parameters Index Parameter suffix Complex condition Sub-condition Now we use this knowledge to demonstrate how to construct simple or more complex parameter sets.
Simple branch, Long branch scenarios

This functionality uses the default values: CONDITION_SWITCH=PARENT_SUCCESS ACTION_SWITCH=CANCEL You do not need to specify any input parameters for these scenarios. The default values are supplied automatically by the branch job.
Pause action
This functionality needs at least one fixed parameter. You must use at least two branch jobs to implement the pause/release scenario. In order to use the pause/release functionality, you must override the default behavior for the first branch job. We provide the complete syntax together with the parameter separators in Example 7-35. The name of the branch job in this example is BRANCH_1. If the name of your branch job has a different suffix (for example, BRANCH_5), you must adjust the separator names. The second branch job in the pause/release approach does not need any input parameters if it is dependent only on its parents status (SUCC).
Example 7-35 Pause/Release scenario - parameters definition
BRANCH_1-BEGIN ACTION_SWITCH=PAUSE BRANCH_1-END
520
As you can see, we did not supply any indexed parameters. Indexed parameters may be used only in combination with the fixed parameter CONDITION_SWITCH=COMPLEX. Because the parameter CONDITON_SWITCH is not included, the default value CONDITION_SWITCH=PARENT_SUCCESS has been used. The combination of the pause action together with the complex condition is described in Combination of pattern search and pause action on page 524 and Complex condition with pause action on page 525.
Single pattern search

This functionality is represented by one sub-condition and needs one fixed and one indexed parameter. We provide the complete syntax together with the parameter separators in Example 7-36. The name of the branch job in this example is BRANCH_1. If the name of your branch job has a different suffix (for example, BRANCH_5), you must adjust the separator names.
Example 7-36 Single pattern search - parameters definition
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=find this text BRANCH_1-END As you can see, there is only one indexed parameter representing the only one sub-condition.
Negated pattern search

This functionality is represented by one sub-condition and needs one fixed and two indexed parameters. We provide the complete syntax, together with the parameter separators, in Example 7-37. The name of the branch job in this example is BRANCH_1. If the name of your branch job has a different suffix (for instance BRANCH_5), you must adjust the separator names.
Example 7-37 Negated pattern search - parameters definition
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=do not find this text NEGATE_CONDITION_RESULT_1=YES BRANCH_1-END
521
As you can see, both indexed parameters have the same suffix, because they belong to the same sub-condition.
Multiple pattern search

This functionality is represented by several sub-conditions and needs one fixed and several indexed parameters. In this example, we search for two independent patterns within the parents joblog. We must create two separate sub-conditions, each with its own index (1 and 2). We must also specify if both patterns must be found (using the Boolean operator AND) or if finding at least one pattern is sufficient (Boolean operator OR). We provide the complete syntax, together with the parameter separators, in Example 7-38. The name of the branch job in this example is BRANCH_1. If the name of your branch job has a different suffix (for example, BRANCH_5), you must adjust the separator names.
Example 7-38 Multiple pattern search - parameters definition
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=find this text PATTERN_2=find also this text BOOLEAN_OPERATOR_2=&& BRANCH_1-END As you can see, the indexed parameters have different suffixes. The parameter PATTERN_1 belongs to first sub-condition and the parameter PATTERN_2 belongs to the second sub-condition. The parameter BOOLEAN_OPERATOR_2 specifies how the second sub-condition will be joined to the first sub-condition.
Pattern within pattern search

This functionality is represented by one sub-condition and needs one fixed and two indexed parameters. In this example, we search for the text pattern within the parents joblog. Then we search for another pattern within the same row. All the indexed parameters belong to one sub-condition.
522
We provide the complete syntax, together with the parameter separators, in Example 7-39. The name of the branch job in this example is BRANCH_1. If the name of your branch job has a different suffix (for example, BRANCH_5), you must adjust the separator names.
Example 7-39 Pattern search with numeric comparison - parameters definition
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=find this text VALUE_1=and also this text on the same row BRANCH_1-END As you can see, both indexed parameters have the same suffix, because they belong to the same sub-condition.
Pattern search with numeric comparison

This functionality is represented by one sub-condition and needs one fixed and three indexed parameters. In this example, we search for a text pattern within the parents joblog. Then we search for a number within the same row. We want to compare this number against another number that we supply as the input parameter. For the arithmetical comparison, we use the arithmetical operator that we supply as the input parameter as well. All the indexed parameters belong to one sub-condition. We provide the complete syntax, together with the parameter separators, in Example 7-40. The name of the branch job in this example is BRANCH_1. If the name of your branch job has a different suffix (for example, BRANCH_5) you must adjust the separator names.
Example 7-40 Pattern search with numeric comparison - parameters definition
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=Total backup size VALUE_1=500 ARITHMETICAL_OPERATOR_1=-lt BRANCH_1-END As you can see, all three indexed parameters have the same suffix, because they belong to the same sub-condition.
523
Here we explain, in semi-programmatical language, the meaning of the functionality invoked by the parameters specified in Example 7-40 on page 523: Get parents joblog. Extract the row containing string Total backup size. If (row found): Then return continue with the next step Else return FALSE Try to extract numeric value from the row. If (number found): Then continue with the next step Else return FALSE If (number_from_joblog < 50): Then return TRUE Else return FALSE
Combination of pattern search and pause action

The intent of this section is to combine a non-default condition with a non-default action. This means that we use entries for both CONDITION_SWITCH and ACTION_SWITCH in this scenario. We demonstrate how to combine single pattern searching together with the pause action. This functionality is represented by one sub-condition and needs two fixed parameters and one indexed parameter. We provide the complete syntax, together with the parameter separators, in Example 7-41. The name of the branch job in this example is BRANCH_1. If the name of your branch job has a different suffix (for example, BRANCH_5), you must adjust the separator names.
Example 7-41 Combination of pattern search / pause action - parameters definition
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX ACTION_SWITCH=PAUSE PATTERN_1=find this text BRANCH_1-END
524
As you can see, we have overridden both fixed parameters. The one indexed parameter belongs to the one sub-condition.
Signal action
The intent of this section is to demonstrate the different separators that are necessary for the signal scenario. In the signal scenario description, we have mentioned that two jobs are managing the job streams workflow: The signal job The branch job Only the signal job uses the input parameters. The name of the signal job consists of the string SIGNAL and the suffix, so the parameter separators look different. Also, for the signal job, the common rules are valid. The parameter separators must look exactly like the related job name. We demonstrate this difference together with the parameters for the signal action. We combine this action with the condition based on the pattern search within the parents joblog. The signal functionality is represented by one fixed parameter. The pattern search needs one fixed parameter for the condition type and one indexed parameter specifying the pattern search. We provide the complete syntax, together with the parameter separators, in Example 7-41 on page 524. The name of the branch job in this example is BRANCH_1. If the name of your branch job has a different suffix (for example, BRANCH_5), you must adjust the separator names.
Example 7-42 Signal action combined with pattern search - parameters definition
SIGNAL_1-BEGIN CONDITION_SWITCH=COMPLEX ACTION_SWITCH=SIGNAL PATTERN_1=find this text SIGNAL_1-END
Complex condition with pause action

Here we combine the complex condition with the non-default action. The complex condition that is presented in this section has already been shown in 7.3.12, Complex scenario - multiple conditions on page 458.
525
In addition, we combine this complex condition with the pause action. We provide the complete syntax, together with the parameter separators, in Example 7-41 on page 524. The name of the branch job in this example is BRANCH_1. If the name of your branch job has a different suffix (for example, BRANCH_5), you must adjust the separator names.
Example 7-43 Combination of complex condition and pause action - parameters definition
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX ACTION_SWITCH=PAUSE PATTERN_1=Error NEGATE_CONDITION_RESULT_1=YES PATTERN_2=Free space on Primary device VALUE_2=50 ARITHMETICAL_OPERATOR_2=-gt BOOLEAN_OPERATOR_2=&& PATTERN_3=Free space on Secondary device VALUE_3=60 ARITHMETICAL_OPERATOR_3=-gt BOOLEAN_OPERATOR_3=|| BRANCH_1-END The meaning of the definition above is as follows: Sub-condition_1: If you find pattern Error, return FALSE, else return TRUE. (The inverted result is accomplished by the NEGATE_CONDITION_RESULT_1 parameter.) Sub-condition_2: Search for the row containing Free space on Primary device. Extract the number from this row. If the number is greater than 50, return TRUE, else return FALSE. Sub-condition_3: Search for the row containing Free space on Secondary device. Extract the number from this row. If the number is greater than 60, return TRUE, else return FALSE. Join all these three sub-conditions using Boolean operators so that the complex condition is constructed as follows: If (sub-condition_1 = TRUE) AND (sub-condition_2=TRUE) OR (sub-condition_3=FALSE) Then return TRUE Else return FALSE
If (complex_condition_result=TRUE)
526
Then CANCEL bad_branch Else PAUSE the good_branch
If you are unsure about the pause/release concept, refer to 7.3.15, Pause/Release actions scenario on page 467.
Multiple branch jobs within one job stream

The intent of this section is to demonstrate how to define parameters for more branch jobs that are defined in the same job stream. We have already explained how to construct a parameter set belonging to one particular branch job. Having more than one branch job within a job stream means that the different parameter sets are enclosed by different separators. We provide the complete syntax, together with the parameter separators, in Example 7-44. The names of the branch jobs in this example are BRANCH_1 and BRANCH_2. If the name of your branch jobs have different suffixes (for example, BRANCH_5 and BRANCH_6), you must adjust the separator names.
Example 7-44 Multiple branch jobs within one job stream - parameters definition
BRANCH_1-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=Error NEGATE_CONDITION_RESULT_1=YES PATTERN_2=Free space on Primary device VALUE_2=50 ARITHMETICAL_OPERATOR_2=-gt BOOLEAN_OPERATOR_2=&& PATTERN_3=Free space on Secondary device VALUE_3=60 ARITHMETICAL_OPERATOR_3=-gt BOOLEAN_OPERATOR_3=|| BRANCH_1-END BRANCH_2-BEGIN CONDITION_SWITCH=COMPLEX PATTERN_1=Backup of Primary device VALUE_1=ERROR NEGATE_CONDITION_RESULT_1=YES BRANCH_2-END Note: The empty lines between separators are not necessary, but they make the definition more readable.
527
7.6 Important notes about the branch job

This section highlights some considerations and assumptions for the generic branch job design: The name of the branch job within the database is BRANCH. The job must have set the property Recovery options = STOP. The name of the signal job within the database is SIGNAL. The job must have set the property Recovery options = CONTINUE. The name of the branch job put into the job stream must consist of the branch job name (BRANCH) and the suffix. The suffix should reflect the branch job position in the job stream. For example, BRANCH_3 is the name of the third branch job within the job stream. The name of the signal job put into the job stream must consist of the signal job name (SIGNAL) and the suffix. The suffix should reflect the signal job position in the job stream. For example, SIGNAL_3 is the name of the third signal job within the job stream. The suffix counter for signal jobs is different from the suffix counter of branch jobs. It means that jobs BRANCH_3 and SIGNAL_3 can exist within one job stream at the same time, even if their suffix is identical. The branch job has only one parent. This means that the branch job must have the FOLLOWS dependency set exactly on one job in the same job stream. This is checked during the branch job startup. If this condition is not fulfilled, then the branch job ABENDS. Connecting the branch job to more parents is stopped by the branch job and will cause the branch job to ABEND. The parent that is evaluated against the result status (SUCC/ABEND) must have the following property set: Recovery options = Continue This property can be only set in the job definition, not in the job stream definition. For the following branch job usage scenarios, the branch job must have exactly two children: ACTION_SWITCH = CANCEL (default value) ACTION_SWITCH = PAUSE These children must be identified as the good child and the bad child. The children names must be as follows:
528
The job that represents the good child must have a name beginning with G_. It is not necessary to rename the job definition. Renaming the jobs alias within the job stream is sufficient. Example: The job name in the database is START_BACKUP. If we wanted to use this job as the good child of the branch job, we put this job into the job stream and inside of the job stream we give the job the alias G_START_BACKUP. The job that represents the bad child must have a name beginning with B_. It is not necessary to rename the job definition. Renaming the jobs alias within the job stream is sufficient. Example: The job name in the database is RESUME_DATABASE. If we wanted to use this job as the bad child of the branch job, we put this job into the job stream and inside of the job stream and give the job the alias of B_START_BACKUP. The count of the branch jobs children and their correct prefixes are checked during the branch job startup. If these conditions are not fulfilled, then the branch job ABENDS. The use of quote characters is not implemented in the current version of the branch job. If you specify quote characters in either in the PATTERN_i or the VALUE_i parameters, the quote characters are automatically removed. When evaluating the complex condition, the initial search parameter is a text pattern. This text pattern is searched for in the parents joblog. If there are more lines that include the searched pattern, only the first matched line is identified. The other matched lines are ignored. The content of the first identified line is then evaluated by another sub-condition, as shown in the scenarios pattern within pattern row or numeric value comparison. When extracting the numeric value from the pattern row, there can be only one numeric value in the row. The numeric values of integer and real type are accepted. More numbers in the identified pattern row will result in incorrect numeric value extraction; all numbers from the row will be joined together and will not represent a meaningful value. For the case where we use the signal scenario, the signal job must have exactly one child. The child must have a subsequent branch job and its name must comply with the naming conventions for the generic branch job. The signal scenario is described in 7.3.17, Signal action scenario on page 479.
529
When using the PAUSE/RELEASE action pair, the process is as follows: The first branch job sets the priority of job that is about to be paused to 0. The second branch job sets the priority of job that is about to be released to 10. This functionality is hardcoded. So far, there is no implemented mechanism that would allow you to remember the original jobs priority. All the information about the job stream, in which the branch job runs, is extracted from the database using the composer command when the branch job starts. This means that the branch job does not reflect any job instances that have been submitted into the job stream but do not exist in the job stream definition. Important: The generic branch job is not the native part of the Tivoli Workload Scheduler and is not supported by IBM Software Support. It is provided as is without any warranty. We strongly recommend using the branch job in your testing environment first. The same recommendation is valid also for the sample scenarios. Only after you produce an error-free run of the branch job/sample scenarios should you move to the production environment.
7.7 Sample scenarios installation

This section describes how to install the sample generic branch job scenarios that are shipped together with the branch job shell script. The scenarios are shipped together with the branch job shell script in one package. There are separate packages for the UNIX and Windows platforms. The packages can be downloaded from the ITSO Web site. Refer to Appendix D, Additional material on page 615 for instructions on how to download the code. The file names are as follows: SG247528_Unix.tar: For the UNIX platform SG247528_Windows.zip: For the Windows platform We describe the installation steps for each platform separately.
530
Important: Prior to the sample scenarios installation, you must complete the steps described in 7.4.2, Branch job shell script installation on page 489 and 7.4.3, Branch job definition and signal job definition in the database on page 493. If you do not perform these tasks, the installation process will fail. The job stream definitions point to the job definitions for branch job and signal job. If these definitions do not exist in the Tivoli Workload Scheduler database prior to importing the scenario job stream definitions, the installation process will fail. Before we do the sample scenarios installation steps, we describe the content of the installation packages:
7.7.1 Installation packages content

This section describes the content of the installation packages. The installation packages are archive files (tar for the UNIX platform and zip for the Windows platform). We list the contents here: generic_branch_job (directory): The root directory included in the package. It includes: scenario_installer.sh (file): Sample scenarios installation script. Definitions (directory): Contains job and job streams templates, and serves as the working directory for creating the exact definition files for the composer. gbj_job.templates (file): Job definition templates. The installation script takes the templates as inputs and based on user input creates adjusted definition files for the composer command. gbj_sched.templates (file): Job stream definition templates. The installation script takes the templates as inputs and based on user input creates adjusted definition files for the composer command. scenario_scripts (directory): Script files that are used by Tivoli Workload Scheduler scenario jobs. The purpose of these scripts is to produce text output that will be parsed by the branch jobs in particular scenarios. Scripts for the UNIX platform have the .sh extension, while the Windows batch files have the .cmd extension. branch (directory): Contains the branch job shell script. branch.sh: The branch job shell script itself.
531
We are not interested in this shell script at this time. You should have the branch job already installed. If you do not, follow the instructions described in 7.4.2, Branch job shell script installation on page 489.
7.7.2 Installation on UNIX

You must perform the following steps in order to install the sample scenarios on the UNIX platform: 1. Download the file generic_branch_job.tar. 2. Transfer the file to your master domain manager. 3. Log in as the TWS_USER (owner of the master domain manager instance). 4. Save the file to a directory where the TWS_USER has full read/write/execute permissions. 5. Go to the directory where you saved the file. 6. Unpack the package by entering tar xvf generic_branch.job.tar. The directory tree generic_branch_job will be created. The content of the installation package for UNIX platforms is shown in Example 7-45.
Example 7-45 Content of the installation package for UNIX platforms
generic_branch_job generic_branch_job/branch generic_branch_job/branch/branch.sh generic_branch_job/definitions generic_branch_job/definitions/gbj_job.templates generic_branch_job/definitions/gbj_sched.templates generic_branch_job/scenario_installer.sh generic_branch_job/scenario_scripts generic_branch_job/scenario_scripts/gbj_pattern.sh generic_branch_job/scenario_scripts/gbj_pattern_pattern.sh generic_branch_job/scenario_scripts/gbj_pattern_pattern_error.sh generic_branch_job/scenario_scripts/gbj_multiple_conditions.sh generic_branch_job/scenario_scripts/gbj_pattern_error.sh generic_branch_job/scenario_scripts/gbj_pattern_number.sh Note: As you can see, the branch job shell script file branch.sh is also present in the package. However, we are not interested in it at this time. You should have the branch job already installed. If you do not, follow the instructions described in 7.4.2, Branch job shell script installation on page 489.
532
7. Make sure that you have the full read/write/execute permission within the directory tree. If not, adjust either the ownership or permissions of the generic_branch.job directory. This must be done recursively. Note: In most cases, this step is not necessary. But if you experience troubles with running the installation script, perform some or all of the following commands while you are on the level above the generic_branch_job directory: chown -R TWS_USER generic_branch_job chmod +x generic_branch_job/scenario_installer.sh chmod -R +w generic_branch_job/definitions 8. Source the Tivoli Workload Scheduler command line environment. This can be done by running. $TWS_HOME/tws_env.sh, where $TWS_HOME is the installation directory of your master domain manager. Do not forget to enter the preceding dot. Without sourcing the Tivoli Workload Scheduler command-line environment, the installation script will not run. 9. Run the installation script. Go to the directory generic_branch_job and issue: ./scenario_installer.sh 10.The installer automatically detects the value of the master domain manager and the TWS_USER (in fact, it detects just the current user, but you should be logged in as the TWS_USER). These values will be suggested to you by the installation prompts. 11.The installer will ask you for following values: Master domain manager name. TWS_USER (owner of the Tivoli Workload Scheduler master instance). Installation path, where you want to place the sample scenarios scripts. You must select an existing directory where you have the permissions to read/write/execute. During the prompt phase, you have the chance to correct your inputs. The installation will not start until you confirm that the input values are correct. If you do not confirm them, you will be asked for all three values again. You do not need to retype the correct values because all values are remembered. After entering the third value, you will be again asked for the confirmation. During the confirmation prompt, you may also enter quit and exit the installation process.
533
12.After you confirm the input values, the installation will start. The sample scenarios scripts are copied into the target directory. Based on the template files combined with the input values, the installation script will create exact definition files for Tivoli Workload Scheduler by using the composer command. The composer replace command is invoked for the job definitions and for the stream definitions. If everything went well, you will have successfully installed the sample scenarios for the generic branch job. Example 7-46 shows an extract from the text output of the installation process.
Example 7-46 Sample scenarios installation - UNIX
tws@sydney:/usr/tws/generic_branch_job#./scenario_installer.sh ============================================== === START of sample scenarios installation === ==============================================
MASTER_PLATFORM=UNIX EXTENSION=sh =========== MASTER DOMAIN MANAGER ============= Enter the name of your Master Domain Manager. ENTER keeps the value: [SYDNEY]: Keeping the default value SYDNEY ============================= TWS_USER =============================== Enter the name of the TWS_USER (user owning the TWS Master instance). ENTER keeps the value [tws]: Keeping the default value tws ================== Scenario scripts installation path ===================== Enter the full path, where you want to put the scenarios (e.g. /usr/tws/scripts). Use FORWARD SLASHES / even if on WINDOWS PLATFORM! E.g. C:/Program Files/IBM/TWS/tws/scripts If you specify the path which does not exists, or you do not have write permissions in that path,
534
you will be prompetd again. Enter "quit", if you want to quit installation. /usr/tws/scenarios
======================================================================= ====================== Following parameters have been specified: ========================================================= Name of your Master Domain Manager=SYDNEY Owner of the Master Domain Manager instance=tws Scenarios installation path=/usr/tws/scenarios ========================================================= If you agree with the values above, answer y|Y in the following Otherwise provide any other answer and you will be prompted for values again. The previously entered values are remembered. If you mistyped in previous values, just correct the incorrect value. On the other prompts you will press Enter. If you agree with the values above, answer [Y|y]: Or type "quit" to quit the installation. prompt. the any of just
y You have confirmed that you agree with the specified values. Installation will start... Tivoli Workload Scheduler (UNIX)/COMPOSER 8.4 (20070922) Licensed Materials - Property of IBM(R) 5698-WSH (C) Copyright IBM Corp 1998, 2007 All rights reserved. US Government User Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. IBM is a registered trademark of International Business Machines Corporation in the United States, other countries, or both. Installed for user "tws". Locale LANG set to the following: "en" User: tws, Host:127.0.0.1, Port:31116 -replace ./definitions/gbj_job.import_definitions AWSJCL003I The command "update" relating to object "jd=SYDNEY#GBJ_ABEND_JOB" has completed successfully. ....
535
"jd=SYDNEY#GBJ_PATTERN_PATTERN_ERROR_JOB" has completed successfully. AWSJCL003I The command "update" relating to object "jd=SYDNEY#GBJ_PATTERN_PATTERN_JOB" has completed successfully. AWSJCL003I The command "update" relating to object "jd=SYDNEY#GBJ_SOME_JOB" has completed successfully. AWSBIA302I No errors in ./definitions/gbj_job.import_definitions. AWSBIA288I Total objects updated: 12 Tivoli Workload Scheduler (UNIX)/COMPOSER 8.4 (20070922) Licensed Materials - Property of IBM(R) 5698-WSH (C) Copyright IBM Corp 1998, 2007 All rights reserved. US Government User Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. IBM is a registered trademark of International Business Machines Corporation in the United States, other countries, or both. Installed for user "tws". Locale LANG set to the following: "en" User: tws, Host:127.0.0.1, Port:31116 -replace ./definitions/gbj_sched.import_definitions AWSBIA300I The scheduling language syntax has been successfully validated for object "SYDNEY#GBJ_COMPLEX". AWSJCL003I The command "update" relating to object "js=SYDNEY#GBJ_COMPLEX" has completed successfully. AWSBIA300I The scheduling language syntax has been successfully validated for object "SYDNEY#GBJ_LONG_ABEND". AWSBIA300I The scheduling language syntax has been successfully validated for object "SYDNEY#GBJ_LONG_SUCC". AWSJCL003I The command "update" relating to object "js=SYDNEY#GBJ_LONG_SUCC" has completed successfully.
....
AWSJCL003I The command "update" relating to object "js=SYDNEY#GBJ_SIMPLE_ABEND" has completed successfully. AWSBIA300I The scheduling language syntax has been successfully validated for object "SYDNEY#GBJ_SIMPLE_SUCC". AWSJCL003I The command "update" relating to object "js=SYDNEY#GBJ_SIMPLE_SUCC" has completed successfully. AWSBIA302I No errors in ./definitions/gbj_sched.import_definitions. AWSBIA288I Total objects updated: 16
536
If everything went well, you should see the job and job stream definitions in your Job Scheduling Console. Figure 7-44 shows the job definitions.
Figure 7-44 Sample scenarios - job definitions
Figure 7-45 shows the job stream definitions.
Figure 7-45 Sample scenarios - job stream definitions
Now you can submit any of the scenarios and replay the content of the scenarios included in this chapter.
7.7.3 Installation on Windows

This section describes the installation steps for the sample scenarios on the Windows platform.
537
Important: The installation script is written in bash. You need a shell interpreter for Windows in order to run the installer. Because we have tested the installer (together with the branch.sh shell script itself) on Cygwin, we recommend using Cygwin. Now we describe the installation steps when Cygwin has been used as the shell interpreter for your Windows master domain manager. You must perform the following steps in order to install the sample scenarios on the Windows platform: 1. We assume that you already have Cygwin installed on your master domain manager. If not, refer to Chapter 8, Installation of Cygwin onto a Windows master on page 547. 2. Download the file generic_branch_job.zip. 3. Transfer the file to your master domain manager. 4. Log in as the TWS_USER (owner of the master domain manager instance). 5. Save the file to a directory where the TWS_USER has full read/write/execute permissions. 6. Unpack the package using any archive program that understands the zip algorithm. If asked for the extraction path, specify the directory where the TWS_USER has full read/write/execute permissions. The directory tree generic_branch_job will be created. The content of the installation package for Windows platforms is shown in Example 7-47.
Example 7-47 Content of the installation package for Windows platforms
generic_branch_job generic_branch_job\branch generic_branch_job\branch\branch.sh generic_branch_job\definitions generic_branch_job\definitions\gbj_job.templates generic_branch_job\definitions\gbj_sched.templates generic_branch_job\scenario_installer.sh generic_branch_job\scenario_scripts generic_branch_job\scenario_scripts\gbj_pattern.cmd generic_branch_job\scenario_scripts\gbj_pattern_pattern.cmd generic_branch_job\scenario_scripts\gbj_pattern_pattern_error.cmd generic_branch_job\scenario_scripts\gbj_multiple_conditions.cmd generic_branch_job\scenario_scripts\gbj_pattern_error.cmd
538
generic_branch_job\scenario_scripts\gbj_pattern_number.cmd Note: As you can see, the branch job shell script file branch.sh is also present in the package. However, we are not interested in it at this time. You should have the branch job already installed. If you do not, follow the instructions described in 7.4.2, Branch job shell script installation on page 489. 7. Make sure that you have the full read/write/execute permission within the directory tree. If not, adjust either the ownership or permissions on the generic_branch.job directory. This must be done recursively. Note: In most cases this step is not necessary. But if you experience troubles with running the installation script, perform some or all of the following steps, while you are on the level above the generic_branch_job directory. Perform these steps using the Windows GUI: Right click the generic_branch_job directory and select Properties. Make sure that the directory is not read only. Switch to the Security pane and check if the Read & Execute, Read, and Write permissions for the directory are granted either to the TWS_USER or to any of the groups, where the TWS_USER belongs. 8. Source the Tivoli Workload Scheduler command-line environment. This can be done by entering the command %TWS_HOME%\tws_env.cmd, where %TWS_HOME% is the installation directory of your master domain manager. Without sourcing the Tivoli Workload Scheduler command-line environment the installation script will not run. 9. Open a command-line window. You can do it either by clicking the icon on your toolbar or by selecting Start Run and entering cmd. 10.Try to run bash. Type bash in the command-line window. If you receive an error message such as bash is not recognized as an internal or external command, operable program, or batch file., you must set the correct PATH statement. If you have installed Cygwin into the default directory, you should issue the following command: set PATH=C:\Cygwin\bin;%PATH% Note: If you have installed Cygwin into another directory, use the correct value in the command. Do not forget to enter ;%PATH% at the end of the line. The installation script calls several Windows commands and without a properly set PATH the installation process would fail.
539
11.Now you should be able to run the bash command. The output should look like Example 7-48.
Example 7-48 Setting Cygwin path and launching bash
C:\>set PATH=C:\Cygwin\bin;%PATH% C:\>bash bash-3.2$ 12.Go to the directory where you have unpacked the scenarios. Use forward slashes when specifying the directory: cd C:/Windows/Temp/generic_branch_job 13.Run the installation script. Go to the directory generic_branch_job and issue: ./scenario_installer.sh 14.The installer automatically detects the value of the master domain manager and the TWS_USER (in fact, it detects just the current user, but you should be logged in as the TWS_USER). These values will be suggested to you by the installation prompts. 15.The installer will ask you for the following values: Master domain manager name TWS_USER (owner of the Tivoli Workload Scheduler Master instance) Installation path where you want to place the sample scenarios scripts. You must select an existing directory where you have permission to read/write/execute. Note: Always use the forward slashes (/) when using this installation script, even if you are using Windows. The backslashes (\) would not be correctly interpreted! When entering a path that contains one or more spaces, do not enclose the path between quotation marks! If you enter the quotation marks, the path would be incorrectly interpreted. During the prompt phase, you have the chance to correct your inputs. The installation will not start until you confirm that the input values are correct. If you do not confirm them, you will be asked for all three values again. You do not need to retype the correct values because all the values are remembered. After entering the third value, you will be again asked for the confirmation. During the confirmation prompt, you may also enter quit and exit the installation process.
540
16.After you confirm the input values, the installation will start: The sample scenarios scripts are copied into the target directory. Based on the template files combined with the input values, the installation script will create exact definition files for the Tivoli Workload Scheduler. composer command. The composer replace command is invoked for the job definitions and for the stream definitions. If everything went well, you have successfully installed the sample scenarios for the generic branch job. Example 7-49 shows the extract from the text output of the installation process.
Example 7-49 Sample scenarios installation - Windows
C:\>bash bash-3.2$ cd C:/generic_branch_job bash-3.2$ ./scenario_installer.sh ============================================== === START of sample scenarios installation === ==============================================
C:\Program Files\IBM\TWS\tws MASTER_PLATFORM=WINDOWS EXTENSION=cmd =========== MASTER DOMAIN MANAGER ============= Enter the name of your Master Domain Manager. ENTER keeps the value: [HELSINKI]: Keeping the default value HELSINKI ============================= TWS_USER =============================== Enter the name of the TWS_USER (user owning the TWS Master instance). ENTER keeps the value [Administrator]: tws Overriding the detected value Administrator by tws. ================== Scenario scripts installation path ===================== Enter the full path, where you want to put the scenarios (e.g. /usr/tws/scripts).
541
Use FORWARD SLASHES / even if on WINDOWS PLATFORM! E.g. C:/Program Files/IBM/TWS/tws/scripts If you specify the path which does not exists, or you do not have write permissions in that path, you will be prompetd again. Enter "quit", if you want to quit installation. C:/Program Files/IBM/TWS/tws/scenarios
======================================================================= ====================== Following parameters have been specified: ========================================================= Name of your Master Domain Manager=HELSINKI Owner of the Master Domain Manager instance=tws Scenarios installation path=C:/Program Files/IBM/TWS/tws/scenarios ========================================================= If you agree with the values above, answer y|Y in the following Otherwise provide any other answer and you will be prompted for values again. The previously entered values are remembered. If you mistyped in previous values, just correct the incorrect value. On the other prompts you will press Enter. If you agree with the values above, answer [Y|y]: Or type "quit" to quit the installation. prompt. the any of just
y You have confirmed that you agree with the specified values. Installation will start... .\scenario_scripts\gbj_multiple_conditions.cmd .\scenario_scripts\gbj_pattern.cmd .\scenario_scripts\gbj_pattern_error.cmd .\scenario_scripts\gbj_pattern_number.cmd .\scenario_scripts\gbj_pattern_pattern.cmd .\scenario_scripts\gbj_pattern_pattern_error.cmd 6 file(s) copied. C:/Program Files/IBM/TWS/tws/scenarios scm=C:;Program|Files;IBM;TWS;tws;scenarios Tivoli Workload Scheduler (Windows)/COMPOSER 8.4 (20070922) Licensed Materials - Property of IBM(R) 5698-WSH (C) Copyright IBM Corp 1998, 2007 All rights reserved. US Government User Restricted Rights
542
Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. IBM is a registered trademark of International Business Machines Corporation in the United States, other countries, or both. Installed for user "HELSINKI\tws". Locale LANG set to the following: "en" User: tws, Host:127.0.0.1, Port:31116 -replace ./definitions/gbj_job.import_definitions AWSJCL003I The command "update" relating to object "jd=HELSINKI#GBJ_ABEND_JOB" has completed successfully. AWSJCL003I The command "update" relating to object "jd=HELSINKI#GBJ_COMPLEX_JOB" has completed successfully. AWSJCL003I The command "update" relating to object "jd=HELSINKI#GBJ_DO_THE_BAD_THING" has completed successfully. AWSJCL003I The command "update" relating to object "jd=HELSINKI#GBJ_DO_THE_GOOD_THING" has completed successfully. ....
AWSJCL003I The command "update" relating to object "jd=HELSINKI#GBJ_PATTERN_PATTERN_JOB" has completed successfully. AWSJCL003I The command "update" relating to object "jd=HELSINKI#GBJ_SOME_JOB" has completed successfully. AWSBIA302I No errors in ./definitions/gbj_job.import_definitions. AWSBIA288I Total objects updated: 12 Tivoli Workload Scheduler (Windows)/COMPOSER 8.4 (20070922) Licensed Materials - Property of IBM(R) 5698-WSH (C) Copyright IBM Corp 1998, 2007 All rights reserved. US Government User Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. IBM is a registered trademark of International Business Machines Corporation in the United States, other countries, or both. Installed for user "HELSINKI\tws". Locale LANG set to the following: "en" User: tws, Host:127.0.0.1, Port:31116 -replace ./definitions/gbj_sched.import_definitions AWSBIA300I The scheduling language syntax has been successfully validated for object "HELSINKI#GBJ_COMPLEX". AWSJCL003I The command "update" relating to object "js=HELSINKI#GBJ_COMPLEX" has completed successfully.
543
AWSBIA300I The scheduling language syntax has been successfully validated for object "HELSINKI#GBJ_LONG_ABEND". AWSJCL003I The command "update" relating to object "js=HELSINKI#GBJ_LONG_ABEND" has completed successfully. AWSBIA300I The scheduling language syntax has been successfully validated for object "HELSINKI#GBJ_LONG_SUCC". ....
AWSJCL003I The command "update" relating to object "js=HELSINKI#GBJ_SIGNAL" has completed successfully. AWSBIA300I The scheduling language syntax has been successfully validated for object "HELSINKI#GBJ_SIMPLE_ABEND". AWSJCL003I The command "update" relating to object "js=HELSINKI#GBJ_SIMPLE_ABEND" has completed successfully. AWSBIA300I The scheduling language syntax has been successfully validated for object "HELSINKI#GBJ_SIMPLE_SUCC". AWSJCL003I The command "update" relating to object "js=HELSINKI#GBJ_SIMPLE_SUCC" has completed successfully. AWSBIA302I No errors in ./definitions/gbj_sched.import_definitions. AWSBIA288I Total objects updated: 16 bash-3.2$ If everything went well, you should see job and job stream definitions in your Job Scheduling Console. Figure 7-46 shows the job definitions.
Figure 7-46 Sample scenarios - job definitions
Figure 7-47 on page 545 shows the job stream definitions.
544
Figure 7-47 Sample scenarios - job stream definitions
Now you can submit any of the scenarios and replay the content of the scenarios included in this chapter.
7.8 Generic branch job script source code

The complete source code of the generic branch job script is listed in Appendix C, Generic branch job source code on page 593. This code is also available within the supplemental packages that are available together with this book. The packages can be downloaded from the ITSO Web site. Refer to Appendix D, Additional material on page 615 for instructions on how to download the code. The file names are as follows: SG247528_Unix.tar: For the UNIX platform SG247528_Windows.zip: For the Windows platform The step by step instructions on how to extract the branch.sh file from the supplemental packages are included in 7.4.2, Branch job shell script installation on page 489.
545
546
Chapter 8.
Installation of Cygwin onto a Windows master

This chapter provides instructions on how to install the Cygwin onto your Windows master domain manager. In Chapter 7, Generic branch job on page 403, we describe a programmatical extension to the Tivoli Workload Scheduler called generic branch job. The branch job is written in the UNIX shell script. On UNIX master domain managers, it can run without downloading any additional prerequisites. However, on Windows master domain managers, the script must use some UNIX shell interpreter. The interpreter that has been tested with the Generic branch job is contained within the Cygwin bundle. Because the installation of Cygwin is not a typical skill that Tivoli Workload Scheduler administrators usually have, we describe the basic steps for Cygwin installation in this chapter.
547
This chapter has the following sections: Selected installation approach on page 549 Downloading Cygwin from the Cygwin Web site on page 549 Transferring the installables to the master on page 561 Performing the Cygwin installation on the master domain manager on page 562 Testing the Cygwin functionality on page 568
548
8.1 Selected installation approach

The Cygwin installation package is available at the Cygwin Web site at: http://www.cygwin.com Important: Cygwin is a Linux-like environment for Windows. It is free software and can be distributed under the terms of the GNU General Public License (GPL) as published by the Free Software Foundation Version 2 of the License. There is an installation program called setup.exe on the Cygwin Web site that can perform different tasks: Download the installation packages and run the installation. Download the installation packages only. Run the installation. Perform an uninstallation. The easiest way to install Cygwin is to perform the download and install it in one step. But for Tivoli Workload Scheduler purposes, we should remember that the master domain manager can be protected by a firewall and has no Internet access. Because of this limitation, we need to break the installation into three steps: 1. Downloading the installation packages. 2. Transferring the installation packages to the master. 3. Performing the Cygwin installation on the master. We cover all of the above mentioned steps in the following sections.
8.2 Downloading Cygwin from the Cygwin Web site

After going to the Cygwin Web site, do the following steps: 1. Use a workstation that can access the Internet.
Chapter 8. Installation of Cygwin onto a Windows master
549
Important: You must not have Cygwin previously installed on your workstation. The Cygwin installation program remembers the list of already installed packages, so you will not be able to download the correct Cygwin packages. A possible workaround is a temporary renaming of the existing Cygwin directory. In that case, the Cygwin installation program will start from scratch. However, using a Cygwin-free workstation is recommended. 2. Create a directory where you will store the installables, for example, C:\Install\Cygwin.
550
3. Open the Web browser. Go to http://www.cygwin.com. The Cygwin home page appears (Figure 8-1).
Figure 8-1 Cygwin home page
4. Right-click Install or update now. Instead of directly running the setup.exe program from the browser, save the file to the directory that you have created in the previous step. (Figure 8-2 on page 552 and Figure 8-3 on page 553).
551
Figure 8-2 Downloading the installation program
Note: It is important to download and save the installation file locally, because we will transfer it together with the installation bundles to the master.
552
Save the file into the specified directory (Figure 8-3).
Figure 8-3 Selecting the directory for Cygwin bundle
5. Run the installation program and confirm the warning message if it appears. (Figure 8-4).
Figure 8-4 Windows warning message
553
6. The installation program welcome window appears (Figure 8-5). Click Next.
Figure 8-5 Cygwin setup - 1
554
7. Select Download Without Installing (Figure 8-6).
555
8. Specify the same directory where you downloaded the setup.exe program (Figure 8-7).
556
9. Specify the connection type available for your workstation (Figure 8-8).
If a firewall pop-up window appears, allow the connection.
557
10.Specify the mirror site that you want to use for downloading the Cygwin packages. We use http://mirror.calvin.edu in our scenario (Figure 8-9).
558
11.Now the installation program downloads the list of downloadable packages and allows you to select which packages that you want to install (Figure 8-10).
559
12.Leave the default values and click Next. The installation program will start downloading the bundles (Figure 8-11).
560
You should see a window similar to Figure 8-12.
8.3 Transferring the installables to the master

The transfer method depends on your environment, so we will not give any recommendations on how you should copy the downloaded files into the master domain manager file system. Use any available communication channel for transferring the downloaded Cygwin directory to your master domain manager. Copy the directory and its entire contents.
561
8.4 Performing the Cygwin installation on the master domain manager

This section describes how to install Cygwin onto your Tivoli Workload Scheduler Windows master domain manager. We assume that you have completed the steps described in 8.2, Downloading Cygwin from the Cygwin Web site on page 549 and 8.3, Transferring the installables to the master on page 561. 1. Go to the directory where you have copied the Cygwin installation bundle and run the setup.exe installation program. The installation program welcome window appears (Figure 8-13).
Figure 8-13 Cygwin installation on master - 1
562
2. In the following window, select Install from Local Directory (Figure 8-14).
3. The window with Cygwin configuration parameters appears. Select the directory where you want Cygwin to be installed. We have used the default values in our scenario (Figure 8-15 on page 564).
563
Note: Default Text File Type is a very important option. This specifies how Cygwin will handle the text files stored in your Windows file system, including the shell script files. This also affects the branch.sh shell script, that is used for the generic branch job. We provide branch.sh in the UNIX format for both the UNIX master domain manager and the Windows master domain manager. Because Cygwin by default understands only the UNIX format, no further conversion of the branch.sh script is necessary, even if it stored on a Windows file system. If you have converted the branch.sh script somehow to DOS/Windows CR/LF format, you will have to use a conversion utility like dos2unix (shipped with Cygwin) to convert the script file to the UNIX format.
564
4. Select the directory where the installation bundles are stored (Figure 8-16).
565
5. In the following window, keep the default selections and click Next (Figure 8-17).
566
You will see the progress of the installation, as shown in Figure 8-18.
You will see a window similar to Figure 8-19 on page 568.
567
8.5 Testing the Cygwin functionality

Now you should test if Cygwin has installed successfully. Perform the following steps: 1. 2. 3. 4. Open a command line window. Go to the Cygwin installation directory. Go to the bin subdirectory. Issue the bash command.
You should see a bash prompt, as shown in the Example 8-1.

Example 8-1 bash command
Microsoft Windows XP [Version 5.1.2600] (C) Copyright 1985-2001 Microsoft Corp. C:\Documents and Settings\Administrator>cd \cygwin\bin C:\cygwin\bin>bash bash-3.2$
568
Part 4
Part
Planning for a client engagement

In this part, we focus on client engagement planning for an IBM Tivoli Workload Automation portfolio.
569
570
Appendix A.
Planning for a client engagement

In this appendix, we discuss service engagement for IBM Tivoli Workload Automation in general. The target audience of this appendix is Business Partners and Solution Developers. The topics that we discuss include the following: Services engagement preparation on page 572 Solution scope and components on page 573 Services engagement overview on page 575 Estimating time and activities of the engagement on page 582 Important: The time estimates in this chapter are not representative of all the possible implementation scenarios of a Tivoli Workload Automation based solution. Each environment should be considered as unique and these time estimates should be regarded as general guidelines, not absolute numbers
571
Services engagement preparation

This section describes the resources available to help you successfully deliver a Tivoli Workload Automation solution.The end goal of a services engagement may consist of all or some of the following items: Describe a Tivoli Workload Automation architecture and components. Plan and design a Tivoli Workload Automation solution based on client requirements/environment. Install and configure Tivoli Workload Automation infrastructure components. The discussion is divided into the following sections: Implementation skills Available resources
Implementation skills
To be able to successfully develop and deploy a Tivoli Workload Automation based solution, you must acquire some specialized skills. The following lists the skills needed to implement and customize the solution: Working knowledge of automation concepts Working knowledge of OS Administration (Windows, UNIX) Basic knowledge of databases (DB2, Oracle) Basic knowledge of WebSphere Application Server Basic knowledge of scripting The exact skills balance that you will need depends on the environment that you intend to build with this technology, and also the server platform on which you intend to host the management solution.
Available resources
The prerequisite skills listed in the previous section are those needed to customize or develop the solution. For each of these skills, there are a variety of resources available to help acquire the necessary skill level. The educational resources available are as follows: Online Help: The Tivoli Workload Automation portfolio provides seminars on the Web. Details of these materials can be found at: http://www-306.ibm.com/software/tivoli/education/edu_prd.html
572
Further technical information, white papers and, support links. These can be found at: http://www-306.ibm.com/software/tivoli/products/workloadautomation/ Classroom Training: IBM PartnerWorld provides current information about available classes, their dates, locations, and registration. Additionally, check the Partner Education Web site, which serves as a single point of contact for all Business Partner education and training. Further details can be found at: http://www-306.ibm.com/software/tivoli/education/ IBM Technical Education Services (ITES): ITES offers a variety of classes at all knowledge levels to help you achieve any of the offering's prerequisite skills. Redbooks: You can access various practical and architectural information regarding IBM hardware and software platform from IBM Redbooks. These PDFs are available for download from the Web site at: http://ibm.com/redbooks The following are the Tivoli Workload Automation Redbooks available: Getting Started with Tivoli Dynamic Workload Broker Version 1.1, SG24-7442 Integrating IBM Tivoli Workload Scheduler with Tivoli Products, SG24-6648 Getting Started with IBM Tivoli Workload Scheduler V8.3, SG24-7237 Implementing IBM Tivoli Workload Scheduler V 8.2 Extended Agent for IBM Tivoli Storage Manager, SG24-6696 High Availability Scenarios with IBM Tivoli Workload Scheduler and IBM Tivoli Framework, SG24-6632 IBM Tivoli Workload Scheduler Version 8.2: New Features and Best Practices, SG24-6628
Solution scope and components

You need to define the scope of the solution. The solution can be one of the two types of basic offering in Basic solution definition on page 574 or you can add additional components in Advanced solution definition on page 574.
Appendix A. Planning for a client engagement
573
Basic solution definition

The basic solution definition is the implementation of Tivoli Workload Scheduler or Tivoli Dynamic Workload Broker independent of each other.
Tivoli Workload Scheduler

IBM Tivoli Workload Scheduler provides centralized systems management to automate, monitor, and control the flow of work through your enterprises entire data processing operation on both local and remote systems. From a single point of control, you can analyze the status of the production work and drive the processing of the workload. Tivoli Workload Scheduler eliminates the manually intensive process of workload assignments across multiple resources.
Tivoli Dynamic Workload Broker

Tivoli Dynamic Workload Broker is an on demand scheduling infrastructure that provides dynamic management of your environment, analyzes job requirements, and launches and monitors jobs. Tivoli Dynamic Workload Broker improves your workload coordination and scheduling performance and reduces costs. It guarantees the load balancing across resources and optimizes the use of the IT infrastructure by constantly analyzing your environment to maintain an up-to-date view of the resources available and matching them to the requirements defined for each job. New resources are automatically discovered using the Agent Manager and integrated in the scheduling environment.
Advanced solution definition

The advanced Tivoli Workload Automation solution integrates both Tivoli Workload Scheduler with Tivoli Dynamic Workload Broker. The solution would be for Tivoli Workload Scheduler to provide the planning, execution, and monitoring of the scheduled jobs. Dependent jobs are controlled by Tivoli Workload Scheduler, so predecessor and successor jobs execute in the appropriate order. The jobs are balanced between computers using the Tivoli Dynamic Workload Broker during the execution phase. Tivoli Dynamic Workload Broker is the middleware that determines which computer has the available resources at the point in time needed to run the job. When the job is done, the next successor job runs in a series of predecessor/successor dependent jobs. It then routes the job scheduled as a Tivoli Workload Scheduler job to the appropriate system with the most available resources. This allows better
574
resource utilization without having a negative effect on the service level objectives. The need for manual human intervention to execute this process is eliminated due to the combination of Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker.
Services engagement overview

Implementers of a solution routinely rely on their skills and previous experiences to guide them, but there are always some issues that may require some educated guesswork. The goal of this section is to help minimize the guesswork involved in planning and implementing a solution by providing a framework and time estimates for the major tasks: Build an executive assessment (see Executive Assessment on page 576). Set up a demonstration system or proof of technology (see Demonstration system setup on page 577). Analyze the solution tasks (see Analyze solution tasks on page 579). Create a contract, commonly know as a Statement of Work (see Creating a contract on page 580). The representative tasks and the time involved for custom solution execution are included in the following section. Since each client has a unique set of needs, the actual set of tasks to accomplish and the time involved may vary. However, this list should help you understand the implementation details, size the solution more accurately for the client, and ensure a profitable engagement for yourself. It is important to work with your clients to understand their expectations. Once you gather this data, document the tasks, deliverables, and associated costs in a Statement of Work. The Statement of Work acts as your contractual agreement with the client for the duration of the project; therefore, a detailed and well-defined Statement of Work is advantageous both to you and to your client. A good overall understanding of the solution scope is a crucial prerequisite to successfully developing and implementing it. As a Solution Provider, you must understand what is involved in developing such a solution before you can discuss it with your client and size it for a cost estimate.
575
Executive Assessment
The Executive Assessment is a service that can be offered to prospective clients as a billable service. It offers a process designed to help you evaluate the business needs of a company that is planning to deploy a Tivoli Workload Automation solution. This toolset helps you ask the right people the right questions so that you get the information you need to propose the appropriate solution. The complete Executive Assessment process should take approximately 12 to 16 hours. The task breakdown is shown in Table 8-1.
Table 8-1 Solution task Task An initial fact-finding meeting, asking questions, and gathering data A review and analysis of competing solutions Preparation of a set of strategic recommendations Creation of a demonstration prototype A presentation of findings and closing of a contract Total Estimated time (hours) 3 2 1 5-9 1 12-16
This is a business-case assessment, not a technical assessment, so the audience should be business owners, line-of-business executives, marketing and sales managers, and finally, the IT manager. The business owner or line-of-business executive is likely to be the decision maker. For their initial investment, your clients get: A business assessment prepared by a professional (you) A competitive analysis A prototype solution for their review A strategic and tactical proposal for justifying and implementing their solution for e-business
576
Demonstration system setup

A demonstration system is typically set up in advance to show your clients the attributes of the solution. The demonstration system can typically be set up with a limited number of systems that are separate from the system that will be used by the production system. The demonstration can be virtualized with technologies such as Zen, VMWARE, or Microsoft Virtual Server. To do a simple demonstration of Tivoli Workload Scheduler, you would need one server and one agent machine. A key part of the engagement may be that you need to run a specific task on a specific machine, such as a script or a command, at a specific moment of the production day. The demonstration system allows your clients to evaluate whether the solution suits their particular needs. The tasks of demonstrating the solution and its time estimate is shown in Table 8-2 and Table 8-3.
Table 8-2 Solution demonstration tasks for Tivoli Workload Scheduler Task Set up the hardware. Install and configure Tivoli Workload Scheduler master. Install and configure Tivoli Workload Scheduler agent. Demonstrate scheduling to client. Total Estimated Time (hours) 1-2 3-5 1-2 2 7 - 11
For a Tivoli Dynamic Workload Broker demonstration, you need one server and two agents. A key part of the engagement may be that you need to load balance the running of some jobs between the two agents installed.
Table 8-3 Solution demonstration tasks for Tivoli Dynamic Workload Broker Task Set up the hardware. Install and configure Tivoli Dynamic Workload Broker server. Estimated Time (hours) 1 -2 3-5
577
Task Install and configure two Broker agents. Demonstrate load balancing. Total
Estimated Time (hours) 2-4 2 8 - 13
Note: For a Tivoli Workload Automation advanced solution, sum the value of both Table 8-2 and Table 8-3.
Hardware and software requirements

You will need to check the product manuals and release notes for the latest revisions. Here are a few items to consider. The minimum configuration for a Tivoli Workload Scheduler server are shown in the following sections.
Server hardware requirements

Master domain manager with DB2 Server 1.5 GB free space 2 GB RAM 200 MB temporary space Master domain manager/backup master with DB2 Client 500 MB free space 2 GB RAM 200 MB temporary space
Server software requirements

AIX 5L V5.2 or V5.3 HP-UX 11i V2 or V3 for PA-RISK and Itanium Solaris Operating Environment 8, 9, or 10 and 10 for AMD (Opteron) Microsoft Windows Server 2003: Standard, Enterprise, or Data Center Red Hat 3.0, 4.0, or 5.0: System x or Power Systems (64-bit also) Red Hat 3.0 or 4.0: System z Kernel 64 SUSE Linux Enterprise Server 9 or 10
578
Database Server requirements

DB2 Version 8.2 (8.1.7) or later Oracle Database 9i Release 2 -Enterprise Edition (9.2.0.x) or later Oracle Database 10i Release 2 -Enterprise Edition (10.2.0.x) or later
Agent hardware requirements

300 MB free space 256 MB RAM 50 MB temporary space
Agent software requirements

AIX 5L V5.2 or V5.3 HP-UX 11i V1, V2, or v3 for PA-RISK and Itanium Solaris Operating Environment 8, 9, or 10 and 10 for AMD (Opteron) Microsoft Windows Server 2003: Standard, Enterprise, or Data Center (64-bit Itanium 2 also) Microsoft Windows XP Professional SP2 or Microsoft Windows Vista (AMD64 and EM64T also) Red Hat 3.0, 4.0, or 5.0: System x, Power Systems, or System z (64-bit also) SUSE Linux Enterprise Server 9 or 10
Connector requirements
350 MB free space 1.5 GB RAM
Analyze solution tasks

After the client agrees to use the solution in their environment, you must estimate what you must do to implement it. These estimates would then be collected and implemented into a contract or Statement of Work. We discuss these tasks in detail in Estimating time and activities of the engagement on page 582. The tasks are our suggested tasks and order; you may complete these tasks in a different order or may omit or add tasks depending on the environment on which you implement the solution. The overall solution timing may be influenced by the amount of skill and experience that you or your team have on the solution, and also the access to resources facilitated by
579
your client. The assumption of the estimated time that we present is typically based on the following: Knowledge of the operating systems Knowledge of RDBMS and database configuration and management Knowledge of Tivoli Workload Scheduler/ Tivoli Dynamic Workload Broker Depending on your skills and experience, the estimates presented may be too high or too low. Table 8-4 illustrates one method of approximating more realistic time estimates for your efforts, based on whether you or your team are new to each skill area or could be considered experts. A novice represents someone who has completed training in the skill area but has no hands-on experience. An expert represents someone who has completed training in the skill area and has also implemented Tivoli Workload Automation projects. You may use the percentages in Table 8-4 to adjust your time estimate.
Table 8-4 Skill adjustment Skill Experience with the operating system Experience with RDBMS and database management Deep understanding of Tivoli Workload Scheduler Deep understanding of Tivoli Dynamic Workload Broker Novice increase by 25% 10% 25% 30% Expert reduce by 10% 10% 20% 20%
For the detailed task breakdown, see Estimating time and activities of the engagement on page 582.
Creating a contract
A contract or Statement of Work is a binding contractual agreement between you and your client that defines the service engagement that you must perform and the result that the client can expect from the engagement. The contract should leave nothing in doubt.
580
A Statement of Work should contain the following: Executive summary of the solution, which is typically a short (less than a page) summary of the solution and its benefit. You must specify any major restriction of the implementation, such as: The solution is only implemented for finance application servers. The solution will be implemented in phases. Solution description, which contains the major components and solution building blocks that will be implemented. It should cover the conceptual architecture of the solution and solution scope in general. This description is aimed at technical personnel to understand the implementation scope. Assumptions, which lists all the assumptions that are used to prepare the contract and provide task estimation. Any deviation to the assumptions that is used will definitely impact the scope of engagement and must be managed using the change management procedure. Typical changes would include cost changes or scope changes. Business Partner responsibilities, which lists all the responsibilities or major tasks that will be performed by you or your team to implement the solution. Client responsibilities, which lists all the responsibilities or items that the client must provide for you or your team to perform the engagement. If you cannot obtain any item in the client responsibilities, then a change management procedure may be invoked. Staffing estimates, which lists the estimated personnel that must implement the solution. Project schedule and milestones, which shows the major steps, schedule, and achievement calendar that can be used to check the projects progress. Testing methodology, which lists the test cases to ensure that the project implementation is successful. Deliverables, which provides tangible items that the client will get at the end of the service engagement, including: Machine installation Documentation Training Completion criteria, which lists the items that, when provided to the client, indicates that the engagement is successfully completed. For most of services engagement, this is probably the most delicate item to define. It should have clear targets agreed by both parties, and should not be too general.
581
A sample Statement of Work is provided in Appendix B, Sample Statement of Work for a Tivoli Workload Automation solution on page 587.
Estimating time and activities of the engagement

The fundamentals of delivering a profitable and successful services engagement is to correctly identify the tasks that you must perform and to adequately allocate the necessary time to perform them. This section guides you on the tasks that you may need to perform a Tivoli Workload Automation solution implementation and also estimate the time. The estimates rely on some basic assumptions, which invalidate the estimates if the items in the following list become a significant requirement for the client: Managed environment variance: The number of fault tolerant agents (FTA) to install. Managed environment size and network topology: The number of jobs and jobs stream definition to create and schedule. Do you have firewalls between the server and agents? User characteristics and needs: If you need to run specific jobs with specific users, the security file must be correctly configured.
Perform environmental analysis and plan tasks

This section discussed the tasks for environment analysis engagement. Table 8-5 shows the timing estimate for Tivoli Workload Scheduler and Tivoli Dynamic Workload Broker identified tasks.
Table 8-5 Estimated time in hours for identified tasks Task Identify business objectives and project sponsor. Gather details of the scheduling environment. Gather details of OS profile requirements. Tivoli Workload Scheduler 2 Tivoli Dynamic Workload Broker 2
3 2
3 2
582
Task Gather details of hardware variance. Complete design. Communicate plan to project sponsor. TOTAL HOURS
Tivoli Workload Scheduler 3 5 2 17
Tivoli Dynamic Workload Broker 3 5 2 17
To help gather these technical requirements, use the provided sample notes on the issues that they raise, as shown Table 8-6, in order to guide the planning process.
Table 8-6 Technical requirement: gathering sample questions Question How many agents you need to automate? Are there any failover or disaster recovery requirements? Notes The number of agents complicates the plan design. You need to install a Backup Domain Manager to share the Database objects. If the client needs also a database failover solution, a DB administrator must be involved. Create a specific security file to determine who can do what. Tivoli Workload Scheduler for Applications includes the ability to define different access methods (r3batch, unixssh, and unixrsh) to integrate third-party products Tivoli Dynamic Workload Broker allows you to define a logical resource for each application, which increases the configuration time.
Do you need to improve security checking? Do you need to run SAP or PeopleSoft jobs?
How many kinds of applications do you have?
583
Plan the solution

Planning the deployment of a Tivoli Workload Automation solution includes the sub-tasks described here: Gathering requirements At the beginning of your engagement, you should meet with your clients to understand their proposed objectives and gather their requirements. First, you have to determine the functional requirements. Functional requirements define the business functions that the Workload Scheduling system is going to provide. You determine your requirements by developing a good understanding of the business needs and of what you hope to achieve. For example, look at issues such as business goals, purpose, and usage questions, such as who the users are and how they expect to interact. It is important to gather these requirements early and discover any challenges that may lie ahead while they can still be dealt with easily. Once you have determined the functional requirements, you can clarify the technical or system requirements. The technical requirement involves spending time at the client site to determine and understand the available data sources. Design the solution Topics that should be addressed include scalability, functionality, and performance of this solution. Design involves understanding the client's environment, including hardware, software, data volumes, special requirements, and operational procedures. It is necessary to identify and plan for any additional tuning of software that may be required because of the client's environment or special needs. In addition, an analysis of the modifications made to the scenarios and reports needs to be performed. After you have designed the proposed solution and reviewed it with your client, you are ready to begin development of the offering. Perform gap analysis This task may involve performing a gap analysis to give the client an estimate of the development effort required to set up the solution. At its core, the analysis seeks to determine what customizable components need to be extended, modified, or created. The number and complexity of customizable components drive the size of the project and the required resources. After you have designed the proposed solution and reviewed it with your client, you are ready to proceed.
584
Implement the solution

The implementation of the solution is performed using the tasks described in Table 8-7. Note that here we are estimating times to perform the activities a single time. Remember that the number of each item may vary, which will reflect on the total time for the project. The number of agents that need to deployed and also the number of jobs that you need to use will also affect the total time for the project.
Table 8-7 Time line estimates for implementation activities Tasks Estimated time (hours) Tivoli Workload Scheduler Identify servers and configure any firewalls for automation traffic. Build the OS. Install the RDBMS and the IBM Tivoli Workload Automation servers. Install and configure one agent. Create a Job and Job Stream definition and schedule them. Test the solution. Deliver education: IBM Tivoli Workload Scheduler for Operators (1 days) IBM Tivoli Workload Scheduler for Administrators (3 days) IBM Tivoli Dynamic Workload Broker (3 days) Document the solution. TOTAL HOURS 1 3 3-5 1 1 14 28 Tivoli Dynamic Workload Broker 1 3 3-5 1 1 14 21
14 65-67
14 58-60
585
Close the engagement

When the technical work has been completed, and the education has been delivered, the engagement will need to be formally closed with the project sponsor or their deputy. We suggest that the following agenda items be covered during the meeting with the project sponsor: 1. Review of original business objectives 2. Summary of how solution meets defined objectives 3. Summary of services delivered 4. Summary of new capability 5. Other services or product identified during the engagement 6. Thanks and closing
586
Appendix B.
Sample Statement of Work for a Tivoli Workload Automation solution

In this appendix, we provide a skeleton document that you can use for developing your own customized Statement of Work.
587
Building an operating system deployment solution

The content of the Statement of Work includes activities to: Install the IBM Tivoli Workload Automation component infrastructure Configure Agents for Server communication Create Job and Job Stream definitions for the script provided by the client Configure the schedule time The building of the Statement of Work for a Tivoli Workload Automation deployment solution consists of the following parts: Executive summary on page 588 Solution description on page 588 Assumptions on page 589 Business Partner responsibilities on page 589 Client responsibilities on page 589 Staffing estimates on page 590 Testing on page 590 Deliverables on page 591 Completion criteria on page 591
Executive summary
This item concerns the building of the infrastructure required for your environment automation. After this work has been completed, you will have the infrastructure necessary to successfully automate your workload and improve your performance with minimal physical intervention.
Solution description
There is a need to run and manage thousands of scripts during a production day with minimal human intervention. The Tivoli Workload Automation solution provides an easy-to-use method to monitor all of your processes in a production environment and provide recovery options if the resulting flow of jobs is inconsistent.
588
This service offering provides a quick time to value for your investment in the Tivoli Workload Automation Solution technology by providing a working environment within five working days.
Assumptions
These are the assumptions that we make in this Statement of Work: We will have local administrator access to the management server. We will have administrative access to the management server database. We will have access to the DHCP Server configuration. We will have access to Windows OS media and client license keys. We will have full access to a sample target workstation and server.
Business Partner responsibilities

This service will be provided according to the high standards of <name of Business Partner>, an IBM Certified Business Partner. We will provide: Skilled staff to undertake the defined activities Documentation of the completed solution Project management of these activities Note: Insert any additional responsibilities here that you will be taking on as part of this project.
Client responsibilities
This section describes the responsibilities the client has to the Business Partner, for example: Designating a representative who will be the focal point for all communication with the Business Partner relative to this project and who will have the authority to act on the clients behalf in matters regarding this project Designating operations personnel to work with the Business Partner as appropriate Providing all product data in a format as requested Providing all data and information required for implementation
Appendix B. Sample Statement of Work for a Tivoli Workload Automation solution
589
Providing a suitable workspace with Internet and telephone access for the services specialists while working on the client premises Providing user IDs, passwords, and IP addresses as required, enabling the Business Partner to perform the service Note: Add any client responsibilities that you need to assign in order to complete a successful delivery of your service.
Staffing estimates
The project will be performed with one Tivoli Workload Automation Solution specialist, who will be on site as required by the project schedule. We will also provide project management services, and will be onsite at the end of the project for its formal closure. The project is estimated to be performed within five working days. This is six man days of effort in total. We expect that will need a single member of your staff working with us throughout this time, who will also perform any mediation role required between us and any other required technical resources within your operation. This is five man days in total. Note: You may wish to revise these estimates if you wish to provide extra services, such as education.
Testing
The testing of the solution will be done through the use of the infrastructure to deploy packages to the target machines. Testing will be complete when we successfully: Create the infrastructure. (Tivoli Workload Scheduler V8.4 and Tivoli Dynamic Workload Broker V1.2) Create simple job and job stream definitions. Schedule the job stream. Submit the job. Submit the job stream. Analyze the job log. Create dependencies for the job and job stream (files, prompt, and time restrictions).
590
Create a job submission dynamic language (JSDL) file and upload it on the Tivoli Dynamic Workload Broker server. Submit the JSDL from the Tivoli Dynamic Workload Broker server. Analyze the job balancing between two agents.
Deliverables
At the end of this engagement, you will have One Tivoli Workload Scheduler server One Tivoli Dynamic Workload Broker server Three Tivoli Workload Scheduler fault tolerant agents Two Tivoli Dynamic Workload Broker agents One sample job One sample job stream One sample JSDL file Documentation for the deployed environment.
Completion criteria
The completion criteria for this project are: The successful completion of all the tests The delivery of the solution documentation
Appendix B. Sample Statement of Work for a Tivoli Workload Automation solution
591
592
Appendix C.
Generic branch job source code

This appendix contains the source code of the generic branch job described in Chapter 7, Generic branch job on page 403. The source code is shipped together with the sample scenarios in one package. There are separate packages for UNIX and Windows platforms. The packages can be downloaded from the ITSO Web site. Refer to Appendix D, Additional material on page 615 for instructions on how to download the code. The file names are as follows: SG247528_Unix.tar: For UNIX platforms SG247528_Windows.zip: For Windows platforms The complete source code of the generic branch job script is listed in Example C-1 on page 594.
593
Example: C-1 Generic branch job source code
####################################################################### ################################################## #!/bin/sh # Branch Job for TWS # (C) Martin Lisy IBM, December 2007 # 4.1 development version # History # 1.0 Paleolitical version - fixed values of parents/children # 2.5 Implemented branching based on retcode # 2.6 Implemented branching based on single pattern text # 2.7 Implemented signaling (just exiting with retcode 0|1 on text pattern found/not found) # 2.8 Multiple pattern search (up to 3 patterns within one STDOUT) # 3.0 Reworked for UNIX/Windows(cygwin) generic installation # 3.1 Redesigned Input/Action parameters # 3.2 Reworked evaluation logic # 3.3 Working version on UNIX platform for CONDITION_SWITCH,ACTION_SWITCH and up to 9 complex conditions (string/arithmetics) # 4.0 ALL INPUT Parameters moved form DATABASE and parms to Job Stream Comments field # 4.1 Protection of incorrectly defined parent/children ####################################################################### ################################################## # THIS SCRIPT IS PROVIDED AS IS, WITHOUT ANY WARRANTY # # You must run this script from the TWS Job definition. It can't be run from a command line. # Read the instructions from the following IBM Redbooks publication: # Deployment Guide Series: IBM Tivoli Workload Scheduler V8.4 and IBM Tivoli Dynamic Broker V1.2, SG247528 # This book is avalable at the ITSO Web site at http://www.redbooks.ibm.com # # You can find all the useful instructions within this book. ####################################################################### ################################################## # Most simple usage of this script does not need any input parameters. # You must just name the GOOD child with the G_ prefix and the BAD child with the B_ prefix. # (this must done in the jobstream definition). #
594
# If you want to use more complex scenarios (as pattern searching, numeric value comparing, # signaling, pausing, releasing, etc..., refer to mentioned book. # ####################################################################### ################################################## # Report bugs and send comments and suggestions to: # martin_lisy@cz.ibm.com # and # martin.lisy@centrum.cz ####################################################################### ################################################## plecho() { echo ========================================================== echo ============= $* ============= } set_debug(){ DEBUG=NONE #DEBUG=LEVEL1 #DEBUG=LEVEL2 #add a possibility to evaluate "command line" parameter - set the debug level also in TASK definition of a TWS job #planned for version 4.4 :-) } decho() { [ ! $DEBUG = "NONE" ] && echo $* } d2echo() { [ $DEBUG = "LEVEL2" ] && echo $* } check_if_tws_job() { decho "**check_if_tws_job() START**" if [ -z "$UNISON_DIR" ]; then echo This script can be run only as a TWS JOB!! exit 1 fi decho "**check_if_tws_job() END**" } print_header() {
Appendix C. Generic branch job source code
595
echo ============ START of branch job $BRANCH_JOB_NAME ========== } print_footer() { echo ============ END of branch job $BRANCH_JOB_NAME ========== } set_environment() { decho "**set_environment() START**" echo $UNISON_DIR |grep "\\\\" && MASTER_PLATFORM=WINDOWS || MASTER_PLATFORM=UNIX if [ $MASTER_PLATFORM == "WINDOWS" ]; then UNISON_DIR=ècho "$UNISON_DIR" | sed 's/\\\\atjobs//'| sed 's/\\\\/\//g'` fi MAESTRO_OUTPUT_STYLE=LONG MAESTROLINES=0 TMPDIR="$UNISON_DIR"/tmp cd "$TMPDIR" composer="$UNISON_DIR/bin/composer" conman="$UNISON_DIR/bin/conman" parms="$UNISON_DIR/bin/parms" if [ $DEBUG = "LEVEL2" ]; then echo ================= OS ENVIRONMENT ======================= set |grep UNISON echo ================================================== fi decho "**set_environment() END**" } assign_tmp_files() { decho "**assign_tmp_files() START**" STREAM_FILE=$STREAM_ID$BRANCH_JOB_NAME TMP_STREAM_FILE=$STREAM_FILE.tmp CONDITION_FILE=$STREAM_FILE.cond PARAMETER_FILE=$STREAM_FILE.parms decho STREAM_FILE=$STREAM_FILE decho TMP_STREAM_FILE=$TMP_STREAM_FILE decho CONDITION_FILE=$CONDITION_FILE decho "**assign_tmp_files() END**" } get_stream_definition() { decho "**get_stream_definition() START**"
596
STREAM_ID=$UNISON_SCHED_ID STREAM_NAME=$UNISON_SCHED STREAM_CPU=ècho $UNISON_JOB | cut -d \# -f1` decho STREAM_NAME=$STREAM_NAME assign_tmp_files d2echo "BEFORE COMPOSER" "$composer" "create $TMP_STREAM_FILE sched=$STREAM_CPU#$STREAM_NAME" >/dev/null d2echo "AFTER COMPOSER" decho="COMPOSER COMMAND composer create $TMP_STREAM_FILE sched=$STREAM_NAME" decho "STREAM=$STREAM_NAME" awk ' { if (a=match($1,"#")) if (NF==3 && $2=="AS") child=$3; else child=substr($0,a+1);if ($1=="FOLLOWS") \ printf "%s FOLLOWS %s\n",child,$2 }' $TMP_STREAM_FILE >$STREAM_FILE sed -n ' s/^#$.*$$/\1/p' $TMP_STREAM_FILE > $PARAMETER_FILE decho "**get_stream_definition() END**" } get_job_definition() { JOB_CPU=ècho $UNISON_JOB | cut -d . -f 1` BRANCH_JOB_NAME=ècho $UNISON_JOB | cut -d . -f 2` decho JOB_CPU=$JOB_CPU decho BRANCH_JOB_NAME=$BRANCH_JOB_NAME } check_proper_job_name() { decho "**check_proper_job_name() START**" #check if name is either BRANCH or SIGNAL and suffix is present and is number CORRECT_NAME=NO [ ècho $BRANCH_JOB_NAME | grep "^BRANCH_[0-9][0-9]*$"` ] && CORRECT_NAME=YES [ ècho $BRANCH_JOB_NAME | grep "^SIGNAL_[0-9][0-9]*$"` ] && CORRECT_NAME=YES if [ $CORRECT_NAME = "NO" ]; then echo "You have entered incorrect job name." echo "......" echo "When this job is placed into the job stream, it must have one of following names:" echo "BRANCH_suffix or SIGNAL_suffix" echo "-where "suffix" is a numeric value" echo "Examples of correct names for branch jobs: BRANCH_1, BRANCH_2, ... BRANCH_15..."
597
echo "Examples of correct names for signal jobs: SIGNAL_1, SIGNAL_2, ... SIGNAL_15..." echo "......" echo Exiting without performing anything! print_footer exit 1 fi decho "**check_proper_job_name() END**" } get_parameter() { decho "**get_parameter() START**" START_DELIMITER=$BRANCH_JOB_NAME-BEGIN END_DELIMITER=$BRANCH_JOB_NAME-END d2echo Getting Parameter $PARAMETER_NAME for job $BRANCH_JOB_NAME sd=$START_DELIMITER ed=$END_DELIMITER PARAMETER_ROW=`sed -n '/'$START_DELIMITER'/,/'$END_DELIMITER'/ p' $PARAMETER_FILE |grep -v $START_DELIMITER | grep -v $END_DELIMITER |grep -i $PARAMETER_NAME |grep =` PARAMETER_SEARCH_RESULT=$? d2echo Parameter_search_result=$PARAMETER_SEARCH_RESULT if [ $PARAMETER_SEARCH_RESULT -eq 0 ]; then d2echo PARAMETER_ROW=$PARAMETER_ROW PARAMETER_VALUE=ècho $PARAMETER_ROW | sed 's/.*=$.*$/\1/'` d2echo $PARAMETER_NAME=$PARAMETER_VALUE if [ $MANDATORY_PARAMETER = "TRUE" ]; then d2echo MANDATORY parameter. PARAMETER_VALUE=ècho "$PARAMETER_VALUE" |tr '[:lower:]' '[:upper:]'` d2echo In MANDATORY: UPPERCASE Parameter value="$PARAMETER_VALUE" d2echo Possible values="$POSSIBLE_VALUES" #remove the starting hyphen to avoid bad GREP behavior TMP_VALUE=ècho $PARAMETER_VALUE | sed 's/^-//'` echo "$POSSIBLE_VALUES" | grep "$TMP_VALUE" >/dev/null || PARAMETER_VALUE="$DEFAULT_VALUE" d2echo Still in get single parameter fi else if [ $MANDATORY_PARAMETER = "TRUE" ]; then PARAMETER_VALUE=$DEFAULT_VALUE
598
d2echo Adding the default value to mandatory parameter $PARAMETER_NAME=$PARAMETER_VALUE else PARAMETER_VALUE="" d2echo Returning empty value of parameter $PARAMETER_NAME fi fi d2echo Finally evaluated parameter $PARAMETER_NAME=$PARAMETER_VALUE decho "**get_parameter() END**" } get_input_parameters(){ decho "**get_input_parameters()** START" #CONDITION_SWITCH PARAMETER_NAME=CONDITION_SWITCH MANDATORY_PARAMETER=TRUE POSSIBLE_VALUES="PARENT_SUCCESS PARENT_ABEND COMPLEX" DEFAULT_VALUE=PARENT_SUCCESS get_parameter CONDITION_SWITCH=$PARAMETER_VALUE decho Paremeter CONDITION_SWITCH=$CONDITION_SWITCH #ACTION_SWITCH PARAMETER_NAME=ACTION_SWITCH MANDATORY_PARAMETER=TRUE POSSIBLE_VALUES="CANCEL PAUSE SIGNAL" DEFAULT_VALUE=CANCEL get_parameter ACTION_SWITCH=$PARAMETER_VALUE #protection from incorrect parameters. Signal job must signal and branch job must not signal if [ ècho $BRANCH_JOB_NAME | grep "^SIGNAL_[0-9][0-9]*$"` ] && [ ! $ACTION_SWITCH = "SIGNAL" ]; then echo "This is SIGNAL job. Correcting the incorrect parameter ACTION_SWITCH=$PARAMETER_VALUE to ACTION_SWITCH=SIGNAL" ACTION_SWITCH=SIGNAL fi if [ ècho $BRANCH_JOB_NAME | grep "^BRANCH_[0-9][0-9]*$"` ] && [ $ACTION_SWITCH = "SIGNAL" ]; then echo "This is BRANCH job. Correcting the incorrect parameter ACTION_SWITCH=SIGNAL to default value ACTION_SWITCH=CANCEL" ACTION_SWITCH=CANCEL fi
599
decho Paremeter ACTION_SWITCH=$ACTION_SWITCH #Patterns PATTERN_PARAMETER_FOUND=YES INDEX=1 #exit from loop, if PATTERN PARAMETERN not found for current index while [ $PATTERN_PARAMETER_FOUND = "YES" ]; do PARAMETER_NAME=PATTERN_$INDEX decho PARAMETER_NAME=$PARAMETER_NAME MANDATORY_PARAMETER=FALSE get_parameter #remove any quotes PATTERN[$INDEX]=ècho "$PARAMETER_VALUE" | sed 's/\"//g'` decho PATTERN[$INDEX]="${PATTERN[$INDEX]}" if [ -z "$PARAMETER_VALUE" ]; then PATTERN_PARAMETER_FOUND=NO else #when PATTERN PARAMETER present, getting the VALUE PARAMETER PARAMETER_NAME=VALUE_$INDEX decho PARAMETER_NAME=$PARAMETER_NAME MANDATORY_PARAMETER=FALSE get_parameter #remove any quotes VALUE[$INDEX]=ècho "$PARAMETER_VALUE" | sed 's/\"//g'` decho VALUE[$INDEX]="${VALUE[$INDEX]}" #deciding the nature of VALUE : STRING, NUMBER, EMPTY if [ -z "$PARAMETER_VALUE" ]; then VALUE_TYPE[$INDEX]=EMPTY else echo "$PARAMETER_VALUE" | grep [^0-9.] >/dev/null && VALUE_TYPE[$INDEX]=STRING \ || VALUE_TYPE[$INDEX]=NUMBER fi d2echo VALUE_TYPE[$INDEX]=${VALUE_TYPE[$INDEX]} #if number, check, if the last "dot sign" represents end of sentence or a delimiter within the number of type "REAL" [ ${VALUE_TYPE[$INDEX]} = "NUMBER" ] && VALUE[$INDEX]=ècho "${VALUE[$INDEX]}" | sed 's/$.*$\.$/\1/'` decho VALUE_TYPE[$INDEX]="${VALUE_TYPE[$INDEX]}" #when VALUE PARAMETER present AND is NUMBER, getting the ARITHMETICAL_OPERATOR PARAMETER
600
if [ ${VALUE_TYPE[$INDEX]} = "NUMBER" ]; then PARAMETER_NAME=ARITHMETICAL_OPERATOR_$INDEX decho PARAMETER_NAME=$PARAMETER_NAME MANDATORY_PARAMETER=TRUE POSSIBLE_VALUES="-LT -LE -EQ -NE -GE -GT" DEFAULT_VALUE="-eq" get_parameter PARAMETER_VALUE=ècho $PARAMETER_VALUE |tr '[:upper:]' '[:lower:]'` decho "Lowercase operator=$PARAMETER_VALUE" ARITHMETICAL_OPERATOR[$INDEX]=$PARAMETER_VALUE decho ARITHMETICAL_OPERATOR[$INDEX]="${ARITHMETICAL_OPERATOR[$INDEX]}" fi #getting the NEGATE_CONDITION_RESULT PARAMETER PARAMETER_NAME=NEGATE_CONDITION_RESULT_$INDEX decho PARAMETER_NAME=$PARAMETER_NAME MANDATORY_PARAMETER=TRUE POSSIBLE_VALUES="YES NO" DEFAULT_VALUE="NO" get_parameter NEGATE_CONDITION_RESULT[$INDEX]=$PARAMETER_VALUE decho NEGATE_CONDITION_RESULT[$INDEX]="${NEGATE_CONDITION_RESULT[$INDEX]}" #getting the IS_CASE_SENSITIVE PARAMETER PARAMETER_NAME=IS_CASE_SENSITIVE_$INDEX decho PARAMETER_NAME=$PARAMETER_NAME MANDATORY_PARAMETER=TRUE POSSIBLE_VALUES="YES NO" DEFAULT_VALUE="YES" get_parameter IS_CASE_SENSITIVE[$INDEX]=$PARAMETER_VALUE decho IS_CASE_SENSITIVE[$INDEX]="${IS_CASE_SENSITIVE[$INDEX]}" #getting the IS_REGULAR_EXPRESSION PARAMETER PARAMETER_NAME=IS_REGULAR_EXPRESSION_$INDEX decho PARAMETER_NAME=$PARAMETER_NAME MANDATORY_PARAMETER=TRUE POSSIBLE_VALUES="YES NO" DEFAULT_VALUE="NO" get_parameter
601
IS_REGULAR_EXPRESSION[$INDEX]=$PARAMETER_VALUE decho IS_REGULAR_EXPRESSION[$INDEX]="${IS_REGULAR_EXPRESSION[$INDEX]}" #getting the BOOLEAN OPERATOR PARAMETER, which "CONNECTS" current parameter to PRECEDING parameter #this parameter is ignored for the first parameter if [ $INDEX -gt 1 ]; then PARAMETER_NAME=BOOLEAN_OPERATOR_$INDEX decho PARAMETER_NAME=$PARAMETER_NAME MANDATORY_PARAMETER=TRUE POSSIBLE_VALUES="&& ||" DEFAULT_VALUE="&&" get_parameter BOOLEAN_OPERATOR[$INDEX]=$PARAMETER_VALUE decho BOOLEAN_OPERATOR[$INDEX]="${BOOLEAN_OPERATOR[$INDEX]}" fi #finally increase the counter INDEX=èxpr $INDEX + 1` fi done CONDITION_COUNT=èxpr $INDEX - 1` decho CONDITION_COUNT=$CONDITION_COUNT if [ $CONDITION_SWITCH = "COMPLEX" ] && [ $CONDITION_COUNT -eq 0 ]; then echo "CONDITION_COUNT=0!! Changing CONDITION from COMPLEX to PARENT_SUCCESS!!" CONDITION_SWITCH=PARENT_SUCCESS fi decho "**get_input_parameters()** END" } cleanup() { decho "**cleanup() START**" if [ DEBUG = "NONE" ]; then [ -f $STREAM_FILE ] && rm $STREAM_FILE [ -f $TMP_STREAM_FILE ] && rm $TMP_STREAM_FILE [ -f $PARAMETER_FILE ] && rm $PARAMETER_FILE [ -f $CONDITION_FILE ] && rm $CONDITION_FILE fi decho "**cleanup() END**"
602
} get_parent() { decho "**get_parent()** START" BRANCH_JOB_PARENT=àwk '{ if ($1 == "'$1'") print $3; }' $STREAM_FILE` decho BRANCH_JOB_PARENT=$BRANCH_JOB_PARENT decho "**get_parent( )END**" } get_children() { decho "**get_children() START**" CHILDREN_LIST=àwk '{ if ($3 == "'$1'") print $1; }' $STREAM_FILE` decho CHILDREN_LIST=$CHILDREN_LIST decho "**get_children() END**" } get_jobnum() { decho "**get_jobnum() START**" JOB_NUMBER=`"$conman" "sj $STREAM_CPU#$STREAM_ID.$1;schedid" 2>/dev/null| tail -n 1 | sed 's/(.*)//' | awk '{ print $NF }' | sed 's/#J$.*$$/\1/'` decho "CONMAN sj $STREAM_CPU#$STREAM_ID.$1;schedid" d2echo JOBNUM=`"$conman" "sj $STREAM_CPU#$STREAM_ID.$1;schedid" 2>/dev/null| tail -n 1 | sed 's/(.*)//'` decho JOB_NUMBER=$JOB_NUMBER decho "**get_jobnum() END**" } get_status() { decho "**get_status() START**" JOB_STATUS=`"$conman" "sj $STREAM_CPU#$STREAM_ID.$1;schedid" 2>/dev/null| grep $1 | tail -n 1 | sed 's/(.*)//' | awk '{ for (i=0;i<NF;i++) if ($i=="'$1'") print $(i+1) }'` decho JOB=$STREAM_ID.$1 decho "CONMAN sj $STREAM_CPU#$STREAM_ID.$1;schedid" d2echo JOBSTAT=`"$conman" "sj $STREAM_CPU#$STREAM_ID.$1;schedid" 2>/dev/null| tail -n 1 | sed 's/(.*)//'` decho JOB_STATUS=$JOB_STATUS decho "**get_status() END**" } get_priority() { decho "**get_priority() START**"
603
JOB_PRIORITY=`"$conman" "sj $STREAM_CPU#$STREAM_ID.$1;schedid" 2>/dev/null| tail -n 1 | sed 's/(.*)//' | awk '{ for (i=0;i<NF;i++) if ($i=="'$1'") print $(i+2) }'` decho "CONMAN sj $STREAM_CPU#$STREAM_ID.$1;schedid" d2echo JOBPRIO=`"$conman" "sj $STREAM_CPU#$STREAM_ID.$1;schedid" 2>/dev/null| tail -n 1 | sed 's/(.*)//'` decho JOB_PRIORITY=$JOB_PRIORITY decho "**get_priority() END**" } find_pattern() { decho "**find_pattern() START**" #set parameters for "grep" [ ${IS_CASE_SENSITIVE[$i]} = "YES" ] && CASE_SWITCH="" || CASE_SWITCH=-i [ ${IS_REGULAR_EXPRESSION[$i]} = "YES" ] && REGEXP_SWITCH="" || REGEXP_SWITCH=-F decho CASE_SWITCH=$CASE_SWITCH, REGEXP_SWITCH=$REGEXP_SWITCH #get job and its joblog get_jobnum $1 echo Searching for \"$2\" in JOBLOG of $1 decho JOB_NUMBER=$JOB_NUMBER decho "CONMAN sj $JOB_NUMBER ;stdlist" PATTERN_ROW=`"$conman" "sj $JOB_NUMBER ;stdlist" 2>/dev/null| grep $CASE_SWITCH $REGEXP_SWITCH "$2" |head -n 1` [ -z "$PATTERN_ROW" ] && PATTERN_FOUND="NO" || PATTERN_FOUND="YES"; decho PATTERN_ROW="$PATTERN_ROW" if [ $PATTERN_FOUND = "YES" ]; then echo "Pattern FOUND, performing further tests." else echo "Pattern NOT FOUND, condition evaluated as FALSE." fi decho "**find_pattern() END**" } evaluate_single_condition() { decho "**evaluate_single_condition() START**" decho "searching for pattern$i=${PATTERN[$i]}" find_pattern $BRANCH_JOB_PARENT "${PATTERN[$i]}" decho PATTERN_FOUND for CONDITION[$i] = $PATTERN_FOUND if [ $PATTERN_FOUND = "YES" ]; then case ${VALUE_TYPE[$i]} in NUMBER)
604
NUMBER=ècho "$PATTERN_ROW" | sed 's/[^0-9.]*//g'` echo "Searching for NUMBER withing row..." if [ ! -z "$NUMBER" ]; then #remove the "dot sign" from the last position of the string (difference between "REAL" delimiter and the end of sentence. NUMBER=ècho $NUMBER | sed 's/$.*$\.$/\1/'` echo "Number found=$NUMBER. Evaluating arithmetical expression [ $NUMBER ${ARITHMETICAL_OPERATOR[$i]} ${VALUE[$i]} ]" if [ $NUMBER ${ARITHMETICAL_OPERATOR[$i]} ${VALUE[$i]} ]; then echo "Arithmetical expression [ $NUMBER ${ARITHMETICAL_OPERATOR[$i]} ${VALUE[$i]} ] evaluated as TRUE." CONDITION[$i]=TRUE else CONDITION[$i]=FALSE echo "Arithmetical expression [ $NUMBER ${ARITHMETICAL_OPERATOR[$i]} ${VALUE[$i]} ] evaluated as FALSE." fi else echo "Number NOT FOUND within the row. Condition evaluated as FALSE." CONDITION[$i]=FALSE fi decho "CONDITION[$i] NUMBER = ${CONDITION[$i]}" ;; STRING) echo "Searching for STRING=${VALUE[$i]} within the row \"$PATTERN_ROW\"." decho CASE_SWITCH=$CASE_SWITCH, REGEXP_SWITCH=$REGEXP_SWITCH echo "$PATTERN_ROW" | grep $CASE_SWITCH $REGEXP_SWITCH "${VALUE[$i]}" >/dev/null PATTERN_PATTERN_SEARCH_RESULT=$? if [ $PATTERN_PATTERN_SEARCH_RESULT -eq 0 ]; then CONDITION[$i]=TRUE echo "String \"${VALUE[$i]}\" found within the row \"$PATTERN_ROW\"." else CONDITION[$i]=FALSE echo "String \"${VALUE[$i]}\" NOT found within the row \"$PATTERN_ROW\"." fi decho "CONDITION[$i] STRING = ${CONDITION[$i]}" ;;
605
EMPTY) echo "No additional value defined for specified pattern. Condition evaluated as TRUE." CONDITION[$i]=TRUE decho "CONDITION[$i] EMPTY = ${CONDITION[$i]}" ;; esac else CONDITION[$i]=FALSE fi #revert the result, if NEGATE_CONDITION_RESULT=YES if [ ${NEGATE_CONDITION_RESULT[$i]} = YES ]; then [ ${CONDITION[$i]} = TRUE ] && CONDITION[$i]=FALSE || CONDITION[$i]=TRUE echo "==NEGATED== ATOMIC CONDITION RESULT [$i]= ${CONDITION[$i]}" else echo "ATOMIC CONDITION RESULT [$i]= ${CONDITION[$i]}" fi decho "**evaluate_single_condition() END**" } determine_good_child_and_bad_child() { decho "**determine_good_child_and_bad_child() START**" GOOD_CHILD=ècho $CHILDREN_LIST | awk '{ if (match($1,"G_")==1) print $1; if (match($2,"G_")==1) print $2 }'` BAD_CHILD=ècho $CHILDREN_LIST | awk '{ if (match($1,"B_")==1) print $1; if (match($2,"B_")==1) print $2 }'` decho "**determine_good_child_and_bad_child() END**" } determine_run_branch_and_stop_branch() { decho "**determine_run_branch_and_stop_branch() START**" #determine "GOOD" and "BAD" children plecho MAIN DECISION MAKING get_children $BRANCH_JOB_NAME determine_good_child_and_bad_child #most common case - if PARENT ends SUCCessfully, then the RUN branch is the GOOD one if [ $CONDITION_SWITCH = "PARENT_SUCCESS" ]; then echo Evaluation dependent on PARENT_SUCCESS get_status $BRANCH_JOB_PARENT if [ $JOB_STATUS = "SUCC" ];
606
then CONDITION_RESULT=TRUE RUN_BRANCH=$GOOD_CHILD STOP_BRANCH=$BAD_CHILD [ $ACTION_SWITCH = "PAUSE" ] && ACTION_SWITCH=CANCEL else CONDITION_RESULT=FALSE RUN_BRANCH=$BAD_CHILD STOP_BRANCH=$GOOD_CHILD fi evaluation_message="$CONDITION_RESULT: Searched for SUCC parent. Status of PARENT JOB($BRANCH_JOB_PARENT) is $JOB_STATUS." echo $evaluation_message fi #reverted case - if PARENT ABENDS, then the RUN branch is the BAD one if [ $CONDITION_SWITCH = "PARENT_ABEND" ]; then echo Evaluation dependent on PARENT_ABEND get_status $BRANCH_JOB_PARENT if [ $JOB_STATUS = "SUCC" ]; then CONDITION_RESULT=FALSE RUN_BRANCH=$BAD_CHILD STOP_BRANCH=$GOOD_CHILD else CONDITION_RESULT=TRUE RUN_BRANCH=$GOOD_CHILD STOP_BRANCH=$BAD_CHILD [ $ACTION_SWITCH = "PAUSE" ] && ACTION_SWITCH=CANCEL fi evaluation_message="$CONDITION_RESULT: Searched for ABEND parent. Status of PARENT JOB($BRANCH_JOB_PARENT) is $JOB_STATUS." echo $evaluation_message fi #most complicated case - evaluate the condition based on PATTERN search #sometimes combined with arithmetical evaluation #multiple evaluations can occur either in positive or negative meaning #e.g. #search for line containing string "space available" #if this line contains number greater than 100 the condition is OK # and other exampes described in DOC :-)
607
if [ $CONDITION_SWITCH = "COMPLEX" ]; then echo COMPLEX condition evaluation i=1 CONDITION="if " PRINTABLE_CONDITION="" while [ $i -le $CONDITION_COUNT ] do echo "----------ATOMIC CONDITION $i------------" evaluate_single_condition if [ $i -gt 1 ]; then CONDITION="$CONDITION ${BOOLEAN_OPERATOR[$i]} " PRINTABLE_CONDITION="$PRINTABLE_CONDITION ${BOOLEAN_OPERATOR[$i]} " fi CONDITION="$CONDITION [ TRUE = ${CONDITION[$i]} ] " PRINTABLE_CONDITION="$PRINTABLE_CONDITION [ ${CONDITION[$i]} ] " decho "Condition value inside loop[i]=$i : $CONDITION" i=èxpr $i + 1` done echo "-------------------------------------" echo "-------- COMPLEX CONDITION ----------" echo "$PRINTABLE_CONDITION" CONDITION="$CONDITION; then echo TRUE; else echo FALSE; fi" decho "Complete condition syntax: $CONDITION" echo $CONDITION > $CONDITION_FILE chmod +x $CONDITION_FILE CONDITION_RESULT=`./$CONDITION_FILE` echo CONDITION_RESULT=$CONDITION_RESULT if [ $CONDITION_RESULT = "TRUE" ]; then RUN_BRANCH=$GOOD_CHILD STOP_BRANCH=$BAD_CHILD [ $ACTION_SWITCH = "PAUSE" ] && ACTION_SWITCH=CANCEL else RUN_BRANCH=$BAD_CHILD STOP_BRANCH=$GOOD_CHILD fi evaluation_message="$CONDITION_RESULT: The result of complex condition is $CONDITION_RESULT." echo $evaluation_message fi decho "**determine_run_branch_and_stop_branch() END**"
608
} recursive_action() { decho "**recursive_action() START**" if [ ! -z "$*" ]; then for ACTION_JOB in $* do echo "Performing action $ACTION on job $STREAM_CPU#$STREAM_ID.$ACTION_JOB" get_priority $ACTION_JOB case $ACTION in "CANCEL") "$conman" "cj $STREAM_CPU#$STREAM_ID.$ACTION_JOB;schedid;noask" 2>/dev/null if [ -z "$CANCELLED_JOBS" ]; then CANCELLED_JOBS=$ACTION_JOB else CANCELLED_JOBS=ècho $CANCELLED_JOBS, $ACTION_JOB` fi # -z cancelled_jobs get_children $ACTION_JOB if [ ! -z "$CHILDREN_LIST" ]; then CHILDREN_LIST=ècho $CHILDREN_LIST | \ awk ' { for (i=1;i<=NF;i++) if ($i!="'$RUN_BRANCH'" && $i!="'$STOP_BRANCH'") print $i } '` decho My child is $CHILDREN_LIST ============================= recursive_action $CHILDREN_LIST fi #childlist ;; "PAUSE") "$conman" "altpri $STREAM_CPU#$STREAM_ID.$ACTION_JOB;schedid;0;noask" 2>/dev/null PAUSED_JOB=$ACTION_JOB ;; "RELEASE") get_priority $ACTION_JOB if [ $JOB_PRIORITY -eq 0 ]; then echo "Releasing $STREAM_CPU#$STREAM_ID.$ACTION_JOB, because priority=$JOB_PRIORITY" "$conman" "altpri $STREAM_CPU#$STREAM_ID.$ACTION_JOB;schedid;10;noask" 2>/dev/null RELEASED_JOB=$ACTION_JOB
609
else echo "Releasing of job $STREAM_CPU#$STREAM_ID.$ACTION_JOB is NOT NECESSARY, because priority=$JOB_PRIORITY" fi #$job_priority -gt 0 ;; *) ;; esac done fi decho "**recursive_action() END**" } perform_branching(){ decho "**perform_branching() START**" #action on STOP branch (cancel/pause) ACTION=$ACTION_SWITCH plecho Action on STOP Branch recursive_action $STOP_BRANCH #action on RUN branch (release if paused) ACTION=RELEASE plecho Action on RUN Branch recursive_action $RUN_BRANCH decho "**perform_branching() END**" } print_input_summary() { decho "**print_input_summary() START**" plecho Job environment echo MASTER_PLATFORM=$MASTER_PLATFORM echo STREAM_NAME=$UNISON_SCHED echo STREAM_CPU=$STREAM_CPU echo BRANCH_JOB_NAME=$BRANCH_JOB_NAME echo PARENT=$BRANCH_JOB_PARENT plecho Input parameters echo CONDITION_SWITCH=$CONDITION_SWITCH echo ACTION_SWITCH=$ACTION_SWITCH [ $CONDITION_SWITCH = "COMPLEX" ] && echo CONDITION_COUNT=$CONDITION_COUNT i=1 while [ $i -le $CONDITION_COUNT ] do echo PATTERN[$i]="${PATTERN[$i]}" echo IS_CASE_SENSITIVE[$i]="${IS_CASE_SENSITIVE[$i]}" echo IS_REGULAR_EXPRESSION[$i]="${IS_REGULAR_EXPRESSION[$i]}"
610
if [ "${VALUE_TYPE[$i]}" != "EMPTY" ]; then echo VALUE[$i]"=${VALUE[$i]}" [ ${VALUE_TYPE[$i]} = "NUMBER" ] && echo ARITHMETICAL_OPERATOR[$i]="${ARITHMETICAL_OPERATOR[$i]}" fi [ $i -gt 1 ] && echo "BOOLEAN OPERATOR[$i]=${BOOLEAN_OPERATOR[$i]}" echo "NEGATE_CONDITION_RESULT[$i]=${NEGATE_CONDITION_RESULT[$i]}" i=èxpr $i + 1` done decho "**print_input_summary() END**" } print_statistics() { decho "**print_statistics() START**" plecho Statistics of branch job $BRANCH_JOB_NAME if [ $ACTION_SWITCH = "SIGNAL" ]; then if [ $CONDITION_RESULT = "TRUE" ]; then echo "******Recommended confirmation for this job is SUCC.******" else echo "******Recommended confirmation for this job is ABEND.******" fi else echo "$evaluation_message" echo "For action $ACTION_SWITCH - RUN_BRANCH=$RUN_BRANCH and STOP_BRANCH=$STOP_BRANCH" echo BRANCH selected to STOP: $STOP_BRANCH echo BRANCH selected to CONTINUE: $RUN_BRANCH echo CANCELLED_JOBS: $CANCELLED_JOBS echo PAUSED_JOB: $PAUSED_JOB echo RELEASED_JOB:$RELEASED_JOB fi decho "**print_statistics() END**" } check_proper_stream_definition(){ decho "**check_proper_stream_definition() START**" ## this function checks, if the branch job has is placed correctly into job stream
611
# each branch job must have the parent get_parent $BRANCH_JOB_NAME if [ -z "$BRANCH_JOB_PARENT" ]; then echo This Branch job has no parent! Exiting without performing anything! print_footer exit 1 fi get_children $BRANCH_JOB_NAME decho CHILDREN_LIST=$CHILDREN_LIST CHILDREN_COUNT=ècho $CHILDREN_LIST | awk ' { print NF } '` decho CHILDREN_COUNT=$CHILDREN_COUNT if [ $ACTION_SWITCH = "SIGNAL" ]; then #signaling job must have one child if [ $CHILDREN_COUNT -ne 1 ]; then echo SIGNAL branch job must have exactly one child. This is not fulfilled! echo Exiting without performing anything! print_footer exit 1 fi else ##non-signaling jobs must have exactly two children if [ $CHILDREN_COUNT -ne 2 ]; then echo Branch job must have exactly two children. This is not fulfilled! echo Exiting without performing anything! print_footer exit 1 fi ##GOOD and BAD children must have correct prefixes determine_good_child_and_bad_child decho GOOD_CHILD=$GOOD_CHILD decho BAD_CHILD=$BAD_CHILD if [ -z "$GOOD_CHILD" ]; then echo GOOD child is not specified. It must have the G_ prefix. Exiting without performing anything! print_footer exit 1
612
fi if [ -z "$BAD_CHILD" ]; then echo BAD child is not specified. It must have the B_ prefix. Exiting without performing anything! print_footer exit 1 fi fi decho "**check_proper_stream_definition() END**" }
#################### ### BEGIN ### #################### #initialize debug messages set_debug $* # determine MASTER platform and set necessary working environment set_environment #check, if the script is running as the TWS JOB check_if_tws_job # get current branching job details get_job_definition #print joblog header print_header #check, if the branch job has a correct name within the job stream check_proper_job_name #get details about current job stream get_stream_definition get_input_parameters #get details about current job #check, if the branch job has correct position in the job stream (parent/children..) check_proper_stream_definition
613
# get job's parent get_parent $BRANCH_JOB_NAME #print all data collected before evaluating print_input_summary #discover, which branch should continue and which must be stopped determine_run_branch_and_stop_branch if [ $ACTION_SWITCH != SIGNAL ]; then #perform recursive actions on child branches if not SIGNAL job perform_branching fi #final statistics print_statistics #print joblog footer print_footer #cleanup cleanup exit 0 #################### ### END ### ####################
614
Appendix D.
Additional material
This appendix refers to additional material that can be downloaded from the Internet.
Locating the Web material

The Web material associated with this book is available in softcopy on the Internet from the IBM Redbooks Web server. Point your Web browser at: ftp://www.redbooks.ibm.com/redbooks/SG247528 Alternatively, you can go to the IBM Redbooks Web site at: ibm.com/redbooks Select the Additional materials and open the directory that corresponds with the IBM Redbooks form number, SG247528.
615
Using the Web material

The additional Web material that accompanies this book includes the following files: File name SG247528.zip Description Generic branch job script source code
System requirements for downloading the Web material

The following system configuration is recommended: Hard disk space: Operating System: 10 MB minimum Windows/Linux/UNIX
How to use the Web material

Create a subdirectory (folder) on your workstation, and unzip the contents of the Web material zip file into this folder.
616
Abbreviations and acronyms

BDM CAS CCMDB CIT CLI DM EDWA EIF EJB EWLM FTA FTP GPL GUI HTTP IBM ISA ISC ITES ITSO J2EE JMS JSC JSDL LDAP Backup Domain Manager Common Agent Services Change and Configuration Management Database Common Inventory Technology Command-Line Interface Domain Manager Event Driven Workload Automation Event Integration Facility Enterprise Java Beans Enterprise Workload Manager Fault Tolerant Agent File Transfer Protocol GNU General Public License Graphical User Interface Hypertext Transfer Protocol International Business Machines Corporation IBM Support Assistant Integrated Solutions Console IBM Technical Education Services International Technical Support Organization Java 2 Enterprise Edition Java Message Services Job Scheduling Console Job Submission Description Language Lightweight Directory Access Protocol MDM RA SA SLA SOA SSL TCO TCP TEC TLS TMR TPM TWS LTPA Lightweight Third-Party Authentication Master Domain Manager Resource Advisor Standard Agent Service Level Agreements Service-Oriented Architecture Secure Sockets Layer Total Cost of Ownership Transmission Control Protocol Tivoli Enterprise Console Transport Layer Security Tivoli Management Region Tivoli Provisioning Manager Tivoli Workload Scheduler
617
618
Related publications
The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this book.
IBM Redbooks
For information about ordering these publications, see How to get Redbooks on page 620. Note that some of the documents referenced here may be available in softcopy only. Getting Started with IBM Tivoli Workload Scheduler V8.3, SG24-7237 Getting Started with Tivoli Dynamic Workload Broker Version 1.1, SG24-7442 High Availability Scenarios with IBM Tivoli Workload Scheduler and IBM Tivoli Framework, SG24-6632 Implementing IBM Tivoli Workload Scheduler V 8.2 Extended Agent for IBM Tivoli Storage Manager, SG24-6696 Integrating IBM Tivoli Workload Scheduler with Tivoli Products, SG24-6648
Other publications
These publications are also relevant as further information sources: IBM Tivoli Dynamic Workload Broker Installation and Configuration Guide Version 1.2, SC32-2282 IBM Tivoli Dynamic Workload Broker User's Guide Version 1.2, SC32-2281 IBM Tivoli Workload Scheduler Job Scheduling Console User's Guide Version 8.4, SC32-1257 IBM Tivoli Workload Scheduler Planning and Installation Guide Version 8.4, SC32-1273 IBM Tivoli Workload Scheduler Reference Guide Version 8.4, SC32-1274
619
Online resources
These Web sites are also relevant as further information sources: bc utility for Linux: http://community.installshield.com/archive Cygwin Web site: http://www.cygwin.com IBM Log and Trace Analyzer Web site: http://www-128.ibm.com/developerworks/autonomic/btmpd Information for sharing the user registry in the WebSphere Application Server V6.1: http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/index.jsp Supported operating systems for all Tivoli products: http://www.ibm.com/software/sysmgmt/products/support/Tivoli_Supporte d_Platforms.html Tivoli Workload Scheduler up-to-date hardware and software requirements: http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm .tivoli.itws.doc/igmst02.htm#ToC_71
How to get Redbooks

You can search for, view, or download Redbooks, Redpapers, Technotes, draft publications and Additional materials, as well as order hardcopy Redbooks, at this Web site: ibm.com/redbooks
Help from IBM

IBM Support and downloads ibm.com/support IBM Global Services ibm.com/services
620
Index
Numerics
64 bit 257 availability of consumable resources 61
B A
ABEND 246 ABEND (Error) 246 access methods 583 action helper 286 action plug-ins 29, 294 action run instances 29 action triggering 29 actions 272, 280 Actions list 221 active rule 384 ad hoc job 242 Add Link 232 Add Run Cycle 235 adding a dependency 232 additional programming 404 Administration port 143 Administration secure port 143 administrative security 201 Agent Manager 70, 97 Agent Managers Certification Authority 97 agents private key 96 agents public key 96 AgentAuditEvent 115 align IT to business goals 5 All Scheduled Jobs 246 Allocation Repository 64 AO 28 appservman 27 Arrange Icons 231 assign additional resource 15 asynchronous events 269 audit trail file name 116 audit trail files 116 audit.properties 115 auditing properties 115 authentication in client network 99 authentication mechanism 99 authentication realm 288 automated data backup and restore 15 batch 25 batch jobs 25 batchman 27 batchman statistics 39 best system for executing the job 13 bm check file 37 bm check status 39 bm check until 39 bm look 39, 47 bm read 39, 47 bm stats 39 bm verbose 39 Bootstrap / RMI 143 branch.sh 491, 532 browse a job log 245 Browse Job Log 246 built-in event providers 281 business solutions 5
C
cache 41 calendaring 11 cancel a job 8 Candidate CPU Architectures panel 257 CAO Model 28 CCMDB (Tivoli Change and Configuration Management Database ) 173 centalized management 8 Centralized scripts 263 centralized security 3435 centralized storage management operations 15 Certification Authority 70, 123 changing the job name 225 chargeback 9 CLI 28 CLI Model Web 28 CLI Planner Web 28 Client engagement planning 571 business requirements 584 Close the engagement 586
621
engagement activities 582 engagement preparation 572 Available resources 572 Implementation skills 572 environmental analysis 582 estimating timings 582 functional requirements 584 Implement the solution 585 plan the solution 584 services engagement overview 575 analyze solution tasks 579 creating a contract 580 demonstration system set up 577 Executive Assessment 576 solution components 573 solution scope 573 advanced solution 574 basic solution 574 client responsibilities 581 clients private key 96 cluster manager 4 command-line cilent 140 command-line interface (CLI) 81 Common Agent Services (CAS) 6970, 99 Common Agent Services infrastructure 70 common programming methodology 4 communications between workstations 21 completion criteria 581 complex message handling 14 composer add 501502 composer replace 541 Confidentiality and Integrity features 96 Config Download Web 29 Configuring Tivoli Workload Scheduler Bridge 261 conman sbd 242 conman show command 35 conman tellop command 42 Conn Event Rule Deployment 29 Conn Event Rule Engine 28 Conn Model 28 Conn Plan 28 connector 20 Context assistant 125 Converting job definitions into job brokering definitions 83 correct dependency resolution 11 COURIER.MSG 40 courier.msg 46
CP Planner 28 Create symbolic links 145 Create Task 249 critical path analysis 7 critical workload 7 current rulebase name 351 custom registry 288 Customize and Generate Reports 248 Cygwin bundle 547 Cygwin installation 491
D
DAO Event Rule 28 DAO Log 29 DAO Plan 28 Data Source 28 datecalc command 36 DB2 install script 154 DB2 Setup Wizard 186 DB2 tools catalog 193 DB2Resource logical resource 264 default certificates 96 defined objectives 586 defining new events 344 deliverables 581 demonstration scenarios 219 deploymentFrequency (df) 327 disable database auditing 35 disable plan auditing 36 divisions between domains 23 Download Manager 29 dumpsec 290 dynamic end-to-end workload automation solution 5
E
education 586 embedded WebSphere Application Server 80 enable database auditing 35 enable list security check 35 enable plan auditing 36 enabling database auditing 35 plan auditing 36 enCarryForward 34 enCentSec 34 encrypted communication 91 enDbAudit 35
622
end-to-end dependency management 11 end-to-end workload automation 5 enEventDrivenWorkloadAutomation (ed) 340 enEventProcessorHttpsProtocol (eh) 340 enListSecChk 35 enPlanAudit 36 enSwfaultTo 36 Enterprise Java Bean (EJB) 28 Enterprise Workload Manager 14 Domain Policy 14 Enterprise Workload Manager (EWLM) 63, 173 Domain Policy 14 enablement 57 Management Domain 9 ERP application workloads 7 event correlation 29 event correlation conditions 276 event correlation engine 286 event correlation process 29 Event Correlator 29 event driven workload automation 272 command-line interface 338 communication among event processor and agents 292 concepts 269 action providers 282 actions 280 event correlation conditions 276 event providers 281 event rules 274 events 272 database 286 demonstration 360 event processor 286 event providers implementation 296 event rule deployment process 290 global options 340 high availability 287 highlights 271 implementation details 284 important files and directories 293 local options 342 logical design 271 monitoring agents 286 security 287 Tivoli Enterprise Console integration 345 topology 284 User interfaces 287 working with 297
Event Integration Facility (EIF) 292294 event listening process 29 Event Plug-ins 29 Event Processor 29, 293 Event Processor port 143 event property 323 event rule 29 event rule deployment process 290 deploying the monitoring configuration to workstations 291 deployment steps 290 eligible workstations 291 initiating the deployment process 292 event rule instances 29 event rule life cycle 274275 event rules 272, 274 event sequence 278 event transport mechanism 29 eventProcessorEIFPort (ee) 340 events 272 everyday run cycle 237 evtdef command 344 EXEC 246 EXEC (Running) 246 Executive Assessment 576 Extended agent (XA) 24
F
fault tolerance 11 fault tolerant agent (FTA) 24, 137, 287 file dependencies 38 File Monitor 282 File Transfer Protocol (FTP) 42 FileMon subagent 297 Filter Critera page 252 FINAL job stream 37 Find button 229 Find Job Stream window 239 firewall support 98 forecast plan 28 FULLSTATUS FTA 36
G
gap analysis 584 General properties 225 generate a custom report 249 generate_customer_price_list 11 generic branch job 403
Index
623
Action part 410 assumptions 528 begin separator 511 branch job capabilities 409 branch job design advantages 411 branch job parameters 509 branch job prerequisites 489 branch job shell script installation on UNIX 489 on Windows 491 complex branch 432 complex branch scenarios 431 considerations 528 end separator 511 evaluation part 409 introduction 404 job evaluating logic 409 long branch demonstration 419 multiple branch 425 sample scenarios 412 sample scenarios installation 530 script source code 545 simple branch demonstration 415 source code 593 terminology 406 bad child 406 branch 406 branch job suffix 407 condition 406 good child 406 input parameter 407 parent 406 run branch 406 stop branch 407 Generic Command Executor 284 generic events 273 GenericActionPlugin.jar 343 GenericEventPlugIn.jar 343 global options parameter 33 enCarryForward 34 enCentSec 34 enDbAudit 35 enListSecChk 35 enPlanAudit 36 enSwfaultTol 36 ignoreCals 36 startOfDay 37 Global prompts 297
Grid computing 4 Grid computing technology 5 Grid environments 6
H
Health Insurance Portability and Accountability Act 114 high availability 15 high-priority applications 14 HistoryDataAuditEvent 115 Hypertext Transfer Protocol (HTTP) 42
I
IBM Change and Configuration Management Database (CCMDB) enablement 57 IBM Enterprise Workload Manager 15 IBM Log and Trace Analyzer 116 IBM PartnerWorld 573 IBM Service Management 15 IBM specialists 405 IBM Support Assistant (ISA) plug-in 125 IBM Technical Education Services (ITES) 573 IBM Tivoli Business Systems Manager 15 IBM Tivoli Dynamic Workload Console 156 IBM Tivoli Enterprise Portal 15 IBM Tivoli Passport Advantage 137 IBM Tivoli Passport Advantage Web site 164, 210 IBM Tivoli Provisioning Manager 15, 173 IBM Tivoli Service Level Advisor 15 IBM Tivoli Storage Manager 15 IBM Tivoli System Automation for Multiplatforms 15 IBM Tivoli System Automation for z/OS 15 IBM Tivoli Workload Automation portfolio 67 IBM Tivoli Dynamic Workload Broker 7 IBM Tivoli Workload Scheduler 6 IBM Tivoli Workload Scheduler for Applications 7 IBM Tivoli Workload Scheduler for z/OS 6 IBM Tivoli Workload Scheduler LoadLeveler 7 technical overview 7 IBM Tivoli Workload Automation solutions 6 IBM Tivoli Workload Scheduler for Virtualized Data Centers 7 IBM WebSphere Application Server wizard 199 IBM WebSphere Java 2 Enterprise Edition (J2EE) 260 IBM workload automation family 3 IBM Workload Manager for z/OS 15
624
IBM z/OS operating system 15 ignoreCals 36 Implementation skills 572 improve business efficiency 4 installed plug-ins 28 Installing IBM DB2 Universal Database V9.1 184 Tivoli Dynamic Workload Broker V1.2 168 Advanced Installation Settings 178 Custom 172 Enable administrative security 201 IBM Tivoli Dynamic Workload Broker extensions 172 port selection box 178 Sample Applications window 199 Tivoli Workload Scheduler Bridge 172 Typical 171 Tivoli Workload Scheduler 131 Tivoli Workload Scheduler Bridge 261 Tivoli Workload Scheduler V8.4 137 existing installation 140 Firewall environment 143 graphical installation wizard 137 in a preexisting production environment 209 master domain manager (MDM) 137 on an existing WebSphere Application Server 209 Oracle Database 147 through a Software Distribution product 137 twsinst command 137 with DB2 Universal database 146 workstation configuration information 142 WebSphere Application Server V6.1 197 InstallShield Wizard 139, 154 Integrated Solutions Console (ISC) 77, 119, 163, 209 Integrated Solutions Console for IBM Tivoli Dynamic Workload Console 218 integration scenario 263 INTERCOM.MSG 39 Internet Explorer V6.0 298, 361, 390 Internet Explorer V7.0 298, 361, 390 internetwork dependencies 39 interprocesses communication 30 IT governance 15 IT resource availability 7 IT resource usage constraints 15 IT resources 4 Itanium 133, 578
ITDWB application 119
J
J2EE enterprise application 57 JavaScript engine 298, 361, 390 jm job table size 40 jm look 40, 47 jm nice 40 jm no root 40 jm read 40, 47 JnextPlan 31, 33, 3536 JnextPlan script 31 job 11, 3839, 220 Job Brokering Definition Console 168, 264 installing 205 job classes 9 job definition editor 497 Job Dispatcher 63 Job Execution Agent 6566 job names 229 Job Repository 64 Job Run Statistics Report 250 job scheduling objects 31 job status 9, 39 job stream 38, 226 job stream definition 38 job stream editor 230 job stream names 229 Job Submission Description Language (JSDL) 75, 168, 205 job table 40 JobAuditEvent 115 JobDefinitionAuditEvent 115 JobLogAuditEvent 115 jobman 27
K
key business processes 15
L
launchpad.exe 168, 210 LDAP registry 288 LDAP server 288 license agreement 139 load balancer 4 LoadLeveler 7 local options
Index
625
parameter 37 bm check file 37 bm check status 39 bm check until 39 bm look 39 bm read 39 bm stats 39 bm verbose 39 jm job table size 40 jm look 40 jm nice 40 jm no root 40 jm read 40 mm cache mailbox 41 mm cache size 41 mm response 41 mm retrylink 41 mm sound off 42 mm unlink 42 nm port 42 nm read 42 nm retry 42 nm SSL port 42 switch sym prompt 44 sync level 43 tcp timeout 44 thiscpu 44 timeout 44 wr enable compression 44 wr read 44 wr unlink 45 local prompts 297 local user 34 localopts file 47 logCleanupFrequency (lc) 342 logHistory (lh) 342 Logical resource view 263 LogMonX subagent 297 Lookup function 323 LTP Planner 28
makesec 290 makesec command 34 manage critical IT processes 15 managed environment size 582 managed environment variance 582 management hub 20 managing server 94 market trends and directions 4 massively parallel jobs 14 master 20, 23 master domain manager (MDM) 137, 226, 238, 242 MASTERDM 21 MASTERDM domain 286 matching and routing workloads 7 maximum resource utilization 9 Message Logger 283 Message Logger event provider 336 message logs 29 Microsoft Virtual Server 577 middleware 15 mm cache mailbox 41 mm cache size 41 mm read 47 mm response 41 mm retrylink 41 mm sound off 42 mm unlink 42 Model Object 28 Monbox.msg 27 monbox.msg 296 monitoring agent 286 monman 27 monman process 286 Mozilla Firefox V2.0 298, 361, 390 multiple cluster nodes 14 multiple file dependencies 38 multiple jobs 226 multiple network names 345 mutual authentication port 143 mutual SSL handshake 93, 99, 123
M
Mail Sender 283 Mailbox.msg 27 mailman 27 mailman failure 41 mailSenderName (ms) 341 mainframe scheduling 6
N
Netcool SSM subagent 286 netman 2627, 142 network traffic 21 New Job Definition section 221 New Job Properties window 224 New Job Stream section 238
626
New Workstation window 262 nm port 42 nm read 42 nm retry 42 nm SSL port 42 NumberOfProcessors 63
Q
qualified file checking 38 dependency 38
R
r3batch 583 RDBMS 28 reading 41 reading cache for incoming messages 41 Recovery Option 502 Recovery options 528 RecoveryActionAuditEvent 115 Redbooks Web site 620 Contact us xxvii RelationshipAuditEvent 115 Report Header 251 Report Tablespace Name 152 Report Tablespace Path 152 Reporting 164 Requires Confirmation flag 480 resend the Symphony file 35 Resource Advisor (RA) 60 Resource Advisor Agent 66 Resource allocation failed error 268 Resource definitions 76 Resource Manager 72 resource matching process 61 resource optimization scenario 256 resource priority control 9 resource selection policies 61 Resource Utilization scenario 263 ResourceAuditEvent 115 Response actions 310 Response file 188 Restart Application Server box 180 Return code mapping 263 Rule 29 Rule Builder 29, 286 rule editor 300 run cycle 233 Run Cycle View 234, 268 Run Cycle window 236 Frequency 236 On 236 Run Cycles list 237
O
Objects Monitor 281 occurrence 242 onfig 29 onn 28 Open Grid Services Architecture 7 OPENS dependency 38 Operator Messages 283, 336 Operator Messages portlet 283 Opteron 578 optman 33 optman chg 33 optman command 33 Oracle 7 Oracle Database Administrator 147 Oracle Server 147
P
Partner Education Web site 573 passing through the zone boundaries 98 PeopleSoft 583 plan 154 Plan Services Web 28 plan the solution design the solution 584 gathering requirements 584 perform gap analysis 584 planman operations 28 planning the deployment 584 portlet 299 ppservman 27 predefined events 269 previous security file 35 private keys 93 process flow 45 production day 27, 3031 production plan 28 project schedule and milestones 581 project sponsor 586 prompt dependencies 38
Index
627
S
sample Statement of Work 587 SAP 7 SAP R/3 24 Sarbanes-Oxley Act 114 scenarios 219 scenarios in this book 49 secure communication 96 secure connection 99 Secure Sockets Layer (SSL) connections 42 port 42 secure links 43 security file 34, 582 sendevent utility 273 server authentication port 143 server connection 288 servers certificate 96 servers private key 96 servers public key 96 service 5 service class 15 service level agreements (SLA) 45, 15 service level agreements for job execution 4 service-oriented architecture (SOA) 4, 28, 118 servlet 2829 servlet request 9 SETUP.sh 137 SFinal 142 shared user registry 288 single-sign-on approach 106 SMTP server configuration 194 SMTP settings 283 smtpServerName (sn) 341 smtpServerPort (sp) 341 smtpUseAuthentication (ua) 341 smtpUserName (un) 341 smtpUserPassword (up) 341 smtpUseSSL (us) 341 smtpUseTLS (tl) 341 SOAP connector port 143 specifying 252 specifying filter criteria 252 SSL connections 42 SSL handshake 96 ssmagent 27 staffing estimates 581 stageman command 34 standard agent 260261, 263
standard error 245 standard output 245 startOfDay 37 StartUp script 26 Statement of Work 579, 587 assumptions 589 Business Partner responsibilities 589 client responsibilities 589 completion criteria 591 customize 587 deliverables 591 executive summary 588 solution description 588 staffing estimates 590 testing 590 Status of All Jobs 241 STERDM 21 stringent SLAs 4 su command 220 submit a job stream 238 subordinate agents 31 subordinate domain manager 31 subordinate domain managers 22 SUCC (Successful) 246 support business processes and policies 5 suppress 8 suppress a job 8 Symphony Creation DAO 28 Symphony file batchman scans 46 changes to 27 creation 31 distribution 32 JnextPlan script 31 start time 37 update 32 Symphony records 28 sync level 43 default setting 43 High 43 Low 43 Medium 43 SystemOut.log 293
T
tablespace 151 Tablespace Name 151 Tablespace Path 151
628
tampering with the security file 35 Task 221 Task tab 244 Task Type 221 TDWB 75 TDWBClientKeyFile.jks 95 TDWBClientTrustFile.jks 95 TDWBServerKeyFile.jks 95 TDWBServerTrustFile.jks 95 tec_recv_agent_port 346 TECServerName (th) 340 TECServerPort (tp) 340 TELNET 42 test command 38 Testing methodology 581 thiscpu 44 time zone 302 timeout 44, 279 timeout actions 310 timing estimate 582 Tivoli Agent Manager 178 Tivoli Dynamic Workload Broker agent 65 agent components 65 Job Execution Agent 65 Resource Advisor Agent 66 agent subcomponents 66 Job Execution Agent 66 J2EE Job Executor 66 Native Job Executor 66 Allocation Repository 64 architecture 53 topological view 55 Job Dispatcher 63 Resource Repository 60 Web Services interface 119 Tivoli Dynamic Workload Broker applications 201 Tivoli Dynamic Workload Console 161 Tivoli Endpoint 70 Tivoli Enterprise Console 29 Tivoli Enterprise Console administrator 351 Tivoli Enterprise Console integration 345 Tivoli LoadLeveler 9 Tivoli Management Region (TMR) server 70 Tivoli Provisioning Manager (TPM) enablement 57 Tivoli Storage Manager (TSM) 80, 119 Tivoli Workload Automation environment 136 Tivoli Workload Automation portfolio 7 Tivoli Workload Scheduler 80
advanced customization 33 global options parameters 33 local options parameters 37 architecture 19 browse a job log 220, 245 components 26 application server subsystems Action Plug-ins 29 CLI Model Web 28 CLI Planner Web 28 Config Download Web 29 Conn Event Rule Deployment 29 Conn Event Rule Engine 28 Conn Plan 28 CP Planner 28 DAO Event Rule 28 DAO Log 29 DAO Model 28 DAO Plan 28 Data Source 28 EIF Listener 29 Event Correlator 29 Event Plug-ins 29 Event Processor 29 LTP Planner 28 Plan Services Web 28 Rule Builder 29 Symphony Creation DAO 28 engine processes 26 application server subsystems 28 appservman 27 batchman 27 jobman 27 mailman 27 monman 27 netman 26 writer 27 connector 20 CPU 20 database 19, 31, 220 domain 26 engine 19 event rules 28 event-driven scheduling 20 Fle Monitor 281 four tier network 23 important tuning parameters 47 introduction 18 Job Scheduling Console 20
Index
629
logical workstation 24 master domain 20 master domain manager 32 masters Symphony file 23 MASTERDM 21 multi-domain configuration 21 multiple instances 43 network 20 Object Monitor 281 objects 229 overview 18 performance optimization 47 physical workstation 24 plan 30 creation of the plan 31 distribution of the plan 31 process flow 45 production day 30 quick-start demonstration 220 reducing network traffic 21 self monitoring 271 simplest configuration 21 single domain configuration 20 start of new day 22 submit a job stream 238 submit ad hoc jobs 242 Tivoli Dynamic Workload Console 20 Tivoli Enterprise Console integration 345 topology 25 user 221 Web-based console 20 what is new with V8.4 51 workstation types 24 backup domain manager (BDM) 24 domain manager (DM) 24 extended agent (XA) CA7 24 JES2 24 JES3 24 Oracle Applications 24 SAP R/3 24 master domain manager (MDM) 24 standard agent (SA) 24 Tivoli Workload Scheduler Bridge 173, 260 configuration 261 installation 260 Tivoli Workload Scheduler for Virtualized Data Centers 7 Tivoli Workload Scheduler for z/OS end-to-end 6
Tivoli Workload Scheduler for z/OS engine 24 Tivoli Workload Scheduler LoadLeveler 9 Tivoli Workload Scheduler Object Monitor 281 Tivoli Workload Scheduler ports 143 topmost domain 24 TotalMemory 63 traditional scheduling 5 Transmission Control Protocol (TCP) 42 trial plan 28 truststore 96 TWS See Tivoli Workload Scheduler TWS_LOG 151 TWSAgentConfig.properties 261 TWSEvent class 348 TWSEvent.rls 357 twsinst 137 TWSMERGE.log 296 TWSPlugIn.properties 343 TWSPluginConfiguration.xml 343 TWSUser 141
U
UNISON_JOB 125 UNISON_RUN 125 UNISON_SCHED 125 unixrsh 583 unixssh 583 UpdateInstaller 209 Upgrade Instance 140 utilization by user 9
V
Variables 323 VMWARE 577
W
wasadmin roles box 161 wasadmin user 161 Web Services 5, 28 WebSphere administrator 201 WebSphere Application Server 9, 28, 156 WebSphere Application Server V6.1 156 WebSphere Application Server V6.1.0.9 209 WebSphere Update installer 214 Windows 2000 258 Windows 2003 Server 210
630
wireless area network (WAN) 44 Workbench 344 workload 11 workload automation solutions 5 workload distribution process 61 workload infrastructure solution scenario 11 workload velocity 5 Workstation Name 221 workstation names 229 wr enable compression 44 wr read 44 writer 27 wstartesvr 351 wstopesvr 351
Y
YYMMDD_TWSERGE.log file 246
Z
Zen 577
Index
631
632
(1.0 spine) 0.875<->1.498 460 <-> 788 pages
Back cover
Deployment best practices and scheduling scenarios Planning and architecture Case studies and planning for engagement
IBM Tivoli Workload Scheduler and IBM Tivoli Dynamic Workload Broker are key products in the comprehensive, on demand IBM Tivoli Workload Automation portfolio. Tivoli Workload Scheduler is the IBM centralized job scheduler for distributed, mainframe, and end-to-end environments that allows you to do batch scheduling based on a calendar. Tivoli Dynamic Workload Broker extends Tivoli Workload Automation capabilities by providing dynamic optimization of workload processing based on the performance of the scheduling infrastructure and workload demands. In this easy-to-follow IBM Redbooks publication, we cover different scheduling scenarios with Tivoli Workload Scheduler V8.4 and Tivoli Dynamic Workload Broker V1.2 in distributed environments. We also discuss best practices for designing and implementing a scheduling solution for small, medium, and enterprise accounts. Finally, we cover the sales engagement planning for a Tivoli Workload Automation portfolio, including a sample statement of work. The primary audience for this section is Business Partners and pre-sales Systems Engineers working in this area. This book is a major reference for IT Specialists and IT Architects working in the Tivoli Workload Automation area.
INTERNATIONAL TECHNICAL SUPPORT ORGANIZATION
BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.
For more information: ibm.com/redbooks

SG24-7528-00 ISBN 0738485160

DemoSubmit A Job Stream

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

DemoSubmit A Job Stream

Uploaded by

Copyright:

Available Formats

Front cover

Vasfi Gucer Giuseppe Grammatico Martin Lisy Michael A Lowry

Copyright IBM Corp. 2008. All rights reserved.

Copyright IBM Corp. 2008. All rights reserved.

Copyright IBM Corp. 2008. All rights reserved.

Copyright IBM Corp. 2008. All rights reserved.

Copyright IBM Corp. 2008. All rights reserved.

The team that wrote this book

Copyright IBM Corp. 2008. All rights reserved.

Bohuslav Bezecny CEZData, s.r.o. Pavel Fruhauf PPF banka a.s.

Become a published author

Concepts and architecture

Copyright IBM Corp. 2008. All rights reserved.

Workload scheduling overview

Copyright IBM Corp. 2008. All rights reserved.

1.1 Market trends and directions

1.2 Business solutions

Chapter 1. Workload scheduling overview

1.3 IBM Tivoli Workload Automation portfolio

IBM Tivoli Workload Scheduler for Applications extends Tivoli Workload

IBM Tivoli Dynamic Workload Broker further extends Tivoli Workload

1.4 Tivoli Workload Automation in action

Chapter 1. Workload scheduling overview

IBM Software Group | Tivoli software

Tivoli workload automation portfolio for distributed solutions

Dynamic W orkload Broker

Enterprise W orkload Manager

Manages jobs across compute nodes

Figure 1-1 IBM Tivoli Workload Automation portfolio

Chapter 1. Workload scheduling overview

Workload Infrastructure Solution Scenario

Figure 1-2 Workload infrastructure solution scenario

Tivoli Workload Scheduler

generate_customer_price_list::job2 on system blue2 after generate_customer_price::job1

Figure 1-3 Tivoli Workload Scheduler

Chapter 1. Workload scheduling overview

Tivoli D ynam ic W orkload Broker

Dynam ic W orkload Broker

generate_custom er_price_list::job1 generate_custom er_price_list::job2

Figure 1-4 Tivoli Dynamic Workload Broker

Dynamic Workload Broker

generate_customer_price_list::job1 generate_customer_price_list::job2 check_price_record2 check_price_record2 check_price_record2

job2::check_price_record runs on several systems in parallel

Figure 1-5 IBM Tivoli LoadLeveler

Chapter 1. Workload scheduling overview

Enterprise Workload Manager

Dynamic Workload Broker

Enterprise Workload Manager

generate_customer_price_list::job1 generate_customer_price_list::job2 check_price_record2 check_price_record2 check_price_record2

Assign more I/O on system blue2 to job2::check_price_record2

Figure 1-6 Enterprise Workload Manager

1.4.1 Tivoli Workload Automation integration with IBM products

Chapter 1. Workload scheduling overview

Tivoli Workload Scheduler concepts and architecture

Copyright IBM Corp. 2008. All rights reserved.

2.2 Overview of Tivoli Workload Scheduler

2.3 Overview of Tivoli Dynamic Workload Broker

2.4 Tivoli Workload Scheduler architecture

Chapter 2. Tivoli Workload Scheduler concepts and architecture

2.4.1 The Tivoli Workload Scheduler network

Master Domain Manager

Chapter 2. Tivoli Workload Scheduler concepts and architecture

Domain Manager DMA