TWS 8.4 Reference Guide

Tivoli Workload Scheduler
Version 8.4
Reference Guide
SC32-1274-06
Tivoli Workload Scheduler
Version 8.4
Reference Guide
SC32-1274-06
Note Before using this information and the product it supports, read the information in Notices on page 573.
This edition applies to version 8, release 4, of IBM Tivoli Workload Scheduler (program number 5698-WSH) and to all subsequent releases and modifications until otherwise indicated in new editions. This edition replaces SC32127405. Copyright International Business Machines Corporation 1999, 2007. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . vii Tables . . . . . . . . . . . . . . . ix About this guide . . . . . . . . . . . xi
What is new in this release . . . . . . . . . xi What is new in this publication . . . . . . . . xi What is new in this publication for version 8.4 . . xi Who should read this guide . . . . . . . . xiii What this guide contains . . . . . . . . . xiii Publications . . . . . . . . . . . . . . xv Tivoli Workload Scheduler library . . . . . . xv Related publications . . . . . . . . . . xviii Accessing terminology online . . . . . . . xx Accessing publications online . . . . . . . xxi Ordering publications . . . . . . . . . xxii Using LookAt to look up message explanations xxii Accessibility . . . . . . . . . . . . . xxiii Tivoli technical training. . . . . . . . . . xxiii Support information . . . . . . . . . . . xxiii Conventions used in this publication . . . . . xxiii Typeface conventions . . . . . . . . . xxiv Operating system-dependent variables and paths . . . . . . . . . . . . . . . xxiv Command syntax . . . . . . . . . . . xxiv Customizing date formatting in the stdlist . . Customizing jobs processing on the workstation jobmanrc . . . . . . . . . . . . . . Customizing the MAIL_ON_ABEND section of jobmanrc . . . . . . . . . . . . . Customizing job processing for a user on UNIX workstations - .jobmanrc . . . . . . . . . . 24 . 25 . 26 . 27
Chapter 4. Setting up command-line authentication and user authorizations . 29

What is new in configuring user access . . . Setting up options for using the user interfaces Security management overview . . . . . . Centralized security management . . . . Updating the security file . . . . . . . . dumpsec . . . . . . . . . . . . makesec . . . . . . . . . . . . Configuring the security file . . . . . . . Specifying users . . . . . . . . . . Specifying objects . . . . . . . . . Specifying access . . . . . . . . . Sample security file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 29 31 32 33 34 35 36 38 40 43 51
Chapter 5. Managing the production cycle . . . . . . . . . . . . . . . 55

| What is new in managing the plan
. . . . . . Plan management basic concepts . . . . . . . Preproduction plan . . . . . . . . . . . . Identifying job stream instances in the plan . . . Managing external follows dependencies for jobs and job streams . . . . . . . . . . . . Production plan . . . . . . . . . . . . . Understanding carry forward options. . . . . Trial plan . . . . . . . . . . . . . . . Forecast plan . . . . . . . . . . . . . . Customizing plan management using global options Generating a production plan - JnextPlan . . . . Planman command line . . . . . . . . . . Creating an intermediate production plan . . . Creating an intermediate plan for a plan extension . . . . . . . . . . . . . . Retrieving the production plan information . . . Creating a trial plan . . . . . . . . . . Creating a trial plan of a production plan extension . . . . . . . . . . . . . . Creating a forecast plan . . . . . . . . . Deploying rules . . . . . . . . . . . . Unlocking the production plan . . . . . . . Resetting the production plan . . . . . . . The stageman command . . . . . . . . . . Managing concurrent accesses to the Symphony file Scenario 1: Access to Symphony file locked by other Tivoli Workload Scheduler processes . . . Scenario 2: Access to Symphony file locked by stageman . . . . . . . . . . . . . . 55 55 57 58 59 61 61 63 64 65 69 72 73 75 75 76 78 78 79 80 81 82 84 84 84
Chapter 1. Tivoli Workload Scheduler overview . . . . . . . . . . . . . . 1

Understanding basic concepts . . . . . . . . What is a Tivoli Workload Scheduler network . . How you configure your Tivoli Workload Scheduler runtime environment . . . . . . . How you define scheduling activities using Tivoli Workload Scheduler . . . . . . . . . . . How to control job and job stream processing . . How you manage production scheduling activities with Tivoli Workload Scheduler . . . . . . . How to automate workload using event rules . . Tivoli Workload Scheduler user interfaces . . . . Starting production . . . . . . . . . . . . 1 1 2 2 4 5 6 7 8
Chapter 2. Understanding workstation processes . . . . . . . . . . . . . 11

| What is new about workstation processes . . . . 11
Tivoli Workload Scheduler workstation processes . Starting and stopping processes on a workstation Workstation inter-process communication . . . Tivoli Workload Scheduler network communication Support for Internet Protocol version 6 . . . . 11 . 16 . 17 18 . 20
Chapter 3. Configuring the job environment . . . . . . . . . . . . 21

Job environment overview . . . . . . Environment variables exported by jobman .
Copyright IBM Corp. 1999, 2007
. .
. .
. 21 . 22
iii
Managing follows dependencies using carry forward prompt . . . . . . . . . . The logman command . . . . . . . . Starting production plan processing . . . Automating production plan processing . .
. . . .
. . . .
. . . .
84 85 87 87
system command unlock . . . . validate . . . version . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
237 238 241 242
| | | | | | | | |
Chapter 6. Running event-driven workload automation . . . . . . . . 89

The event rule management process . . . . . . 92 Using the involved interfaces and commands . . 93 Defining event rules . . . . . . . . . . . 95 Event rule examples . . . . . . . . . . 97 Rule operation notes . . . . . . . . . . 102 Triggered rule elements . . . . . . . . . . 103 Defining custom events . . . . . . . . . . 103
Chapter 9. Managing objects in the plan - conman . . . . . . . . . . . 243

|
What is new in managing objects in production Using the conman command line program . . Setting up the conman environment . . . . Running conman . . . . . . . . . . Running commands from conman . . . . . Wildcards . . . . . . . . . . . . Delimiters and special characters . . . . . Conman commands processing . . . . . Selecting jobs in commands . . . . . . . Syntax . . . . . . . . . . . . . . Arguments . . . . . . . . . . . . Selecting job streams in commands . . . . . Syntax . . . . . . . . . . . . . . Arguments . . . . . . . . . . . . Managing jobs and job streams from back-level agents . . . . . . . . . . . . . . . Command descriptions . . . . . . . . . adddep job . . . . . . . . . . . . adddep sched . . . . . . . . . . . altpass. . . . . . . . . . . . . . altpri . . . . . . . . . . . . . . bulk_discovery . . . . . . . . . . . cancel job. . . . . . . . . . . . . cancel sched . . . . . . . . . . . . confirm . . . . . . . . . . . . . console . . . . . . . . . . . . . continue . . . . . . . . . . . . . deldep job . . . . . . . . . . . . deldep sched . . . . . . . . . . . deployconf . . . . . . . . . . . . display . . . . . . . . . . . . . exit . . . . . . . . . . . . . . . fence . . . . . . . . . . . . . . help . . . . . . . . . . . . . . kill . . . . . . . . . . . . . . . limit cpu . . . . . . . . . . . . . limit sched . . . . . . . . . . . . link . . . . . . . . . . . . . . . listsym . . . . . . . . . . . . . recall . . . . . . . . . . . . . . redo . . . . . . . . . . . . . . release job . . . . . . . . . . . . release sched . . . . . . . . . . . reply . . . . . . . . . . . . . . rerun . . . . . . . . . . . . . . resource . . . . . . . . . . . . . setsym . . . . . . . . . . . . . . showcpus . . . . . . . . . . . . showdomain . . . . . . . . . . . showfiles . . . . . . . . . . . . . showjobs . . . . . . . . . . . . . showprompts . . . . . . . . . . . showresources . . . . . . . . . . . showschedules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 243 243 245 247 248 248 249 249 249 249 257 257 257 263 264 267 269 271 272 273 274 276 278 279 280 281 283 285 286 289 290 291 292 293 294 295 297 299 300 302 304 306 307 310 311 312 317 319 321 332 335 337
Chapter 7. Defining objects in the database . . . . . . . . . . . . . 105

| What is new in defining scheduling objects . . . 105
Defining scheduling objects . . . . Workstation definition . . . . . Workstation class definition . . . Domain definition . . . . . . . Job definition . . . . . . . . Windows user definition . . . . Calendar definition . . . . . . Parameter definition . . . . . . Prompt definition . . . . . . . Resource definition . . . . . . Job stream definition . . . . . . Job stream definition keyword details Event rule definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 108 115 117 119 125 127 128 130 132 133 137 178
Chapter 8. Managing objects in the database - composer . . . . . . . . 189

What is new in managing objects in the database Using the composer command-line program . . Setting up the composer environment . . . Running the composer program . . . . . Running commands from composer . . . . . Filters and wild cards . . . . . . . . Delimeters and special characters . . . . . Command descriptions . . . . . . . . . Referential integrity check . . . . . . . add. . . . . . . . . . . . . . . authenticate . . . . . . . . . . . . continue . . . . . . . . . . . . . create - extract . . . . . . . . . . . delete . . . . . . . . . . . . . . display . . . . . . . . . . . . . edit . . . . . . . . . . . . . . . exit . . . . . . . . . . . . . . . help . . . . . . . . . . . . . . list, print . . . . . . . . . . . . . lock . . . . . . . . . . . . . . modify . . . . . . . . . . . . . new . . . . . . . . . . . . . . redo . . . . . . . . . . . . . . rename . . . . . . . . . . . . . replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 190 190 191 194 194 196 197 198 203 205 206 207 210 213 217 218 219 220 224 227 231 232 234 236
iv
IBM Tivoli Workload Scheduler: Reference Guide
| | |
| | |
shutdown . . . . start . . . . . . startappserver . . . starteventprocessor . startmon . . . . . status . . . . . . stop . . . . . . stop ;progressive . . stopappserver . . . stopeventprocessor . stopmon . . . . . submit docommand . submit file . . . . submit job . . . . submit sched . . . switcheventprocessor . switchmgr . . . . system . . . . . tellop . . . . . . unlink . . . . . . version . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
341 342 345 346 347 348 349 351 352 353 354 355 358 361 363 366 367 368 369 370 372
Chapter 10. Using utility commands

| What is new in using utility commands
Command descriptions . . at and batch . . . . . cpuinfo . . . . . . datecalc . . . . . . delete . . . . . . . evtdef . . . . . . . evtsize. . . . . . . jobinfo. . . . . . . jobstdl . . . . . . . maestro . . . . . . makecal . . . . . . metronome.pl . . . . morestdl . . . . . . parms . . . . . . . release . . . . . . . rmstdlist . . . . . . sendevent . . . . . showexec . . . . . . shutdown . . . . . StartUp . . . . . . version . . . . . . Unsupported commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
373
. . . . . . . . . . . . . . . . . . . . . . . 373 373 375 378 380 384 385 388 390 392 394 395 397 398 400 403 404 405 407 408 409 410 412
| | | |
Report 01 - Job Details Listing: . . . . . . Report 02 - Prompt Listing: . . . . . . . . Report 03 - Calendar Listing: . . . . . . . Report 04A - Parameter Listing: . . . . . . Report 04B - Resource Listing: . . . . . . . Report 07 - Job History Listing: . . . . . . Report 08 - Job Histogram: . . . . . . . . Report 9B - Planned Production Detail: . . . . Report 10B - Actual Production Detail: . . . . Report 11 - Planned Production Schedule: . . . Report 12 - Cross Reference Report: . . . . . Report extract programs . . . . . . . . . . jbxtract . . . . . . . . . . . . . . prxtract . . . . . . . . . . . . . . caxtract . . . . . . . . . . . . . . paxtract . . . . . . . . . . . . . . rextract . . . . . . . . . . . . . . r11xtr . . . . . . . . . . . . . . . xrxtrct . . . . . . . . . . . . . . . Additional reports available on the Tivoli Dynamic Workload Console . . . . . . . . . . . . Historical reports . . . . . . . . . . . Production reports. . . . . . . . . . .
425 428 429 430 431 432 433 434 435 436 438 440 441 443 444 445 446 447 449 454 454 458
Chapter 12. Managing time zones . . . 461

| What is new about managing time zones . . . . 461
Enabling time zone management . . . . . . How Tivoli Workload Scheduler manages time zones . . . . . . . . . . . . . . . Moving to daylight saving time on . . . . . Moving to daylight saving time off . . . . . General rules . . . . . . . . . . . . Backward compatibility time zone table . . . Complete table of time zones with variable length notation . . . . . . . . . . . . . . . 461 . . . . . 462 464 464 464 465
. 466
Chapter 13. The auditing feature . . . 483

Auditing overview . . . Enabling the auditing feature Audit log format . . . . Audit log header format . Audit log body format . Sample audit log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483 483 484 484 484 487
Chapter 14. Managing extended agents . . . . . . . . . . . . . . 489

What are extended agents? . . . Workstation definition . . . Access method interface . . . . Method command line syntax . Method response messages . . Method options file . . . . Method running . . . . . . Launch job task (LJ) . . . . Manage job task (MJ) . . . . Check file task (CF) . . . . Get status task (GS) . . . . Cpuinfo command . . . . Troubleshooting . . . . . . Job standard list error messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489 490 490 490 492 493 494 494 495 495 495 496 496 496
Chapter 11. Getting reports and statistics . . . . . . . . . . . . . 413

| What is new in running reports and statistics. . . 413
Setup for using report commands Changing the date format . . Command descriptions . . . . rep1 - rep4b . . . . . . . rep7 . . . . . . . . . rep8 . . . . . . . . . rep11 . . . . . . . . . reptr . . . . . . . . . xref . . . . . . . . . . Sample report outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 414 414 416 417 419 421 422 424 425
Contents
Method not executable . . . . Console Manager messages . . . Composer and compiler messages Jobman messages . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
497 497 497 497
GenericAction actions
. 542
Appendix B. Web services interface
545
Chapter 15. Managing internetwork dependencies . . . . . . . . . . . 499

What is new about internetwork dependencies . Internetwork dependencies overview . . . . Understanding how an internetwork dependency is shown . . . . . . . . Configuring a network agent . . . . . . . A sample network agent definition . . . . Defining an internetwork dependency . . . . A sample internetwork dependency definition See Also . . . . . . . . . . . . . Managing internetwork dependencies . . . . States of jobs defined in the EXTERNAL job stream . . . . . . . . . . . . . . Working with jobs defined in the EXTERNAL job stream . . . . . . . . . . . . Sample internetwork dependency management scenarios . . . . . . . . . . . . . Internetwork dependencies in a mixed environment . . . . . . . . . . . . . . 499 . 499 500 501 502 503 503 . 504 . 504 . 504 . 505 . 505 . 507 . . . .
Appendix C. Quick reference for commands . . . . . . . . . . . . 547

Managing the plan . . . . . Managing objects in the database . General purpose commands . Scheduling objects . . . . . Composer commands . . . Managing objects in the plan . . Conman commands . . . . Utility commands . . . . . . Report commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 548 548 549 553 557 557 561 563
Appendix D. Support information . . . 565

Using IBM Support Assistant . . . . . . . . Tivoli Workload Scheduler IBM Support Assistant plug-in version and upgrade issues . . Searching knowledge bases . . . . . . . . . Searching the local information center . . . . Searching the Internet . . . . . . . . . Obtaining fixes . . . . . . . . . . . . . Receiving weekly support updates . . . . . . Contacting IBM Software Support . . . . . . Determining the business impact . . . . . . Describing problems and gathering information Submitting problems . . . . . . . . . . 565 565 566 566 566 567 567 569 570 570 570
| | | | | | | | | | |
Appendix A. Event-driven workload automation event and action definitions . . . . . . . . . . . . . 509

Event providers and definitions TWSObjectsMonitor events . FileMonitor events . . . Action providers and definitions TECEventForwarder actions MailSender actions . . . MessageLogger actions . . TWSAction actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 509 534 537 537 538 539 539
Notices . . . . . . . . . . . . . . 573
Trademarks . . . . . . . . . . . . . . 574
Glossary . . . . . . . . . . . . . 577 Index . . . . . . . . . . . . . . . 585
vi
Figures
1. 2. 3. 4. 5. 6. 7. 8. 9. Process tree in UNIX . . . . . . . . Process tree in Windows . . . . . . . Inter-process communication . . . . . . Closest preceding matching criteria . . . Within a relative interval matching criteria Within an absolute interval matching criteria Sameday matching criteria . . . . . . Closest preceding predecessor job . . . . Pending predecessor instance . . . . . . . . . 14 15 18 59 59 59 . 60 . 60 . 61 10. 11. 12. 13. 14. 15. 16. Network links . . . . . . . . Started workstations in network . . Stopped workstations in network . . Unlinked network workstations . . Example when start of day conversion applied . . . . . . . . . . Example when start of day conversion applied . . . . . . . . . . Local and remote networks . . . . . . . . is . is . . . . . . not . . . . . . . 296 343 350 371
. 463 . 463 . 502
vii
viii
Tables
| |
1. Documentation updates summary . . . . . xii 2. Command syntax . . . . . . . . . . xxiv 3. Starting and stopping Tivoli Workload Scheduler on a workstation . . . . . . . 16 4. Job environment variables for Windows 22 5. Job environment variables for UNIX . . . . 23 6. Variables defined by default in the jobmanrc file . . . . . . . . . . . . . . . 25 7. Object attributes . . . . . . . . . . . 40 8. Access keywords . . . . . . . . . . . 44 9. Carry forward global options settings . . . . 62 10. Resulting carry forward settings . . . . . 62 11. Simple event rule scenarios . . . . . . . 90 12. conman commands for managing monitoring engines . . . . . . . . . . . . . . 92 13. conman commands for managing the event processing server. . . . . . . . . . . 93 14. Interfaces and commands for managing event-driven workload automation . . . . . 94 15. Event rule definition for scenario1 . . . . . 98 16. Event rule definition for scenario2 . . . . . 99 17. Event rule definition for scenario3 . . . . 100 18. Event rule definition for scenario4 . . . . 101 19. Rule operation notes . . . . . . . . . 102 20. List of supported scheduling object keywords 106 21. List of reserved words when defining jobs and job streams . . . . . . . . . . . 106 22. List of reserved words when defining workstations . . . . . . . . . . . . 107 23. List of reserved words when defining users 107 24. Option settings for workstation types 109 25. Type of communication depending on the security level value . . . . . . . . . 112 26. Comparison operators . . . . . . . . 121 27. Logical operators . . . . . . . . . . 121 28. Recovery options and actions . . . . . . 122 29. List of scheduling keywords . . . . . . 134 30. Explanation of the notation defining the number of occurrences for a language element. . . . . . . . . . . . . . 178 31. TWSObjectsMonitor events. . . . . . . . 181 32. FileMonitor events. . . . . . . . . . 182 33. Action types by action provider. . . . . . 184 34. Scheduling objects filtering criteria . . . . 195 35. Delimeters and special characters for composer . . . . . . . . . . . . . 196 36. List of composer commands . . . . . . 197 37. Object identifiers for each type of object defined in the database . . . . . . . . 199 38. Object definition update upon deletion of referenced object . . . . . . . . . . 199 39. Referential integrity check when deleting an object from the database . . . . . . . . 200 40. Output formats for displaying scheduling objects . . . . . . . . . . . . . . 215 41. Output formats for printing scheduling objects . . . . . . . . . . . . . . 42. Delimeters and special characters for conman 43. List of conman commands . . . . . . . 44. State change after confirm command 45. Opened links . . . . . . . . . . . 46. Started workstations . . . . . . . . . 47. Stopped workstations . . . . . . . . . 48. Stopped workstations with stop ;progressive 49. Unlinked workstations . . . . . . . . 50. List of utility commands . . . . . . . . 51. Date formats . . . . . . . . . . . . 52. List of report commands . . . . . . . . 53. Report extract programs. . . . . . . . . 54. Jbxtract output fields . . . . . . . . . 55. Prxtract output fields . . . . . . . . . 56. Caxtract output fields . . . . . . . . . 57. Paxtract output fields . . . . . . . . . 58. Rextract output fields . . . . . . . . . 59. R11xtr output fields . . . . . . . . . 60. Xdep_job output fields . . . . . . . . 61. Xdep_job output fields (continued) . . . . 62. Xdep_sched output fields . . . . . . . 63. Xfile output fields . . . . . . . . . . 64. Xjob output fields . . . . . . . . . . 65. Xprompts output fields . . . . . . . . 66. Xresource output fields . . . . . . . . 67. Xsched output fields . . . . . . . . . 68. Xwhen output fields . . . . . . . . . 69. Summary of historical reports . . . . . . 70. Summary of production reports . . . . . 71. Backward compatibility time zone table 72. Variable length notation time zones list 73. Method command task options . . . . . 74. Launch job task (LJ) messages . . . . . . 75. Check file task (CF) messages . . . . . . 76. Get status task (GS) messages . . . . . . 77. Internetwork dependencies in a mixed environment . . . . . . . . . . . . 78. Parameters of JobStatusChanged event types. 79. Parameters of JobUntil event types. . . . . 80. Parameters of JobSubmit event types. 81. Parameters of JobCancel event types. 82. Parameters of JobRestart event types. 83. Parameters of JobLate event types. . . . . 84. Parameters of JobStreamStatusChanged event types. . . . . . . . . . . . . . . 85. Parameters of JobStreamCompleted event types. . . . . . . . . . . . . . . 86. Parameters of JobStreamUntil event types. 87. Parameters of JobStreamSubmit event types. 88. Parameters of JobStreamCancel event types. 89. Parameters of JobStreamLate event types. 90. Parameters of WorkstationStatusChanged event types. . . . . . . . . . . . . 222 248 264 278 296 343 350 351 371 373 414 414 440 441 443 444 445 446 447 449 449 450 450 451 451 452 452 453 454 459 465 466 491 494 495 496 507 510 511 513 515 516 518 520 522 523 525 526 527 529
| | | | | | | | | | | | |
| |
| | | | | |
| | | | | | | | | | | | | | | |
ix
| 91. Parameters of ApplicationServerStatusChanged event types. . | | 92. Parameters of ChildWorkstationLinkChanged event types. . . . . . . . . . . . . | | 93. Parameters of ParentWorkstationLinkChanged event types. . . . . . . . . . . . . | | 94. Parameters of PromptStatusChanged event types. . . . . . . . . . . . . . . | | 95. Parameters of FileCreated event types. | 96. Parameters of FileDeleted event types. | 97. Parameters of ModificationCompleted event types. . . . . . . . . . . . . . . | | 98. Parameters of LogMessageWritten event types. . . . . . . . . . . . . . . | | 99. Parameters of TECFWD action types. | 100. Parameters of SendMail action types. | 101. Parameters of MSGLOG action types. | 102. Parameters of SubmitJobStream action types.
530 531 531 532 534 535 535 536 537 538 539 539
| | | |
103. 104. 105. 106. 107. 108. 109. 110. 111. 112. 113. 114. 115. 116.
Parameters of SubmitJob action types. Parameters of SubmitAdHocJob action types. Parameters of ReplyPrompt action types. Parameters of RunCommand action types. Available messages in the Web services interface . . . . . . . . . . . . . Commands used against the plan . . . . . General purpose commands . . . . . . Commands used against scheduling objects in the database . . . . . . . . . . . . Commands that can be run from conman Utility commands available for both UNIX and Windows . . . . . . . . . . . Utility commands available for UNIX only Utility commands available for Windows only Report commands . . . . . . . . . . Report extract programs . . . . . . . .
540 541 542 542 546 547 548 553 558 561 562 562 563 564
About this guide

IBM Tivoli Workload Scheduler simplifies systems management across distributed environments by integrating systems management functions. Tivoli Workload Scheduler plans, automates, and controls the processing of your enterprises entire production workload. The Tivoli Workload Scheduler Reference Guide provides detailed information about the command line interface, scheduling language, and utility commands for Tivoli Workload Scheduler.
What is new in this release

For information about the new or changed functions in this release, see Tivoli Workload Scheduling Suite: Overview. For information about the APARs that this release addresses, see the Tivoli Workload Scheduler Download Document at http://www.ibm.com/support/ docview.wss?rs=672&uid=swg24016672.
What is new in this publication

This section describes what has changed in this publication since version 8.3.02. Note: Throughout the document, changed or added text is marked by a revision bar in the left margin.
What is new in this publication for version 8.4

For version 8.4, the following changes have been made to document the new features:
xi
What is new in this guide

Table 1. Documentation updates summary Feature Event-driven workload automation Description Documentation changes
Provides the capability to v Chapter 1, Tivoli Workload Scheduler overview, define and run rules that carry on page 1 includes section How to automate out predefined actions in workload using event rules on page 6. response to predefined events. v Chapter 2, Understanding workstation processes, on page 11 describes the monman process. v Chapter 4, Setting up command-line authentication and user authorizations, on page 29 documents additional security file authorizations for defining and using event rules and for managing the event rule management agents and server v Chapter 5, Managing the production cycle, on page 55 describes the new planman deploy command for manual rule deployment. v Chapter 6, Running event-driven workload automation, on page 89 provides an overview of the event rule management feature. v Chapter 7, Defining objects in the database, on page 105 provides reference for defining event rules. v Chapter 8, Managing objects in the database composer, on page 189 provides reference for managing event rule definitions. v Chapter 9, Managing objects in the plan - conman, on page 243 provides reference for the new commands that start, stop, and switch the event processing server, start and stop the monitoring manager, download the latest monitoring configuration file, and show the event rules deployed on an agent. v Chapter 10, Using utility commands, on page 373 provides reference for the new commands for defining custom events and for forwarding them to the event processing server. v Appendix A, Event-driven workload automation event and action definitions, on page 509 documents in detail all available event and action types and their properties.
xii
What is new in this guide

Table 1. Documentation updates summary (continued) Feature Application server manager service (appserverman) Description Starts the embedded WebSphere Application Server and restarts it automatically if it goes down. Documentation changes v Chapter 2, Understanding workstation processes, on page 11 describes the appserverman process. Section Starting and stopping processes on a workstation on page 16 has changed to reflect changes in startup commands. v Chapter 4, Setting up command-line authentication and user authorizations, on page 29 documents additional security file authorizations for starting and stopping the applications server. v Chapter 5, Managing the production cycle, on page 55 in section Generating a production plan JnextPlan on page 69 explains how the JnextPlan command and the final job stream now start WebSphere Application Server automatically as their first step, eliminating the need to run the CheckPrerequisites script. v Chapter 9, Managing objects in the plan - conman, on page 243 provides reference for the new commands that start and stop the application server. Tivoli Dynamic Workload Console history and production reports Additional reports that can be run on the Tivoli Dynamic Workload Console. v An overview of these reports is in Additional reports available on the Tivoli Dynamic Workload Console on page 454. Detailed online help is provided by the Tivoli Dynamic Workload Console. v Chapter 4, Setting up command-line authentication and user authorizations, on page 29 documents additional security file authorizations for running the reports. Support for Internet Protocol version 6 New time zones Support for this new version along with the previous one. Support for new time zones has been added. Chapter 2, Understanding workstation processes, on page 11 includes an overview in section Support for Internet Protocol version 6 on page 20. Chapter 12, Managing time zones, on page 461 shows an updated list of all supported time zones in Table 72 on page 466.
Who should read this guide

This guide is intended for administrators and advanced users of Tivoli Workload Scheduler.
What this guide contains

This manual contains the following chapters and appendixes: v Chapter 1, Tivoli Workload Scheduler overview, on page 1 Provides you with a quick introduction to Tivoli Workload Scheduler and its user interfaces, and explains the basic steps a new user should follow to begin to use the product for the first time. v Chapter 2, Understanding workstation processes, on page 11 Describes workstation processes and network communication in a Tivoli Workload Scheduler environment during job processing. v Chapter 3, Configuring the job environment, on page 21
About this guide
xiii

Describes how to customize the way job management is performed on a workstation. Chapter 4, Setting up command-line authentication and user authorizations, on page 29 Describes how to set up the user environment to use command line programs and how to manage user access to objects using the security file. Chapter 5, Managing the production cycle, on page 55 Describes how Tivoli Workload Scheduler performs plan management. Chapter 6, Running event-driven workload automation, on page 89 Provides an overview of event rule management. Chapter 7, Defining objects in the database, on page 105 Describes the scheduling objects, including job streams with the related keywords, that you can define in the Tivoli Workload Scheduler DB2 database.
v v v
v Chapter 8, Managing objects in the database - composer, on page 189 Explains the usage and the syntax of the commands used in the composer command-line interface to manage scheduling objects in the database. v Chapter 9, Managing objects in the plan - conman, on page 243 Describes the usage and the syntax of the commands used in the conman command-line interface to monitor and manage job and job stream instances in production. v Chapter 10, Using utility commands, on page 373 Describes the Tivoli Workload Scheduler utility commands that manage the environment. v Chapter 11, Getting reports and statistics, on page 413 Describes how to use different types of reports. v Chapter 12, Managing time zones, on page 461 Describes how to manage the time zones with Tivoli Workload Scheduler. v Chapter 13, The auditing feature, on page 483 Describes how to enable and use the auditing option to track changes applied to the database and to the plan. v Chapter 14, Managing extended agents, on page 489 Describes how to create and use extended agents, that is logical definitions, each hosted by a physical workstation, used to perform job processing where an agent is not installed. v Chapter 15, Managing internetwork dependencies, on page 499 Describes how to create and use a network agent workstation to manage dependencies of locally defined jobs and job streams from jobs and job streams running in a remote Tivoli Workload Scheduler network. v Appendix A, Event-driven workload automation event and action definitions, on page 509 Provides a complete description of all event and action types for use when defining event rules. v Appendix B, Web services interface, on page 545 Gives an introduction to the use of the Tivoli Workload Scheduler Web Services Interface. v Appendix C, Quick reference for commands, on page 547 Contains a quick reference for commands. It also includes utility and report commands.
xiv

v Appendix D, Support information, on page 565 Describes how to obtain support for IBM products.
Publications
This section lists publications in the Tivoli Workload Scheduler library and any other related publications. It also describes how to access Tivoli publications online and how to order Tivoli publications.
Tivoli Workload Scheduler library

Tivoli Workload Scheduler comprises several separate products available for a variety of operating systems. The library is divided into: IBM Tivoli Workload Scheduling suite library This library contains all cross-platform and cross-product publications for Tivoli Workload Scheduler. IBM Tivoli Workload Scheduler distributed library This library contains all of the publications that refer to the use of Tivoli Workload Scheduler on operating systems other than z/OS. IBM Tivoli Workload Scheduler for z/OS library This library contains all publications that apply only to IBM Tivoli Workload Scheduler for z/OS. IBM Tivoli Workload Scheduler for Applications library This library contains all publications that apply only to IBM Tivoli Workload Scheduler for Applications. IBM Tivoli Workload Scheduler for Virtualized Data Centers library This library contains all publications that apply only to IBM Tivoli Workload Scheduler for Virtualized Data Centers.
IBM Tivoli Workload Scheduling suite library

The following publications are available in the IBM Tivoli Workload Scheduling suite library. This library includes publications that are common to all products, operating systems, and components. v Tivoli Workload Scheduling Suite: Overview, SC32-1256 Provides an overview of all Tivoli Workload Scheduler products, and the way they can be used together to provide workload management solutions for your whole enterprise. Note: This manual used to be called "General Information". v Tivoli Workload Scheduler: Dynamic Workload Console Installation and Troubleshooting Guide, SC32-1572 Describes how to work with Tivoli Workload Scheduler, regardless of operating system, using a common Web-based GUI called the Dynamic Workload Console. v Tivoli Dynamic Workload Console Download Document at http:// www.ibm.com/support/docview.wss?rs=672&uid=swg24016672 This provides full information about downloading the product CD images. It also indicates the APARs that have been fixed in this release. v Tivoli Dynamic Workload Console System Requirements Document at http://www.ibm.com/support/docview.wss?rs=672&uid=swg27010503 This provides full information about the hardware and software prerequisites of the product.
About this guide
xv
Publications
v Tivoli Workload Scheduler: Job Scheduling Console Users Guide, SC32-1257 Describes how to work with Tivoli Workload Scheduler, regardless of operating system, using a common GUI called the Job Scheduling Console. v Tivoli Workload Scheduler, version 8.3: Warehouse Enablement Pack version 1.1.1 Implementation Guide for Tivoli Data Warehouse, versions 1.2 and 1.3 Provides information about enabling Tivoli Workload Scheduler for Tivoli Data Warehouse. This publication is only available on the Tivoli Workload Scheduler Engine Installation CD "TWS84_OTHER", in the following path: TDW_enablement_pack/tdw_weps/aws/v8300/doc/itws_for_TDW.doc You cannot access it online, in the same way that you can the other books (see Accessing publications online on page xxi).
IBM Tivoli Workload Scheduler distributed library

The following publications are available in the IBM Tivoli Workload Scheduler distributed library. This library contains publications that refer to using the product on distributed operating systems (all operating systems except z/OS). v Tivoli Workload Scheduler: Quick Start Guide, GC23-6141 Provides information on how to get started with an installation of Tivoli Workload Scheduler on distributed operating systems. v Tivoli Workload Scheduler Download Document at http://www.ibm.com/ support/docview.wss?rs=672&uid=swg24016672 This provides full information about downloading the product CD images. It also indicates the APARs that have been fixed in this release. v Tivoli Workload Scheduler System Requirements Document at http://www.ibm.com/support/docview.wss?rs=672&uid=swg27010396 This provides full information about the hardware and software prerequisites of the product. Tivoli Workload Scheduler: Planning and Installation Guide, SC32-1273 Describes how to plan for and install IBM Tivoli Workload Scheduler on distributed operating systems, and how to integrate Tivoli Workload Scheduler with NetView, Tivoli Data Warehouse, Tivoli Monitoring, and Tivoli Enterprise Console. Tivoli Workload Scheduler: Reference Guide, SC32-1274 Provides an explanation of the concepts of Tivoli Workload Scheduler and describes how the product is used. Also describes the Tivoli Workload Scheduler command line used on distributed operating systems, and how extended and network agents work. Tivoli Workload Scheduler: Administration and Troubleshooting, SC32-1275 Provides information about how to administer Tivoli Workload Scheduler on distributed operating systems, and what to do if things go wrong. It includes help on many messages generated by the main components of Tivoli Workload Scheduler. Tivoli Workload Scheduler: Database Views, SC32-2261 Provides information about the views of the IBM Tivoli Workload Scheduler database. Tivoli Workload Scheduler: Using Microsoft Cluster Service on Windows Server 2003, SC23-6119 Describes how to use Tivoli Workload Scheduler with the Microsoft Cluster service on Windows Server 2003 to achieve high availability.
xvi
Publications
v Tivoli Workload Scheduler: Limited Fault-tolerant Agent for i5/OS, SC32-1280 Describes how to install, configure, and use Tivoli Workload Scheduler limited fault-tolerant agents on i5/OS. v Java API documentation. Provides information about using the Java Application Programming Interface (API). This is a set of available classes and methods running in a JAVA environment that you use to create a custom interface to manage scheduling objects in the database and in the plan. They cannot be used to manage the plan or to set global options. Documentation for the API is provided on all distributed product CDs. Mount the CD for your platform and open the following file with your Internet browser: <CD_drive>/API/doc/index.html. See http://www.ibm.com/software/tivoli/products/scheduler/ for an introduction to the product.
IBM Tivoli Workload Scheduler for z/OS library

The following publications are available in the Tivoli Workload Scheduler for z/OS library: v Tivoli Workload Scheduler for z/OS: Getting Started, SC32-1262 Discusses how to define your installation data for Tivoli Workload Scheduler for z/OS and how to create and modify plans. v Tivoli Workload Scheduler for z/OS: Installation Guide, SC32-1264 Describes how to install Tivoli Workload Scheduler for z/OS. v Tivoli Workload Scheduler for z/OS: Customization and Tuning, SC32-1265 Describes how to customize Tivoli Workload Scheduler for z/OS. v Tivoli Workload Scheduler for z/OS: Managing the Workload, SC32-1263 Explains how to plan and schedule the workload and how to control and monitor the current plan. v Tivoli Workload Scheduler for z/OS: Quick Reference, SC32-1268 Provides a quick and easy consultation reference to operate Tivoli Workload Scheduler for z/OS. v Tivoli Workload Scheduler for z/OS: Diagnosis Guide and Reference, SC32-1261 Provides information to help diagnose and correct possible problems when using Tivoli Workload Scheduler for z/OS. v Tivoli Workload Scheduler for z/OS: Messages and Codes, SC32-1267 Explains messages and codes in Tivoli Workload Scheduler for z/OS. v Tivoli Workload Scheduler for z/OS: Programming Interfaces, SC32-1266 Provides information to write application programs for Tivoli Workload Scheduler for z/OS. v Tivoli Workload Scheduler for z/OS: Scheduling End-to-end, SC32-1732 Provides information on how to integrate Tivoli Workload Scheduler for z/OS with Tivoli Workload Scheduler, controlling workload in a distributed environment from a z/OS master domain manager. v Tivoli Workload Scheduler for z/OS: Memo to Users, GI11-4209 Provides a summary of changes for the current release of the product.
About this guide
xvii
Publications
v Tivoli Workload Scheduler for z/OS: Program Directory, GI11-4248 Provided with the installation tape for Tivoli Workload Scheduler for z/OS, describes all of the installation materials and gives installation instructions specific to the product release level or feature number. See http://www.ibm.com/software/tivoli/products/scheduler-zos/ for an introduction to the product.
IBM Tivoli Workload Scheduler for Applications library

The following publications are available in the IBM Tivoli Workload Scheduler for Applications library: v Tivoli Workload Scheduler for Applications: Users Guide, SC32-1278 Provides information on how to install, set up, and use the IBM Tivoli Workload Scheduler access methods that run and control jobs of the following applications: Oracle PeopleSoft R/3 z/OS v Tivoli Workload Scheduler for Applications: Quick Start Guide, GC32-1538 Gives an overview on how to get started with Tivoli Workload Scheduler for Applications. v Tivoli Workload Scheduler for Applications Download Document at http://www.ibm.com/support/docview.wss?rs=673&uid=swg24013044 This provides full information about downloading the product CD images. It also indicates the APARs that have been fixed in this release. v Tivoli Workload Scheduler for Applications System Requirements Document at http://www.ibm.com/support/docview.wss?rs=673&uid=swg27007885 This provides full information about the hardware and software prerequisites of the product. See http://www.ibm.com/software/tivoli/products/scheduler-apps/ for an introduction to the product.
IBM Tivoli Workload Scheduler for Virtualized Data Centers library

The following publications are available in the IBM Tivoli Workload Scheduler for Virtualized Data Centers library: v Tivoli Workload Scheduler for Virtualized Data Centers: Users Guide, SC32-1454 Describes how to extend the scheduling capabilities of Tivoli Workload Scheduler to workload optimization and grid computing by enabling the control of IBM LoadLeveler and IBM Grid Toolbox jobs. v Tivoli Workload Scheduler for Virtualized Data Centers: Release Notes, SC32-1453 Provides late-breaking information about Tivoli Workload Scheduler for Virtualized Data Centers. See http://www.ibm.com/software/info/ecatalog/en_US/ products/ Y614224T20392S50.html for an introduction to the product.
Related publications
The following publications also provide useful information:
xviii
Publications
v IBM Redbooks: Getting Started with IBM Tivoli Workload Scheduler V8.3: Best Practices and Performance Improvements, SG24-7237 Abstract: IBM Tivoli Workload Scheduler is an IBM strategic scheduling product that runs on different platforms including the mainframe. The new version of the product, IBM Tivoli Workload Scheduler V8.3, comes with some important enhancements, such as relational database management system support, new advanced planning system, which allows the definition of plans that span more that 24 hours, removal of framework requirements, new application programming interface (API), Job Scheduling Console enhancements, and so on. This IBM Redbook documents the architecture, deployment, best practices, and migration scenarios for IBM Tivoli Workload Scheduler V8.3 in a distributed environment. In addition, it covers IBM Tivoli Workload Scheduler V8.3 security, IBM DB2 and IBM WebSphere considerations, troubleshooting, tuning for performance, application programming interface, and JnextPlan, which has replaced the JnextDay process in this release. Clients and Tivoli professionals who are responsible for installing, administering, maintaining, or using IBM Tivoli Workload Scheduler V8.3 will find this book a major reference. This Redbook can be found on the Redbooks Web site at http:// www.redbooks.ibm.com/abstracts/sg247237.html v IBM Redbooks: Customizing IBM Tivoli Workload Scheduler for z/OS V8.2 to Improve Performance, SG24-6352 Abstract: This IBM Redbook covers the techniques that can be used to improve the performance of Tivoli Workload Scheduler for z/OS (including end-to-end scheduling). This Redbook can be found on the Redbooks Web site at http:// www.redbooks.ibm.com/abstracts/sg246352.html v IBM Redbooks: IBM Tivoli Workload Scheduler for z/OS: Best Practices, SG24-7156 Abstract: This IBM Redbook describes best practices for using Tivoli Workload Scheduler for z/OS. Topics covered include: Installation best practices Installation verification Started tasks Communication Initialization statements and parameters Security Exits Restart and cleanup Dataset triggering and event trigger tracking Variables Audit report facility This Redbook can be found on the Redbooks Web site at http:// www.redbooks.ibm.com/abstracts/sg247156.html v IBM Redbooks: Integrating IBM Tivoli Workload Scheduler with Tivoli Products, SG24-6648 Abstract: This IBM Redbook explains the benefits and technical merits of integrating IBM Tivoli Workload Scheduler Distributed and IBM Tivoli Workload Scheduler for z/OS with other IBM products. Scheduling is a mission critical process for any company. However, when you talk about scheduling, you are really talking about an ecosystem. In this ecosystem, each solution is a building
About this guide
xix
Publications
block that adds value to the overall solution. With IBM Tivoli Workload Scheduler, you can collect and add data to and from each component. In addition, expanding the scheduling ecosystem to include monitoring, management, help desk, storage, and business systems management provides greater value. This book discusses all these integration points and provides detailed scenarios on how to integrate IBM Tivoli Workload Scheduler with these types of applications. Because workload management is widely considered the nucleus of the data center, there are numerous opportunities for you to integrate IBM Tivoli Workload Scheduler with other products. This book addresses just some of these many opportunities. In terms of integration with IBM Tivoli Workload Scheduler, do not limit yourself to the products that this book discusses. Integration points discussed in this book should give you an idea of the potential value that IBM Tivoli Workload Scheduler integration can provide for your company. This Redbook can be found on the Redbooks Web site at http:// www.redbooks.ibm.com/abstracts/sg246648.html v IBM Redbooks: WebSphere Application Server V6 System Management & Configuration Handbook, SG24-6451 Abstract: This IBM Redbook provides system administrators, developers, and architects with the knowledge to configure a WebSphere Application Server V6 runtime environment, to package and deploy Web applications, and to perform ongoing management of the WebSphere environment. One in a series of handbooks, the entire series is designed to give you in-depth information about the entire range of WebSphere Application Server products. In this book, we provide a detailed exploration of the WebSphere Application Server V6 runtime environments and administration process. This Redbook can be found on the Redbooks Web site at http:// www.redbooks.ibm.com/abstracts/sg246451.html For all types of information about DB2, go to the DB2 Information Center: http://publib.boulder.ibm.com/infocenter/db2luw/v8//index.jsp For all types of information about the WebSphere Application Server, go to the WebSphere Application Server Information Center: http://publib.boulder.ibm.com/ infocenter/wasinfo/v6r0/index.jsp
Accessing terminology online

The Tivoli Software Glossary includes definitions for many of the technical terms related to Tivoli software. The Tivoli Software Glossary is available at the following Tivoli software library Web site: http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm The IBM Terminology Web site consolidates the terminology from IBM product libraries in one convenient location. You can access the Terminology Web site at the following Web address: http://www.ibm.com/software/globalization/terminology
xx
Publications
Accessing publications online

The Tivoli Workload Scheduler documentation CD contains the publications that are in the product library. The format of the publications is PDF, HTML, or both. The publications are found within a Tivoli Information Center. Place the CD in the CD drive of a Windows computer and the Information Center automatically opens. If the Information Center does not open automatically, or you require more information, consult the readme.txt file in the root of the CD. IBM posts publications for this and all other Tivoli products, as they become available and whenever they are updated, to the Tivoli software information center Web site. There are two ways of accessing the Tivoli software information center: Directly access the IBM Tivoli Workload Scheduler Information Center Go directly to the Information Center at the following Web address: http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jsp?toc=/ com.ibm.tivoli.itws.doc/toc.xml Access the IBM Tivoli Workload Scheduler Information Center from the Tivoli Technical Product Documents Web site Access the Tivoli software information center by following these steps: 1. Go to the Tivoli library at the following Web address: http://www.ibm.com/software/tivoli/library/ 2. Click Tivoli product manuals 3. In the Tivoli Technical Product Documents Alphabetical Listing window, click W (for Workload Scheduler) or scroll down to the W section of the product list 4. Click the appropriate Tivoli Workload Scheduler product link to access your product libraries at the Tivoli software information center. All publications in the Tivoli Workload Scheduler suite library, distributed library, and z/OS library can be found under the entry Tivoli Workload Scheduler. The Tivoli software information center page for Tivoli Workload Scheduler is displayed. It gives you access to the publications relating to the latest version of the product. Links are provided to the documentation of prior versions. 5. Click to access the Tivoli Workload Scheduler Information Center. The Information Center is Eclipse-based, and contains full instructions on how to use it to obtain information and search the publications for specific terms.
Note: If you print PDF publications on other than letter-sized paper, set the option in the File Print window that enables Adobe Reader to print letter-sized pages on your local paper. For all types of information about DB2, go to the DB2 Information Center: http://publib.boulder.ibm.com/infocenter/db2luw/v8//index.jsp For all types of information about the Embedded Version of the WebSphere Application Server version 6.1, go to the WebSphere Application Server Information Center: http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/ index.jsp. Note: The Embedded Version of the WebSphere Application Server version 6.1 is not the same as WebSphere Application Server - Express. It is a runtime
About this guide
xxi
Publications
version of WebSphere Application Server, version 6.1 which is bundled in and managed by Tivoli Workload Scheduler. For all types of information about the Oracle database, consult the documentation of Oracle Corporation. When this manual was published, the relevant documentation could be found on http://www.oracle.com/technology/ documentation/index.html. Note: This information has been included as a courtesy, and IBM cannot guarantee that this URL will continue to be correct.
Tivoli Workload Scheduler online books

All the books in the Tivoli Workload Scheduler for z/OS library are available in displayable softcopy form on CD in the IBM Online Library: z/OS Software Products Collection Kit, SK3T-4270. You can read the softcopy books on CD using these IBM licensed programs: v BookManager READ/2 (program number 5601-454) v BookManager READ/DOS (program number 5601-453) v BookManager READ/6000 (program number 5765-086) All the BookManager programs need a personal computer equipped with a CD drive (capable of reading disks formatted in the ISO 9660 standard) and a matching adapter and cable. For additional hardware and software information, refer to the publications for the specific BookManager product you are using. Updates to books between releases are provided in softcopy only.
Ordering publications
You can order many Tivoli publications online at the following Web site: http://www.elink.ibmlink.ibm.com/public/applications/ publications/cgibin/ pbi.cgi You can also order by telephone by calling one of these numbers: v In the United States: 800-879-2755 v In Canada: 800-426-4968 v In other countries, contact your software account representative to order Tivoli publications. To locate the telephone number of your local representative perform the following steps: 1. Go to the following Web site: http://www.elink.ibmlink.ibm.com/public/applications/ publications/cgibin/pbi.cgi 2. Select your country from the list and click . The IBM Publications Center page is displayed. 3. Click About this site in the main panel to see an information page which includes the telephone number of your local representative.
Using LookAt to look up message explanations

LookAt is an online facility that lets you look up explanations for most messages you encounter, as well as for some system abends and codes. Using LookAt to find information is faster than a conventional search because in most cases LookAt goes directly to the message explanation.
xxii
Using LookAt
You can access LookAt from the Internet at: http://www.ibm.com/eserver/zseries/zos/bkserv/lookat/ or from anywhere in z/OS or z/OS.e where you can access a TSO/E command line (for example, TSO/E prompt, ISPF, z/OS UNIX System Services running OMVS). The LookAt Web site also features a mobile edition of LookAt for devices such as Pocket PCs, Palm OS, or Linux-based handhelds. So, if you have a handheld device with wireless access and an Internet browser, you can now access LookAt message information from almost anywhere.
Accessibility
Accessibility features help users with a physical disability, such as restricted mobility or limited vision, to use software products successfully. With this product, you can use assistive technologies to hear and navigate the interface. You can also use the keyboard instead of the mouse to operate all features of the graphical user interface. For additional information, see the Accessibility Appendix in the IBM Tivoli Workload Scheduler Planning and Installation Guide.
Tivoli technical training

For Tivoli technical training information, refer to the following IBM Tivoli Education Web site: http://www.ibm.com/software/tivoli/education
Support information
If you have a problem with your IBM software, you want to resolve it quickly. IBM provides the following ways for you to obtain the support you need: v Searching knowledge bases: You can search across a large collection of known problems and workarounds, Technotes, and other information. v Obtaining fixes: You can locate the latest fixes that are already available for your product. v Contacting IBM Software Support: If you still cannot solve your problem, and you need to work with someone from IBM, you can use a variety of ways to contact IBM Software Support. For more information about these three ways of resolving problems, see Appendix D, Support information, on page 565.
Conventions used in this publication

This publication uses several conventions for special terms and actions, operating system-dependent commands and paths, command syntax, and margin graphics.
About this guide
xxiii
Conventions
Typeface conventions
This publication uses the following typeface conventions: Bold v Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text v Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multicolumn lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip:, and Operating system considerations:) v Keywords and parameters in text Italic v v v v Words defined in text Emphasis of words (words as words) New terms in text (except in a definition list) Variables and values you must provide
Monospace v Examples and code examples v File names, programming keywords, and other elements that are difficult to distinguish from surrounding text v Message text and prompts addressed to the user v Text that the user must type v Values for arguments or command options
Operating system-dependent variables and paths

This publication uses the UNIX convention for specifying environment variables and for directory notation, except where the context or the example path is specifically Windows. When using the Windows command line, replace $variable with % variable% for environment variables and replace each forward slash (/) with a backslash (\) in directory paths. The names of environment variables are not always the same in Windows and UNIX environments. For example, %TEMP% in Windows is equivalent to $tmp in UNIX environments. Note: If you are using the bash shell on a Windows system, you can use the UNIX conventions.
Command syntax
This publication uses the following syntax wherever it describes commands:
Table 2. Command syntax Syntax Description convention Name of command Brackets ([ ]) The first word or set of consecutive characters. The information enclosed in brackets ([ ]) is optional. Anything not enclosed in brackets must be specified. Example conman [-file definition_file]
xxiv
Conventions
Table 2. Command syntax (continued) Syntax Description convention Braces ({ }) Braces ({ }) identify a set of mutually exclusive options, when one option is required. Underscore An underscore (_) connects multiple (_) words in a variable. Vertical bar Mutually exclusive options are (|) separated by a vertical bar ( | ). You can enter one of the options separated by the vertical bar, but you cannot enter multiple options in a single use of the command. Bold Bold text designates literal information that must be entered on the command line exactly as shown. This applies to command names and non-variable options. Italic text is variable and must be replaced by whatever it represents. In the example to the right, the user would replace file_name with the name of the specific file. composer add file_name Example {-prompts | -prompt prompt_name }
prompt_name {-prompts | -prompt prompt_name }
Italic
file_name
Ellipsis (...) An ellipsis (...) indicates that the [x file_name]... previous option can be repeated multiple times with different values. It An ellipsis outside the brackets indicates that x file_name is optional can be used inside or outside of and may be repeated as follows: x brackets. file_name1 x file_name2x file_name3 [x file_name...] An ellipsis inside the brackets indicates that x file_name is optional, and the file variable can be repeated as follows: x file_name1 file_name2 file_name3 x file_name [x file_name]... An ellipsis used with this syntax indicates that you must specify x file_name at least once.
About this guide
xxv
Conventions
xxvi
Chapter 1. Tivoli Workload Scheduler overview

IBM Tivoli Workload Scheduler provides you with the ability to manage your production environment and automate many operator activities. Tivoli Workload Scheduler manages job processing, resolves interdependencies, and launches and tracks jobs. Because jobs start as soon as their dependencies are satisfied, idle time is minimized and throughput is significantly improved. If a job fails, Tivoli Workload Scheduler manages the recovery process with little or no operator intervention. This chapter is divided into the following sections: v Understanding basic concepts v Tivoli Workload Scheduler user interfaces on page 7 v Starting production on page 8
Understanding basic concepts

This section describes the basic concepts of Tivoli Workload Scheduler and is divided into the following sections: v What is a Tivoli Workload Scheduler network v How you configure your Tivoli Workload Scheduler runtime environment on page 2 v How you define scheduling activities using Tivoli Workload Scheduler on page 2 v How you manage production scheduling activities with Tivoli Workload Scheduler on page 5
What is a Tivoli Workload Scheduler network

A Tivoli Workload Scheduler network consists of a set of linked workstations on which you perform batch job processing using Tivoli Workload Scheduler management capabilities. Workstations communicate using TCP/IP links, and a store-and-forward technology to maintain consistency and fault-tolerance across the network. This means that if a workstation is not linked, all the information is stored in the messages file and only sent when the link is reestablished. The Tivoli Workload Scheduler network consists of one or more domains, each having a domain manager workstation acting as a management hub, and one or more agent workstations. There are three types of agent: standard, fault-tolerant, and extended. Standard and fault-tolerant agents can be defined on UNIX and Windows computers. Extended agents are logical definitions, each hosted by a physical workstation, and are used to perform job processing where an agent is not installed. For example, extended agents are available for Peoplesoft, SAP R/3, z/OS, CA-7, JES, OPC, Oracle EBS, and VMS but you can also install them on UNIX and Windows systems. For information about workstations, refer to Workstation definition on page 108.
What is a Tivoli Workload Scheduler network

In the hierarchical Tivoli Workload Scheduler topology, the master domain manager is the domain manager of the topmost domain. All production setup tasks and the generation of the production plan are performed on the master domain manager. A production plan contains all job management activities to be performed across the Tivoli Workload Scheduler network during a specific time frame. A copy of the production plan is distributed from the master domain manager to the other workstations. On each workstation Tivoli Workload Scheduler launches and tracks its own jobs, and sends job processing status to the master domain manager. For more information about Tivoli Workload Scheduler plan management capabilities, refer to Chapter 5, Managing the production cycle, on page 55.
How you configure your Tivoli Workload Scheduler runtime environment

This section gives you an high level overview of how you can configure your Tivoli Workload Scheduler runtime environment.
Configuring properties
You can set two types of properties to configure your Tivoli Workload Scheduler runtime environment, properties that are set on the master domain manager and affect processing on all workstations in the Tivoli Workload Scheduler network, and properties that are set locally on a workstation and affect processing on that workstation only. The former are managed using the Tivoli Workload Scheduler command line program named optman, and the latter you define locally on the workstation by customizing the configuration files useropts, localopts, and jobmanrc. For more information on how to use the optman command line to manage global options and about local options defined in the localopts file, refer to IBM Tivoli Workload Scheduler: Planning and Installation Guide. For more information about the local options defined in the useropts file, refer to Setting up options for using the user interfaces on page 29.
Configuring security
Each time you run a Tivoli Workload Scheduler program, or invoke a Tivoli Workload Scheduler command, security information is read from a special file, the Security file, to determine your user capabilities. This file contains one or more user definitions. A user definition is a group of one or more users either who are either allowed or denied to perform specific actions against specific scheduling object types. The main Tivoli Workload Scheduler user, TWS_user, is defined at installation time in the security file. That user ID can be used to complete the setup procedure, to set properties, and to manage user definitions inside the security file. You can modify the security file at any time to meet your system requirements. For more information about managing user authorizations, refer to Security management overview on page 31.
How you define scheduling activities using Tivoli Workload Scheduler

To perform scheduling activities using Tivoli Workload Scheduler you need to first define the environment you want to manage in terms of scheduling objects and in
How you define scheduling activities

terms of rules to be applied when scheduling operations to run on these objects. This information is stored by Tivoli Workload Scheduler in a DB2 Relational Data Base, from now on called the database. In addition to the definitions of scheduling objects, such as jobs, job streams, resources, workstations, and so on, the database also contains statistics of processed jobs and job streams, as well as information about the user who created an object and when an object was last modified. You can manage the scheduling object definitions in the database either using the Tivoli Workload Scheduler command-line program named composer or using the graphical user interface, the Job Scheduling Console. You can retrieve statistics about processed jobs and job streams in the database using: v The Tivoli Workload Scheduler report utilities from the command line. v The Tivoli Job Scheduling Console. v The Tivoli Dynamic Workload Console. v The database views. Hereafter are described the most commonly used scheduling objects that you can define and some rules that you can apply to them. For more information about report utility commands, refer to Chapter 11, Getting reports and statistics, on page 413. For more information about the Job Scheduling Console and the Tivoli Dynamic Workload Console, refer to the corresponding documentation. For more information on database views, refer to IBM Tivoli Workload Scheduler: Database Views.
Jobs
A job is a unit of work specifying an action (such as a weekly data backup) to be performed on specific workstations in the Tivoli Workload Scheduler network. Jobs can be defined either independently from job streams or within a job stream definition. For more information about jobs, refer to Job definition on page 119.
Job streams and run cycles

A job streams is a sequences of jobs to be run, together with times, priorities, and other dependencies that determine the order of processing. Each job stream is assigned a time to run, represented by run cycles with type calendars, set of dates, or repetition rates. For more information, refer to Job stream definition on page 133.
Parameters
A parameter is a mapping between a name and a value, it is used as a variable in job and job stream definitions. There are two types of parameters: global or named They are defined in the database, and are replaced with the corresponding values inside the job or job stream definition when the plan is created or extended. local or unnamed They are defined on workstations using the utility parms, and are resolved locally on the workstation when the job or job stream is
How you define scheduling activities

submitted in production or at run time on the target workstation if they the job or job stream was added to the plan when the plan was created or extended. For additional information refer to Parameter definition on page 128 and to parms on page 400 utility command.
How to control job and job stream processing

You can control how jobs and job streams are processed by setting one or more rules from the following:
Defining dependencies
A dependency is a prerequisite that must be satisfied before processing can proceed. You can define dependencies for both jobs and job streams to ensure the correct order of processing. You can choose from four different types of dependencies: v On completion of jobs and job streams: a job or a job stream must not begin processing until other jobs and job streams have completed successfully. For more information, refer to follows on page 150. v Resource: a job or a job stream needs one or more resources available before it can begin to run. For more information, refer to needs on page 160. v File: a job or a job stream needs to have access to one or more files before it can begin to run. For more information, refer to opens on page 167. v Prompt: a job or a job stream needs to wait for an affirmative response to a prompt before it can begin processing. For more information, refer to Prompt definition on page 130 and prompt on page 170. You can define up to 40 dependencies for a job or job stream. In a Tivoli Workload Scheduler network, dependencies can cross workstation boundaries. For example, you can make job1, which runs on host site1, dependent on the successful completion of job2, which runs on host site2.
Setting time constrains

Time constraints can be specified for both jobs and job streams. For a specific run cycle you can specify the time that processing begins, by using the keyword at, or the time after which processing is no longer started, by using the keyword until. By specifying both, you define a time window within which a job or job stream runs. Both at and until represent time dependencies. Another time setting that can be specified is the schedtime; it indicates the time that is referred to when calculating jobs and job streams dependencies. You can also specify a repetition rate; for example, you can have Tivoli Workload Scheduler launches the same job every 30 minutes between 8:30 a.m. and 1:30 p.m. For more information, refer to at on page 138, deadline on page 142, every on page 146, schedtime on page 171, and until on page 175.
Setting job priority and workstation fence

Tivoli Workload Scheduler has its own queuing system, consisting of levels of priority. Assigning a priority to jobs and job streams gives you added control over their precedence and order of running. The job fence provides another type of control over job processing on a workstation. When it is set to a priority level, it only allows jobs and job streams whose priority exceeds the job fence to run on that workstation. Setting the fence to 40, for example, prevents jobs with priorities of 40 or less from being launched.
How to control job and job stream processing

For more information, refer to fence on page 290 and priority on page 169.
Setting limits
The limit provides a means of setting the highest number of jobs that Tivoli Workload Scheduler is allowed to launch. You can set a limit: v In the job stream definition using the job limit argument v In the workstation definition using the limit cpu command Setting the limit on a workstation to 25, for example, allows Tivoli Workload Scheduler to have no more than 25 jobs running concurrently on that workstation. For more information, refer to limit cpu on page 293, and limit sched on page 294.
Defining resources
You can define resources to represent physical or logical assets on your system. Each resource is represented by a name and a number of available units. If you have three tape units, for example, you can define a resource named tapes with three available units. A job that uses two units of the tapes resource would then prevent other jobs requiring more than the one remaining unit from being launched. However because a resource is not strictly linked to an asset, you can use a mock resource as a dependency to control job processing. For more information, refer to Resource definition on page 132.
Asking for job confirmation

There might be scenarios where the completion status of a job cannot be determined until you have performed some tasks. You might want to check the results printed in a report, for example. In this case, you can set in the job definition that the job requires confirmation, and Tivoli Workload Scheduler waits for your response before marking the job as successful or failed. For more information, refer to confirm on page 278.
Defining job recovery actions

When you schedule a job, you can specify the type of recovery you want performed by Tivoli Workload Scheduler if the job fails. The predefined recovery options are: v Continue with the next job. v Stop and do not start the next. v Run the failed job again. In addition, you can specify other actions to be taken in terms of recovery jobs and recovery prompts. For example, if a job fails, you can have Tivoli Workload Scheduler automatically run a recovery job, issue a recovery prompt that requires an affirmative response, and then run the failed job again. For more information, refer to Job definition on page 119.
How you manage production scheduling activities with Tivoli Workload Scheduler
Each time a new production plan is generated, Tivoli Workload Scheduler selects the job streams that run in the time window specified for the plan, and carries forward uncompleted job streams from the previous production plan. All the required information are written in a file, named Symphony, which is continually
How you manage production scheduling activities

updated while processing to indicate work completed, work in progress, and work to be done. The Tivoli Workload Scheduler conman (Console Manager) command-line program is used to manage the information in the Symphony file. The conman command-line program can be used to: v Start and stop Tivoli Workload Scheduler control processes. v Display the status of jobs and job streams. v Alter priorities and dependencies. v Alter the job fence and job limits. v Rerun jobs. v Cancel jobs and job streams. v Submit new jobs and job streams. v Reply to prompts. v Link and unlink workstations in the Tivoli Workload Scheduler network. v Modify the number of available resources. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
How to automate workload using event rules

Beside doing plan-based job scheduling, you can automate workload based on demand with the aid of event rules. The objective of event rules is to carry out a predefined set of actions in response to specific events affecting Tivoli Workload Scheduler and non-Tivoli Workload Scheduler objects. With respect to Tivoli Workload Scheduler objects, the product provides a plug-in that you can use to detect the following events: v A specific job or job stream: Changes status Is beyond its latest start time Is submitted Is cancelled Is restarted Becomes late v A certain workstation: Changes status Changes its link status from its parent workstation Changes its link status from its child workstation v A specific prompt is displayed or replied to v The embedded application server on a certain workstation is started or stopped When any of these events takes place, any of the following actions can be triggered: v Submit a job stream, a job, or a task v Reply to a prompt v Run non-Tivoli Workload Scheduler commands v Notify users via e-mail v Send messages to Tivoli Enterprise Console You can also define and run event rules that act either on the detection of one or more of these events or on a sequence or set of these events not completing within a specific length of time. More information is available on Chapter 6, Running event-driven workload automation, on page 89.
User interfaces
Tivoli Workload Scheduler user interfaces

A combination of graphical and command-line and API interface programs are provided to work with Tivoli Workload Scheduler. In particular, the command-line interface is available for certain advanced features which are not available in the graphical user interface. The available Tivoli Workload Scheduler user interface programs are: composer A command-line program used to define and manage scheduling objects in the database. This interface program and its use are described in Chapter 7, Defining objects in the database, on page 105 and Chapter 8, Managing objects in the database - composer, on page 189. conman A command-line program used to monitor and control the Tivoli Workload Scheduler production plan processing. This interface program is described in Chapter 9, Managing objects in the plan - conman, on page 243. | | | | | | | | | | | | | | | | | | | | | | | | | | | Java API A set of available classes and methods running in a JAVA environment that you use to create your custom interface to manage scheduling objects in the database and in the plan. This API cannot be used to create your custom interface to set global options. Documentation for the API is provided on all product CDs. Mount the CD for your platform and open the following file with your Internet browser: CD_drive/API/doc/ index.html. Click on the Help topic in the page header to learn more about how the documentation is structured. Tivoli Dynamic Workload Console A web-based user interface available for viewing and controlling scheduling activities in production on both the Tivoli Workload Scheduler distributed and z/OS environments. With the Tivoli Dynamic Workload Console you can use any supported browser to access the Tivoli Workload Scheduler environment from any location in your network. You can use the Tivoli Dynamic Workload Console to: v Browse and manage scheduling objects involved in current plan activities v Create and control connections to Tivoli Workload Scheduler environments v Submit jobs and job streams in production v Set user preferences v Create and manage event rules Tivoli Dynamic Workload Console must reside on a server that can reach the Tivoli Workload Scheduler nodes using network connections. See the Tivoli Dynamic Workload Console Installation and Troubleshooting guide for information. Job Scheduling Console An interactive graphical interface used to create, modify, and delete objects in the product database and in the plan. This interface is described in the IBM Tivoli Workload Scheduler Job Scheduling Console: Users Guide. optman A command-line program used on the master domain manager to manage the settings that affect the entire Tivoli Workload Scheduler environment.
User interfaces
These settings, also called global options, are stored in the database. This interface program is described in the Tivoli Workload Scheduler Planning and Installation Guide. planman A command-line program used to manage the Tivoli Workload Scheduler planning capability. This interface program is described in Planman command line on page 72. Web Services Interface An interface that provides you with a Web Services based access mechanism to a subset of functionality used to manage jobs and job streams in the plan. It does not allow you to manage the plan, to set global options, to manage objects in the database. For more information refer to Appendix B, Web services interface, on page 545. You must install the Tivoli Workload Scheduler Command Line Client feature on fault-tolerant agents and systems outside the Tivoli Workload Scheduler network to use the composer and optman command-line programs and to run planman showinfo and planman unlock commands. For information on how to set the options needed to allow a user to access the command-line interfaces, refer to Setting up options for using the user interfaces on page 29.
Starting production
This section provides you with a step-by-step path of basic operations you can perform quickly implement Tivoli Workload Scheduler in your environment using the command-line interface. It is assumed that: v These steps are performed on the master domain manager immediately after successfully installing the product on the systems where you want to perform your scheduling activities. v The user ID used to perform the operations is the same as the one used for installing the product. If you are not familiar with Tivoli Workload Scheduler you can follow the non-optional steps to define a limited number of scheduling objects, and add more as you become familiar with the product. You might start, for example, with two or three of your most frequent applications, defining scheduling objects to meet their requirements only. Alternatively, you can use the Job Scheduling Console or the Tivoli Dynamic Workload Console to perform the same tasks. Refer to the corresponding product documentation for more information. The first activity you must perform is to access the Tivoli Workload Scheduler database and to define the environment where you want to perform your scheduling activities using the Tivoli Workload Scheduler scheduling object types. To do this perform the following steps: 1. Set up the Tivoli Workload Scheduler environment variables Run one of the following scripts: . ./TWS_home/tws_env.sh for Bourne and Korn shells in UNIX . ./TWS_home/tws_env.csh for C shells in UNIX TWS_home\tws_env.cmd in Windows
Starting production
in a system shell to set the PATH and TWS_TISDIR variables. 2. Connect to the Tivoli Workload Scheduler database You can use the following syntax to connect to the master domain manager as TWS_user:
composer -user <TWS_user> -password <TWS_user_password>
where TWS_user is the user ID you specified at installation time. Note: If you want to perform this step and the following ones from a system other than the master domain manager you must specify the connection parameters when starting composer as described in Setting up options for using the user interfaces on page 29. 3. Optionally add in the database the definitions to describe the topology of your scheduling environment in terms of: v Domains Use this step if you want to create a hierarchical tree of the path through the environment. Using multiple domains decreases the network traffic by reducing the communications between the master domain manager and the other workstations. For additional information, refer to Domain definition on page 117. v Workstations Define a workstation for each machine belonging to your scheduling environment with the exception of the master domain manager which is automatically defined during the Tivoli Workload Scheduler installation. For additional information, refer to Workstation definition on page 108. The master domain manager is automatically defined in the database at installation time. 4. Optionally define the users allowed to run jobs on Windows workstations Define any user allowed to run jobs using Tivoli Workload Scheduler by specifying user name and password. For additional information, refer to Windows user definition on page 125. 5. Optionally define calendars Calendars allow you to determine if and when a job or a job stream has to run. You can use them to include or exclude days and times for processing. For additional information refer to Calendar definition on page 127. 6. Optionally define parameters, prompts, and resources For additional information refer to Parameter definition on page 128, Prompt definition on page 130, and Resource definition on page 132. 7. Optionally define jobs and job streams For additional information refer to Job definition on page 119, and to Job stream definition on page 133. 8. Optionally define restrictions and settings to control when jobs and job streams run. You can define dependencies for jobs and job streams. There can be up to 40 dependencies for a job stream. They can be: v Resource dependencies v File dependencies v Job and job stream follow dependencies v Prompt dependencies You can define time settings for jobs and job streams to run in terms of:
Starting production
v Run cycles v Time constraints You can tailor the way jobs run concurrently either on a workstation or within a job stream by setting: v Limit v Priority 9. Automate the plan extension at the end of the current production plan processing Add the final job stream to the database to perform automatic production plan extension at the end of each current production plan processing by running the following command:
add Sfinal
For additional information, refer to Automating production plan processing on page 87. 10. Generate the plan Run the JnextPlan command to generate the production plan. This command starts the processing of the scheduling information stored in the database and creates the production plan for the time frame specified in the JnextPlan command. The default time frame is 24 hours. If you automated the plan generation as described in the previous step, you only need to run the JnextPlan command the first time. When you complete this step-by-step process, your scheduling environment is up and running, with batch processing of an ordered sequence of jobs and job streams being performed against resources defined on a set of workstations, if defined. By default, the first time you run the JnextPlan command, the number of jobs that can run simultaneously on a workstation is zero, so make sure that you increase this value by changing the limit cpu to allow job execution on that workstation, see the section limit cpu on page 293 for more details. If you want to modify anything while the production plan is already in process, use the conman program. While the production plan is processing across the network you can still continue to define or modify jobs and job streams in the database. Consider however that these modifications will only be used if you submit the modified jobs or job streams, using the command sbj for jobs or sbs for job streams, on a workstation which has already received the plan, or after a new production plan is generated using JnextPlan. See Chapter 9, Managing objects in the plan - conman, on page 243 for more details about the conman program and the operations you can perform on the production plan in process.
10
Chapter 2. Understanding workstation processes

In a multi-tier Tivoli Workload Scheduler network, locally on each workstation a group of specialized scheduling processes performs job management and sends back the information about job processing throughout the hierarchical tree until the master domain manager is reached. The master domain manager then updates its copy of the Symphony file, containing the records describing the job processing activities to be performed across Tivoli Workload Scheduler network during the current production plan, with the information received from the workstations and sends the updates on the activities to be performed to the workstations involved. This chapter describes both the job processing performed at each workstation and the network communication established across the hierarchical tree. It is divided into the following sections: v What is new about workstation processes v Tivoli Workload Scheduler workstation processes v Starting and stopping processes on a workstation on page 16 v Workstation inter-process communication on page 17 v Tivoli Workload Scheduler network communication on page 18 | | | | | | | |
What is new about workstation processes

This section gives you a quick reference to the enhancements about workstation processes included in Tivoli Workload Scheduler version 8.4. The enhancement involves the addition of the following workstation processes: v The appserverman process is in charge of starting and stopping the embedded Websphere application server. v The monman process is in charge of running monitoring services to detect locally events defined in event rules.
Tivoli Workload Scheduler workstation processes

The management of communication between workstations and local job processing together with update state notification is performed on each Tivoli Workload Scheduler workstation by a series of management processes active while the engine is running. On fault-tolerant agents and domain managers these processes are based on a WebSphere Application Server infrastructure. This infrastructure is automatically installed with the workstation and allows Tivoli Workload Scheduler to: v Communicate across the Tivoli Workload Scheduler network. v Manage authentication mechanisms for remote clients, such as command-line programs, connecting to the master domain manager using HTTP or HTTPS protocol. For information on how to start and stop both WebSphere Application Server infrastructure and Tivoli Workload Scheduler processes on a workstation refer to Starting and stopping processes on a workstation on page 16. Out of starting and stopping of processes on a workstation and managing connection parameters when communicating across the Tivoli Workload Scheduler network, the WebSphere Application Server infrastructure is transparent when using Tivoli Workload Scheduler.
11
Workstation processes
In this guide Tivoli Workload Scheduler processes or workstation processes are used to identify the following processes: | | | | | | netman monman writer mailman batchman jobman These processes are started on a workstation, that is not a standard agent workstation, in the following order: netman Netman is the Network Management process. It is started by the Startup command and it behaves like a network listener program which receives start, stop, link, or unlink requests from the network. Netman examines each request received and spawns a local Tivoli Workload Scheduler process. | | | | | | | | | | | | | | | | | monman Monman is a process started by netman and used in event management. Starts monitoring and ssmagent services that have the task of detecting the events defined in the event rules deployed and activated on the specific workstation. When these services catch any such events, after a preliminary filtering action, they send them to the event processing server that runs usually in the master domain manager. If no event rule configurations are downloaded to the workstation, the monitoring services stay idle. The communication process between the monitoring agents and the event processing server is independent of the Tivoli Workload Scheduler network topology. It is based directly on the EIF port number of the event processor and the event information flows directly from the monitoring agents without passing through intermediate domain managers. A degree of fault-tolerance is guaranteed by local cash memories that temporarily store the event occurrences on the agents in case communication with the event processor is down. writer Writer is a process started by netman to pass incoming messages to the local mailman process. The writer processes (there might be more than one on a domain manager workstation) are started by link requests (see link on page 295) and are stopped by unlink requests (see unlink on page 370) or when the communicating mailman ends. mailman Mailman is the Mail Management process. It routes messages to either local or remote workstations. On a domain manager, additional mailman processes can be created to divide the load on mailman due to the initialization of agents and to improve the timeliness of messages. When the domain manager starts up, it creates a separate mailman process instance for each ServerID specified in the workstation definitions of the fault-tolerant agents and standard agents it manages. Each workstation is contacted by its own ServerID on the domain manager. For additional information, refer to Workstation definition on page 108. batchman Batchman is the Production Control process. It interacts directly with the
12
copy of the Symphony file distributed to the workstations at the beginning of the production period and updates it. Batchman performs several functions: v Manages locally plan processing and updating. v Resolves dependencies of jobs and job streams. v Selects jobs to be run. v Updates the plan with the job processing results Batchman is the only process that can update the Symphony file. jobman Jobman is the Job Management process. It launches jobs under the direction of batchman and reports job status back to mailman. It is responsible for tracking job state and for setting the environment as defined in scripts jobmanrc and .jobmanrc when requesting to launch jobs. For information about these scripts, see Chapter 3, Configuring the job environment, on page 21. When the jobman process receives a launch job message from batchman, it spawns a job monitor process. The maximum number of job monitor processes that can be spawned on a workstation is set using the limit cpu command from the conman command line prompt (see limit cpu on page 293). job monitor (jobman on UNIX, JOBMON.exe and joblnch.exe on Windows operating system) The job monitor process first performs a set of actions to set the environment before the job is launched, and then launches the job by running the script file or command specified in the job definition. For additional details on how to specify the script file or the command launched with the job, refer to Job definition on page 119. | | | | | | | | The setup activities consist of launching the standard configuration file (TWS_home/jobmanrc in UNIX and TWS_home/jobmanrc.cmd in Windows) which contains settings that apply to all jobs running on the workstation. In addition, on UNIX workstations a local configuration script TWS_user/.jobmanrc is launched, if it exists in the home directory of the user launching the job. This local configuration file contains settings that apply only to jobs launched by the specific user. If any of these steps fail, the job ends in the FAIL state. All processes, except jobman, run as the TWS_user. Jobman runs as root. On standard agent workstations, the batchman process is not launched because this type of workstation does not manage job scheduling. These workstations only launch jobs under the direction of their domain manager. Locally on the workstation the management processes wait for a request to launch a job from the domain manager in LISTEN mode. When the request is received the job is launched locally and the result is sent back to the domain manager. For additional information on standard agent workstations refer to IBM Tivoli Workload Scheduler: Planning and Installation Guide.
13
Figure 1 shows the processes tree on an workstation, other than a standard agent workstation, installed on a UNIX operating system:
netman
monman
batchman
writer
ssmagent
mailman
serverA (mailman)
jobman
job monitor (jobman)
jobmanrc
jobmanrc
jobmanrc
.jobmanrc
.jobmanrc
.jobmanrc
job file
Figure 1. Process tree in UNIX
job file
job file
14
Figure 2 shows the processes tree on a workstation, other than a standard agent workstation, installed on a Windows operating system:
netman.exe
monman.exe
mailman.exe
writer.exe
ssmagent.exe
batchman.exe
serverA (mailman.exe)
jobman.exe
jobmon.exe
joblnch.exe
joblnch.exe
joblnch.exe
jobmanrc.cmd
jobmanrc.cmd
jobmanrc.cmd
job file
Figure 2. Process tree in Windows
job file
job file
15
On Windows operating systems there is an additional service, the Tivoli Token Service, which enable Tivoli Workload Scheduler processes to be launched as if they were issued by the Tivoli Workload Scheduler user.
Starting and stopping processes on a workstation

How processes are started on a workstation from the Tivoli Workload Scheduler command line depends on the operating system installed. Table 3 explains how you can start and stop both the WebSphere Application Serverinfrastructure and Tivoli Workload Scheduler processes on a workstation based on the operating system installed. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 3. Starting and stopping Tivoli Workload Scheduler on a workstation Action Commands used on UNIX platform Commands used on Windows platform conman start conman startappserver conman startmon
Start all Tivoli Workload conman start Scheduler processes including conman startappserver WebSphere Application Server conman startmon and the event monitoring engine. Start netman and Websphere Application Server. On Windows starts also the Tivoli Token Service ./StartUp.sh
StartUp
Stop all Tivoli Workload conman shutdown Scheduler processes and ./stopWas.sh Websphere Application Server. Stop all Tivoli Workload Scheduler processes with the exception of Websphere Application Server. Start all Tivoli Workload Scheduler processes with the exception of Websphere Application Server and the event monitoring engine. Stop all Tivoli Workload Scheduler processes but netman. Stop all Tivoli Workload Scheduler processes (including netman). Start WebSphere Application Server Stop WebSphere Application Server Start the event monitoring engine Stop the event monitoring engine conman shutdown
conman shutdown -appsrv shutdown -appsrv conman shutdown shutdown
conman start
conman start
conman stop
conman stop
conman shutdown
conman shutdown shutdown startWas or conman startappserver stopWas or conman stopappserver conman startmon conman stopmon
./startWas.sh or conman startappserver ./stopWas.sh or conman stopappserver conman startmon conman stopmon
Refer to StartUp on page 409 for more information on the StartUp utility command.
16
Starting and stopping processes

Refer to shutdown on page 408 for more information on the shutdown utility command. Refer to IBM Tivoli Workload Manager: Planning and installation guide for more information on startWas and stopWas commands. Refer to start on page 342 for more information on the conman start command. Refer to stop on page 349 for more information on the conman stop command. Refer to shutdown on page 341 for more information on the conman shutdown command. | | | | | | | | | | | | | | Refer to startappserver on page 345 for more information on the conman startappserver command. Refer to stopappserver on page 352 for more information on the conman stopappserver command. Refer to startmon on page 347 for more information on the conman startmon command. Refer to stopmon on page 354 for more information on the conman stopmon command. If the agent is installed on a Windows system, WebSphere Application Server and the netman processes are automatically started at start time as services together with the Tivoli Token Service. If the agent is installed on a UNIX system, WebSphere Application Server and the netman processes can be automatically started at start time by adding a statement invoking Startup in the /etc/inittab file.
Workstation inter-process communication

Tivoli Workload Scheduler uses message queues for local inter-process communication. There are four message files, which reside in the TWS_home directory: NetReq.msg This message file is read by the netman process for local commands. It receives messages such as START, STOP, LINK, and UNLINK. Mailbox.msg This message file is read by the mailman process. It receives messages from the local batchman and jobman processes, from both the Job Scheduling Console and the console manager conman, and from other Tivoli Workload Scheduler workstations in the network. Intercom.msg This message file is read by the batchman process and contains instructions sent by the local mailman process. Courier.msg This message file is written by the batchman process and read by the jobman process.
17
Workstation inter-process communication
Operator input
conman stop, start or shutdown
NetReq.msg
netman writer
netman spawns writer for each incoming connection From remote mailman To remote mailman
JSC or conman
Mailbox.msg
mailman
Intercom.msg
batchman
Courier.msg
jobman
Figure 3. Inter-process communication
These files have a default maximum size of 10MB. The maximum size can be changed using the evtsize utility (see evtsize on page 388).
Tivoli Workload Scheduler network communication

Tivoli Workload Scheduler uses the TCP/IP protocol for network communications. The node name and the port number used to establish the TCP/IP connection are set for each workstation in its workstation definition, refer to Workstation definition on page 108 for additional details. A store-and-forward technology is used by Tivoli Workload Scheduler to maintain consistency and fault tolerance across the network at all times by queuing messages in message files while the connection is not active. When the TCP/IP communication is established between systems, Tivoli Workload Scheduler provides bi-directional communications between workstations using links. Links are controlled by the autolink flag set in the Workstation definition on page 108, and by the link on page 295 and unlink on page 370 commands issued from the conman command-line program. When a link is opened, messages are passed between two workstations. When a link is closed, the sending workstation stores messages in a local message file and sends them to the destination workstation as soon as the link is re-opened. There are basically two types of communication that take place in the Tivoli Workload Scheduler environment, connection initialization and scheduling event
18
Network communication
delivery in the form of change of state messages during the processing period. These two types of communication are now explained in detail. Connection initialization and two-ways communication setup These are the steps involved in the establishment of a two-ways Tivoli Workload Scheduler link between a domain manager and a remote FTA: 1. On the domain managers the mailman process reads the host name, TCP/IP address, and port number of the FTA from the Symphony file. 2. The mailman process on the domain manager establishes a TCP/IP connection to the netman process on the FTA using the information obtained from the Symphony file. 3. The netman process on the FTA determines that the request is coming from the mailman process on the domain manager, and spawns a new writer process to handle incoming connection. 4. The mailman process on the domain manager is now connected to the writer process on the FTA. The writer process on the FTA communicates the current run number of its copy of the Symphony file to the mailman process on the domain manager. This run number is the identifier used by Tivoli Workload Scheduler to recognize each Symphony file generated by JnextPlan. This step is necessary for the domain manager to check if the current plan has already been sent to the FTA. 5. The mailman process on the domain manager compares its Symphony file run number with the run number of the Symphony file on the FTA. If the run numbers are different, the mailman process on the domain manager sends to the writer process on the FTA the latest copy of the Symphony file. 6. When the current Symphony file is in place on the FTA, the mailman process on the domain manager sends a start command to the FTA. 7. The netman process on the FTA starts the local mailman process. At this point a one-way communication link is established from the domain manager to the FTA. 8. The mailman process on the FTA reads the host name, TCP/IP address, and port number of the domain manager from the Symphony file and use them to establish the uplink back to the netman process on the domain manager. 9. The netman process on the domain manager determines that the request is coming from the mailman process on the FTA, and spawns a new writer process to handle the incoming connection. The mailman process on the FTA is now connected to the writer on the domain manager and a full two-way communication link has been established. As a result of this, the writer process on the domain manager writes messages received from the FTA to the Mailbox.msg file on the domain manager, and the writer process on the FTA writes messages from the domain manager to the Mailbox.msg file on the FTA. Job processing and scheduling event delivery in the form of change of state messages during the processing day performed locally by the FTA During the production period, the Symphony file present on the FTA is read and updated with the state change information about jobs that are run locally by the Tivoli Workload Scheduler workstation processes. These are the steps that are performed locally on the FTA to read and update the Symphony file and to process jobs:
19
Network communication
1. The batchman process reads a record in the Symphony file that says that job1 is to be launched on the workstation. 2. The batchman process writes in the Courier.msg file that job1 has to start. 3. The jobman process reads this information in the Courier.msg file, starts job1, and writes in the Mailbox.msg file that job1 started with its process_id and timestamp. 4. The mailman process reads this information in its Mailbox.msg file, and sends a message that job1 started with its process_id and timestamp, to both the Mailbox.msg file on the domain manager and the local Intercom.msg file on the FTA. 5. The batchman process on the FTA reads the message in the Intercom.msg file and updates the local copy of the Symphony file. 6. When job job1 completes processing, the jobman process updates the Mailbox.msg file with the information that says that job1 completed. 7. The mailman process reads the information in the Mailbox.msg file, and sends a message that job1 completed to both the Mailbox.msg file on the domain manager and the local Intercom.msg file on the FTA. 8. The batchman process on the FTA reads the message in the Intercom.msg file, updates the local copy of the Symphony file, and determines the next job that has to be run. For information on how to tune job processing on a workstation, refer to the IBM Tivoli Workload Scheduler: Administration and Troubleshooting Guide. | | | | | | | | | | | | | | | | |
Support for Internet Protocol version 6

Tivoli Workload Scheduler supports Internet Protocol version 6 (IPv6) in addition to the legacy IPv4. To assist customers in staging the transition from an IPv4 environment to a complete IPv6 environment, Tivoli Workload Scheduler provides IP dual-stack support. In other terms, the product is designed to communicate using both IPv4 and IPv6 addresses simultaneously with other applications using IPv4 or IPv6. To this end, the gethostbyname and the gethostbyaddr functions were dropped from Tivoli Workload Scheduler as they exclusively support IPv4. They are replaced by the new getaddrinfo API that makes the client-server mechanism entirely protocol independent. The getaddrinfo function handles both name-to-address and service-to-port translation, and returns sockaddr structures instead of a list of addresses These sockaddr structures can then be used by the socket functions directly. In this way, getaddrinfo hides all the protocol dependencies in the library function, which is where they belong. The application deals only with the socket address structures that are filled in by getaddrinfo.
20
Chapter 3. Configuring the job environment

This chapter describes how to customize the way job management is performed on a workstation. This customization is made by assigning locally on each workstation values to variables that have an impact on jobman processing. This chapter is divided into the following sections: v Job environment overview v Environment variables exported by jobman on page 22 v Customizing jobs processing on the workstation - jobmanrc on page 25 v Customizing job processing for a user on UNIX workstations - .jobmanrc on page 27
Job environment overview

On each workstation, jobs are launched by the production control process batchman. The batchman process resolves all job dependencies to ensure the correct order of job processing, and then queues a job launch message to the jobman process. Each of the processes launched by jobman, including the configuration scripts and the jobs, retain the user name recorded with the logon of the job. In case of submitted jobs, they retain the submitting users name. The jobman process starts a job monitor process that begins by setting a group of environment variables, and then runs a standard configuration script named TWS_home/jobmanrc which can be customized. The jobmanrc script sets variable that are used to configure locally on the workstation the way jobs are launched, regardless of the user. On UNIX workstations, if the user is allowed to use a local configuration script, and the script USER_HOME/.jobmanrc exists, the local configuration script .jobmanrc is also run. The job is then run either by the standard configuration script, or by the local one. The results of job processing are reported to jobman which, in turn, updates the Mailbox.msg file with the information on job completion status. To have jobs run with the users environment, add the following instruction in the local configuration script:
. $USER_home/.profile
Note: Before adding the .profile in the .jobmanrc file make sure that it does not contain any stty setting or any step that requires an user manual intervention. In case it does, add in the .jobmanrc file only the necessary steps contained in the .profile.
21
Environment variables exported by jobman

The variables listed in Table 4 are set locally on the workstation and exported by jobman on Windows operating systems:
Table 4. Job environment variables for Windows Variable Name COMPUTERNAME HOMEDRIVE HOMEPATH LANG LOGNAME MAESTRO_OUTPUT_STYLE SystemDrive SystemRoot TEMP TIVOLI_JOB_DATE TMPTEMP TMPDIR Value The value of the COMPUTERNAME set in the user environment. The value of the HOMEDRIVE set in the user environment. The value of the HOMEPATH set in the user environment. The value of the LANG set in the user environment. If not set, its value is set to C. The login users name. The setting for output style for long object names. The value of the SYSTEMDRIVE set in the user environment. The value of the SYSTEMROOT set in the user environment. The value of the TEMP set in the user environment. If not specified, its value is set to c:\temp. The scheduled date for a job. The value of the TMP set in the user environment. If not specified, its value is set to c:\temp. The value of the TMPDIR set in the user environment. If not specified, its value is set to c:\temp. The time zone, if it was set in the operating system environment. The name of this workstation. The value of the UNISON_DIR set in the user environment. The jobmanrc fully qualified path. The value of the UNISONHOME set in the user environment. If not specified, its value is set to the home directory of the user running the job. The name of the host CPU. The absolute job identifier: worktation#sched_id.job. The job number (parent process identifier, ppid). The name of the master workstation. The Tivoli Workload Scheduler current production run number. The job stream name. The Tivoli Workload Schedulers production date (yymmdd) reported in the header of the Symphony file.
TZ UNISON_CPU UNISON_DIR UNISON_EXEC_PATH UNISONHOME
UNISON_HOST
| |
UNISON_JOB UNISON_JOBNUM UNISON_MASTER UNISON_RUN UNISON_SCHED UNISON_SCHED_DATE
22

Table 4. Job environment variables for Windows (continued) Variable Name UNISON_SCHED_ID UNISON_SCHED_IA UNISON_SCHED_EPOCH UNISON_SHELL UNISON_STDLIST UNISON_SYM USERDOMAIN USERNAME USERPROFILE Value The jobstreamID of the job stream containing the job in process. The StartTime of the job stream containing the job in process. The Tivoli Workload Schedulers production date expressed in epoch form. The login shell of the user running the job. The path name of the standard list file of the job. The Symphony record number of the launched job. The value of the USERDOMAIN set in the user environment. The value of the USERNAME set in the user environment. The value of the USERPROFILE set in the user environment.
The variables listed in Table 5 are set locally on the workstation and exported by jobman on UNIX operating systems:
Table 5. Job environment variables for UNIX Variable Name HOME LANG LD_LIBRARY_PATH LD_RUN_PATH LOGNAME MAESTRO_OUTPUT_STYLE PATH TIVOLI_JOB_DATE TWS_TISDIR TZ UNISON_CPU UNISON_DIR UNISON_EXEC_PATH UNISONHOME Value The home directory of the user. The value of the LANG set in the user environment. The value of the LD_LIBRARY_PATH set in the user environment. The value of the LD_RUN_PATH set in the user environment. The login user name. The setting for output style for long object names. /bin:/usr/bin The scheduled date for a job. The value of the TWS_TISDIR set in the user environment. The time zone set. The name of this workstation. The value of the UNISON_DIR set in the user environment. The .jobmanrc fully qualified path. The value of the UNISONHOME set in the user environment. If not specified, its value is set to the home directory of the user. The name of the master workstation.
UNISON_HOST
23

Table 5. Job environment variables for UNIX (continued) Variable Name Value The absolute job identifier: worktation#sched_id.job. The job number (parent process identifier, ppid). The name of the master workstation. The Tivoli Workload Schedulers current production run number. The job stream name. The Tivoli Workload Schedulers production date (yymmdd). The Tivoli Workload Schedulers production date, expressed in epoch form. The login shell of the user. The path name of the standard list file of the job. The Symphony record number.
| |
UNISON_JOB UNISON_JOBNUM UNISON_MASTER UNISON_RUN UNISON_SCHED UNISON_SCHED_DATE UNISON_SCHED_EPOCH UNISON_SHELL UNISON_STDLIST UNISON_SYM
Customizing date formatting in the stdlist

You can use an environment variable named UNISON_DATE_FORMAT to specify the date format that is used for the date in the header and in the footer of the stdlist file. This variable can be set on both UNIX and Windows workstations and must be set before starting Tivoli Workload Scheduler processes on that workstation to become effective. To set this variable follow these steps: On UNIX workstations 1. Add the statement to export the UNISON_DATE_FORMAT variable in the root .profile file. 2. Run the .profile file. 3. Run conman shutdown and then StartUp.sh. On Windows workstations 1. From the System Properties set the UNISON_DATE_FORMAT in the System Variable. 2. Run conman shutdown and then StartUp. These are some examples of the settings used to display the year format in the date field in the header and footer of the stdlist file. The setting:
UNISON_DATE_FORMAT = "%a %x %X %Z %Y"
produces an output with the following format:

Fri 15/10/04 11:05:24 AM GMT 2004
The setting:
UNISON_DATE_FORMAT = "%a %x %X %Z"
produces an output with the following format:

Fri 15/10/04 11:05:24 AM GMT
24
Customizing date formatting in the stdlist

Set this variable locally on every workstation for which you want to display the 4-digit year format. If omitted, the standard 2-digit format is used. You can refer to the following link:
http://linux.com.hk/PenguinWeb/manpage.jsp?name=strftime=3
to see the available settings that can be assigned to the UNISON_DATE_FORMAT variable.
Customizing jobs processing on the workstation - jobmanrc

A standard configuration script template named TWS_home/config/jobmanrc is supplied with Tivoli Workload Scheduler. It is installed automatically as TWS_home/jobmanrc. This script can be used by the system administrator to set the desired environment before each job is run. To alter the script, make your modifications in the working copy (TWS_home/jobmanrc), leaving the template file unchanged. The file contains variables which can be configured, and comments to help you understand the methodology. Table 6 describes the jobmanrc variables.
Table 6. Variables defined by default in the jobmanrc file Variable Name UNISON_JCL UNISON_STDLIST UNISON_EXIT Value The path name of the jobs script file. The path name of the jobs standard list file. yes | no If set to yes, the job ends immediately if any command returns a nonzero exit code. If set to no, the job continues to run if a command returns a nonzero exit code. Any other setting is interpreted as no. LOCAL_RC_OK yes | no If set to yes, the users local configuration script is run (if it exists), passing $UNISON_JCL as the first argument. The user might be allowed or denied this option. See Customizing job processing for a user on UNIX workstations - .jobmanrc on page 27 for more information. If set to no, the presence of a local configuration script is ignored, and $UNISON_JCL is run. Any other setting is interpreted as no.
25
jobmanrc
Table 6. Variables defined by default in the jobmanrc file (continued) Variable Name MAIL_ON_ABEND Value yes | no For UNIX operating systems: If set to yes, a message is mailed to the login users mailbox if the job ends with a non zero exit code. This can also be set to one or more user names, separated by spaces so that a message is mailed to each user. For example, root mis sam mary. If set to no, no messages are mailed if the job abends. Abend messages have the following format: cpu#sched.job jcl-file failed with exit-code Please review standard-list-filename You can change the wording of the message or translate the message into a another language. For an explanation of how to do this, see Customizing the MAIL_ON_ABEND section of jobmanrc. SHELL_TYPE standard | user | script If set to standard, the first line of the JCL file is read to determine which shell to use to run the job. If the first line does not start with #!, then /bin/sh is used to run the local configuration script or $UNISON_JCL. Commands are echoed to the jobs standard list file. If set to user, the local configuration script or $UNISON_JCL is run by the users login shell ($UNISON_SHELL). Commands are echoed to the jobs standard list file. If set to script, the local configuration script or $UNISON_JCL is run directly, and commands are not echoed unless the local configuration script or $UNISON_JCL contains a set -x command. Any other setting is interpreted as standard. USE_EXEC yes | no If set to yes, the job, or the users local configuration script is run using the exec command, thus eliminating an extra process. This option is overridden if MAIL_ON_ABEND is also set to yes. Any other setting is interpreted as no, in which case the job or local configuration script is run by another shell process.
Customizing the MAIL_ON_ABEND section of jobmanrc

You can modify the wording used in the message sent to the users specified in the MAIL_ON_ABEND field of the TWS_home/jobmanrc configuration file by accessing that file and changing the wording in the parts highlighted in bold:
26
Customizing the MAIL_ON_ABEND

# Mail a message to user or to root if the job fails. if [ "$MAIL_ON_ABEND" = "YES" ] then if [ $UNISON_RETURN -ne 0 ] then mail $LOGNAME <<-! $UNISON_JOB \$UNISON_JCL\ failed with $UNISON_RETURN Please review $UNISON_STDLIST ! fi elif [ "$MAIL_ON_ABEND" = "ROOT" ] then if [ $UNISON_RETURN -ne 0 ] then mail root <<-! $UNISON_JOB \$UNISON_JCL\ failed with $UNISON_RETURN Please review $UNISON_STDLIST ! fi elif [ "$MAIL_ON_ABEND" != "NO" ] then if [ $UNISON_RETURN -ne 0 ] then mail $MAIL_ON_ABEND <<-! $UNISON_JOB \$UNISON_JCL\ failed with $UNISON_RETURN Please review $UNISON_STDLIST ! fi fi
Customizing job processing for a user on UNIX workstations .jobmanrc

On UNIX workstations, the local configuration script .jobmanrc permits users to establish a desired environment when processing their own jobs. Unlike the jobmanrc script, the .jobmanrc script can be customized to perform different actions for different users. Each user defined as tws_user can customize in the home directory the .jobmanrc script to perform pre- and post-processing actions. The .jobmanrc script is an extra step that occurs before the job is actually launched. The .jobmanrc script runs only under the following conditions: v The standard configuration script, jobmanrc, is installed, and the environment variable LOCAL_RC_OK is set to yes (see Table 6). v If the file TWS_home/localrc.allow exists, the users name must appear in the file. If the TWS_home/localrc.allow file does not exist, the users name must not appear in the file, TWS_home/localrc.deny. If neither of these files exists, the user is permitted to use a local configuration script. v The local configuration script is installed in the users home directory (USER_home/.jobmanrc), and it has execute permission. Jobs are not automatically run, the command or script must be launched from inside the .jobmanrc. Depending on the type of process activity you want to perform, the command or script is launched differently. Follow these general rules when launching scripts from inside .jobmanrc: v Use eval if you want to launch a command.
27
.jobmanrc
v Use either eval or exec if you want to launch a script that does not need post processing activities. v Use eval if you want to launch a script that requires post processing activities. If you intend to use a local configuration script, it must, at a minimum, run the jobs script file ($UNISON_JCL). Tivoli Workload Scheduler provides you with a standard configuration script, jobmanrc, which runs your local configuration script as follows:
$EXECIT $USE_SHELL $USER_home/.jobmanrc "$UNISON_JCL" $IS_COMMAND
where: v The value of USE_SHELL is set to the value of the jobmanrc SHELL_TYPE variable (see Table 6 on page 25). v IS_COMMAND is set to yes if the job was scheduled or submitted in production using submit docommand. v EXECIT is set to exec if the variable USE_EXEC is set to yes (see Table 6 on page 25), otherwise it is null. All the variables exported into jobmanrc are available in the .jobmanrc shell, however, variables that are defined, but not exported, are not available. The following example shows how to run a jobs script file, or command, in your local configuration script:
#!/bin/ksh PATH=TWS_home:TWS_home/bin:$PATH export PATH /bin/sh -c "$UNISON_JCL"
The following is an example of a .jobmanrc that does processing based on the exit code of the users job:
#!/bin/sh # PATH=TWS_home:TWS_home/bin:$PATH export PATH /bin/sh -c "$UNISON_JCL" #or use eval "$UNISON_JCL" and the quotes are required RETVAL=$? if [ $RETVAL -eq 1 ] then echo "Exit code 1 - Non Fatal Error" exit 0 elif [ $RETVAL -gt 1 -a $RETVAL -lt 100 ] then conman "tellop This is a database error - page the dba" elif [ $RETVAL -ge 100 ] then conman "tellop Job aborted. Please page the admin" fi
28
Chapter 4. Setting up command-line authentication and user authorizations

This chapter describes how to set up the options required to allow users to work with the product user interfaces (the command-line programs, the Job Scheduling Console, and the Tivoli Dynamic Workload Console) and how to manage the authorizations to access scheduling objects assigned to Tivoli Workload Scheduler users. The chapter is divided into the following sections: v What is new in configuring user access v Setting up options for using the user interfaces v Security management overview on page 31 v Updating the security file on page 33 v Configuring the security file on page 36 v Sample security file on page 51
What is new in configuring user access

This Tivoli Workload Scheduler version features the security settings necessary to: v Regulate the access and use of the new event rule objects, which are: actions events eventrules v Start and stop the WebSphere Application Server, the event processing server, and monman. v Switch the event processing server. v Force update of the monitoring configuration file for the event monitoring engine. v Display reports on the Tivoli Dynamic Workload Console. Note that complete authorization to event rule objects and to display reports on the Tivoli Dynamic Workload Console is already defined for TWSuser in the default security file upon installation of version 8.4. If you migrate from previous versions, however, you must edit the file to grant TWSuser these permissions.
Setting up options for using the user interfaces

To use the Tivoli Workload Scheduler user interfaces (the command-line programs, the Job Scheduling Console, and the Tivoli Dynamic Workload Console), and run the logman command and the JnextPlan script, you need to provide the following setup information to connect to the master domain manager via HTTP/HTTPS using the WebSphere Application Server infrastructure: v The hostname of the master domain manager. v The port number used when establishing the connection with the master domain manager. v The credentials, username and password, of the TWS_user. v The proxy hostname used in the connection with the HTTP protocol. v The proxy port number used in the connection with the HTTP protocol.
29

v The protocol used during the communication. This can be HTTP with basic authentication, or HTTPS with certificate authentication. v The timeout indicating the maximum time the connecting user interface program can wait for the master domain manager response before considering the communication request as failed. All this information, except username and password, is stored in the TWS_home/localopts properties file. For information about this configuration file, refer to IBM Tivoli Workload Scheduler: Planning and installation guide. The file containing the user credential is the useropts file. This file is first read when the user connects to a Tivoli Workload Scheduler command-line program. In addition to the username and password this file can also contain other settings which, if defined, overwrite those set in the localopts file. If the username and password are not specified in this file then they must be specified when invoking the command-line program. | | | | Note: On Windows workstations, when you specify a password that contains double quotation marks (") or other special characters, make sure that the character is escaped. For example, if your password is tws11"tws, write it as "tws11\"tws" in useropts. This is the sample content of a useropts file:
# # Tivoli Workload Scheduler useropts file defines attributes of this Workstation. # #---------------------------------------------------------------------------# Attributes for CLI connections USERNAME = MDMDBE4 # Username used in the connection PASSWORD = "ENCRYPT:YEE7cEZs+HE+mEHCsdNOfg==" # Password used in the connection #HOST = # Master hostname used when attempting a connection. PROTOCOL = https # Protocol used to establish a connection with the Master. #PROTOCOL = http # Protocol used to establish a connection with the Master. PORT = 3111 # Protocol port #PROXY = #PROXYPORT = TIMEOUT = 120 # Timeout in seconds to wait a server response #DEFAULTWS =
The # symbol is used to comment a line. The user specified in the username field is defined in the security file on the master domain manager. The ENCRYPT label in the password field indicates that the specified setting has been encrypted; if this label does not appear, you must exit and access the interface program again to allow the encryption of that field. Because Tivoli Workload Scheduler supports multiple product instances installed on the same machine, there can be more than one useropts file instances. The possibility to have more useropts files, having a different name each, provides the ability to specify different sets of connection settings for users defined on more than one instance of the product installed on the same machine. In the localopts file of each instance of the installed product the option named useropts identifies the file name of the useropts file that has to be accessed in the user_home/.TWS directory to connect to that installation instance. This means that, if two Tivoli Workload Scheduler instances are installed on a machine and a system user named operator is defined as user in both instances, then in the localopts file of the first instance the local option useropts =
30

useropts1 identifies the operator_home/.TWS/useropts1 file containing the connection parameters settings that user operator needs to use to connect to that Tivoli Workload Scheduler instance. On the other hand, in the localopts file of the second Tivoli Workload Scheduler instance the local option useropts = useropts2 identifies the operator_home/.TWS/useropts2 file containing the connection parameters settings that user operator needs to use to connect to that Tivoli Workload Scheduler instance. The set of values described in this section is named connection_parameteres. The connection_parameteres are used when invoking either a command-line program, such as composer, optman, or planman, or when using the logman command or the JnextPlan scripts. If any of these parameters is omitted when invoking a command, Tivoli Workload Scheduler searches for the value first in the useropts file and then in the localopts file. If a parameter is not specified either in the connection parameters when invoking the command or inside the useropts and localopts files, an error is displayed.
Security management overview

The way Tivoli Workload Scheduler manages security is controlled by a configuration file named security file. A template file named TWS_home/config/Security.conf is provided with the product. During installation, a copy of the template file is installed as TWS_home/Security.conf, and a compiled, operational copy is installed as TWS_home/Security. Immediately after installing Tivoli Workload Scheduler on a workstation, the user who installed the product, TWS_user, and the system administrator (root on UNIX or Administrator on Windows) are the only users defined and allowed to connect to the user interfaces and to perform all operations on all scheduling resources. The system administrator has unrestricted access to all scheduling resources even if the security file does not exist on that workstation. On UNIX-based workstations you can limit the access to scheduling objects allowed to the root user by creating a security file with a user definition for the root user. Within the Tivoli Workload Scheduler network, using the security file you can make a distinction between local root users and the root user on the master domain manager by allowing local root users to perform operations affecting only their login workstations and providing the master root user the authorizations to perform operations affecting any workstation across the network. As you continue to work with the product you might want to add more users with different roles and authorization to perform specific operations on a defined set of objects. For example, in the security file you might add a user definition named operators that includes users oper1 and oper2, who are authorized to display and list job streams whose names begin with N* only from the master domain manager. | | | |
Do not edit the original TWS_home/config/Security.conf template, but follow the steps described in Updating the security file on page 33 to make your modifications on the operational copy of the file.
31
Security management overview

| | The security file controls activities such as: v Linking workstations. v Accessing command-line interface programs, the Job Scheduling Console, and the Tivoli Dynamic Workload Console. v Performing operations on scheduling objects in the database or in the plan. Each time a user runs Tivoli Workload Scheduler programs, commands, and user interfaces, the product compares the name of the user with the user definitions in the security file to determine if the user has permission to perform those activities on the specified scheduling objects. By default, the security on scheduling objects is managed locally on each workstation. This means that the system administrator or the TWS_user who installed the product on that system can decide which Tivoli Workload Scheduler users defined on the system can access which scheduling resources in the Tivoli Workload Scheduler network and how. As an option, the master domain manager can centralize control of how objects are managed on each workstation. This can be configured with the enCentSec global option. By default the value assigned to the enCentSec option is NO. You can modify the value assigned to this property, to manage how security is handled in your environment, using the optman command line program on the master domain manager. For information on how to manage the global properties using optman, refer to IBM Tivoli Workload Manager: Planning and Installation Guide.
Centralized security management

A Tivoli Workload Scheduler environment where centralized security management is enabled is an environment where all workstations share the same security file information contained in the security file stored on the master domain manager and the Tivoli Workload Scheduler administrator on the master domain manager is the only one who can add, modify, and delete entries in the security file valid for the entire Tivoli Workload Scheduler environment. To set central security management, the Tivoli Workload Scheduler administrator must run the following steps on the master domain manager: 1. Use the optman command line program, to set the value assigned to the enCentSec global property to YES. 2. Update the information in the security file using the dumpsec command. For information refer to dumpsec on page 34. 3. Compile the security file using the makesec command. For information refer to makesec on page 35. 4. Distribute the compiled security file to all the workstations in the environment and store it in the TWS_home directory. 5. Run JnextPlan to update the security information distributed with the Symphony file. When the JnextPlan command is run, the value of the checksum of the newly compiled security file is encrypted and loaded into the Symphony file and distributed to all the workstations in the Tivoli Workload Scheduler network. On each workstation, when a link is established or when a user connects to a user interface or attempts to issue commands on the plan, either with conman or the
32
Centralized security
Job Scheduling Console, Tivoli Workload Scheduler compares the value of the checksum in the security file delivered with the Symphony file with the value of the checksum of the security file stored on the workstation. If the values are equal, the operation is allowed. If the values are different, the operation fails and a security violation message is issued.
After you modify the master domain manager security file, copy it on the backup master domain manager as soon as possible.
In a network with centralized security management, two workstations are unable to establish a connection if one of them has enCentSec turned off in its Symphony file or if their security file information does not match. The only exception to the security file matching criteria introduced by the centralized security management mechanism is that a workstation must always accept incoming connections from its domain manager, regardless of the result of the security file matching process. Centralized security does not apply to Tivoli Workload Scheduler operations for which the Symphony file is not required. Commands that do not require the Symphony file to run, use the local security file. For example, the parms command, used to modify or display the local parameters database, continues to work according to the local security file, even if centralized security is active and the local security file differs from the centralized security rules. If a workstations security file is deleted and recreated, the checksum of the new security file will not match the value in the Symphony file. In addition, a run-number mechanism associated with the creation process of the Symphony file ensures prevention from tampering with the file.
Updating the security file

Every workstation in a Tivoli Workload Scheduler network (domain managers, fault-tolerant agents, and standard agents) has its own security file. You can maintain a file on each workstation, or, if you enabled centralized security management, you can create a security file on the master domain manager and copy it to each domain manager, fault-tolerant agent, and standard agent. Ensure that all Tivoli Workload Scheduler users are assigned the required authorization in the security file. The activation of the new security definitions does not require that you stop and restart either the Tivoli Workload Scheduler processes or the WebSphere Application Server infrastructure. For information about Tivoli Workload Scheduler processes refer to Tivoli Workload Scheduler workstation processes on page 11. To modify the security file, perform the following steps: 1. Run the dumpsec command to download the security file. See dumpsec on page 34. 2. Modify the contents of the dumped security file using the syntax described in Configuring the security file on page 36. 3. Close any open conman user interfaces using the exit command. 4. Run makesec to upload the security file and apply the modifications. See makesec on page 35. The next two sections contain the command reference information for the dumpsec and makesec commands.
33
dumpsec
dumpsec
Writes in textual mode the information contained in the compiled security file and sends the output to a specific file. This file can be edited and then used as input for the makesec command which compiles and activates the modified security settings. The user must have display access to the security file and write permission in the directory where the command is being run.
Syntax
dumpsec -v | -u dumpsec security-file
Comments
If no arguments are specified, the operational security file is dumped. To create an editable copy of a security file, redirect the output of the command to another file, as shown in the examples below.
Arguments
-v -u Displays command version information only. Displays command usage information only.
security-file Specifies the name of the security file to dump.
Examples
The following command dumps the operational security file (TWS_home/Security) to a file named mysec:
dumpsec > mysec
The following command dumps a security file named sectemp to stdout:

dumpsec sectemp
34
makesec
makesec
Compiles security definitions and installs the security file. Changes to the security file are recognized as soon as conman is stopped and restarted. To use the makesec command, you must have modify access to the security file. Note: The makesec command does not run successfully on Windows operating systems until the connectors are stopped.
Syntax
makesec -v | -u makesec [-verify] in-file
Comments
The makesec command compiles the specified file and installs it as the operational security file (../TWS_home/Security). If the -verify argument is specified, the file is checked for correct syntax, but it is not compiled and installed.
Arguments
-v -u -verify in-file Displays command version information only. Displays command usage information only. Only checks the syntax of the user definitions in in-file. The file is not compiled and installed as the security file. Specifies the name of a file or set of files containing user definitions. Syntax checking is performed automatically when the security file is installed.
Examples
The following example shows how to modify the security file definitions: 1. An editable copy of the operational security file is created in a file named tempsec with the dumpsec command:
dumpsec > tempsec
2.
The user definitions are modified with a text editor:

edit tempsec
3. The file is then compiled and installed with the makesec command:
makesec tempsec
The following command compiles user definitions from the fileset userdef* and replaces the operational security file:
makesec userdef*
35
Configuring the security file

In the security file you can specify which scheduling objects a user can manage and how. You define these settings by writing user definitions. A user definition is an association between a name and a set of users, the objects they can access, and the actions they can perform on the specified objects. The syntax described in this section is used to represent a user definition in the security file. Syntax: [# comment] user def-name user-attributes begin [* comment] object-type [object-attributes] access[=action[,...]] [object-type ... ] [end] Description: Each user definition can be divided into the following three parts: 1. The user's specifications (def-name and user-attributes) 2. A list of the objects on which the user has rights (object-type and object-attributes) 3. The type of access the user has on these objects (action) Each of these parts is described in this section. Arguments: [# | *] comment All text following a pound sign or an asterisk and at least one space is treated as a comment. Comments are not copied into the operational security file installed by the makesec command. user def-name Specifies the name of the user definition. The name can contain up to 36 alphanumeric characters and must start with an alphabetic character. user-attributes Contains one or more attributes that identify the users to whom the definition applies. For more information, refer to Specifying users on page 38. begin ... [end] Delimit the part containing object statements and accesses within the user definition. object-type Specifies the type of object the user is allowed to access. The object types are the following: | action calendars cpu Actions defined in scheduling event rules User calendars Workstations, domains and workstation classes
36

| | event eventrule file job parameter prompt | | | | | | | | | | | | | | | | | resource schedule userobj report Event conditions in scheduling event rules Scheduling event rule definitions Tivoli Workload Scheduler database file Scheduled jobs and job definitions User parameters Global prompts The following reports on the Tivoli Dynamic Workload Console: RUNHIST Job Run History RUNSTATS Job Run Statistics WWS Workstation Workload Summary WWR Workstation Workload Runtimes SQL Custom SQL
ACTPROD Actual production details (for current and archived plans) PLAPROD Planned production details (for trial and forecast plans) Permission to use these reports is granted by default to the tws_user on fresh Version 8.4 installations. Scheduling resources Job streams User objects
You can include multiple object types in a user definition. Omitting an object type prevents access to all objects of that type. | | | | | | object-attributes Specifies one or more attributes that identify, among all objects of the same type, the objects to which the definition applies. These objects are ordered by object type. If no attributes are specified, the actions defined with the access keyword for the user apply to all the objects of that type defined in the domain. For more information, refer to Specifying objects on page 40. access[=action[,...]] Describes the list of access capabilities to the specified objects given to the selected users. If none is specified then no access is given. If access=@ then all access capabilities are assigned to the specified users. For more information, refer to Specifying access on page 43. Wildcard characters: The following wildcard characters are permitted in user definition syntax: ? Replaces one alphanumeric character.
37

@ Replaces zero or more alphanumeric characters.
For information about variables supplied with the product that can be used in object attributes, refer to Specifying objects on page 40. Refer to Sample security file on page 51 for an example on how to use variables. When defining user authorization consider that: v When commands are issued from the composer command line program, the user authorizations are checked in the security file of the master domain manager since the methods used to manage the entries in the database are invoked on the master domain manager. Therefore the user must be defined: As system user on the machine where the master domain manager is installed. In security file on the master domain manager with the authorizations needed to run the allowed commands on the specific objects. v When commands are issued from the conman command line program, the user must be authorized to run the specific commands in the security file both on the connecting workstation and on the master domain manager where the command actually runs.
Specifying users
Specify user attributes as follows: user-attribute[{+ | ~}user-attribute[...]] Use a plus sign (+) to add an attribute the user or users must have. Use a tilde (~) to add an attribute the user or users must not have. A user-attribute is defined as: cpu=workstation|@ [,...] where: workstation Specifies the workstation on which the user is logged in. Wildcard characters are permitted. The following Tivoli Workload Scheduler variables can be used: $master $remotes $slaves $thiscpu Means that the user is logged in on the Tivoli Workload Scheduler master domain manager. Means that the user is logged in on any Tivoli Workload Scheduler standard agent. Means that the user is logged in on any Tivoli Workload Scheduler fault-tolerant agent. Means that the user is logged in on the Tivoli Workload Scheduler workstation on which the security check is running. Specifies that the user is accessing Tivoli Workload Scheduler with the Job Scheduling Console or is logged in on any Tivoli Workload Scheduler workstation.
38
Specifying users
group=groupname[,...] Specifies the name of the group of which the user is a member. Available for both Unix and Windows users. Wildcard characters are permitted. Do not use this argument for Job Scheduling Console users. logon=username|@ [,...] where: username Specifies the user ID with which the user is logged in on a Tivoli Workload Scheduler workstation. Wildcard characters are permitted. The cpu= attribute must be set to a workstation name or @. Notes: 1. If the useDomainQualifiedUserNames is set to true in the WebSphere Application Server security configuration, then each user name defined in the security file must have the format realm/username at least when exercising the product from one of the following: v composer v Job Scheduling Console v logman v optman v planman For more information on WebSphere Application Server security configuration, refer to IBM Tivoli Workload Scheduler: Planning and installation guide. 2. If the user is defined on a Windows 2000 Service Pack 4 (SP4), or Windows XP Service Pack 2 (SP2), or Windows 2003 system, or when upgrading the Windows operating system from an older version to one of those mentioned above, make sure you add the Impersonate a client after authentication right to the user settings. @ Specifies that the user is logged in with any name or is a member of any Tivoli administrators group.
| | |
Order of user qualification

Tivoli Workload Scheduler scans the user definitions set in the security file stored on the workstation where the user is connected to check which actions on which objects that user is allowed to perform. The way the security file is scanned is top-down, meaning that the first user definition that matches the user name determines the capabilities of the user. For this reason, it is important to order user definitions from most specific to least specific. For example:
#Incorrect: #First User Definition in the Security File USER First CPU=@+LOGON=TWSUser Begin ... End
39
Specifying users
#Second User Definition in the Security File USER Second CPU=@+LOGON=TWSDomain\TWSUser Begin ... End #Correct:
| | | | | |
#First User Definition in the Security File USER First CPU=@+LOGON="TWSDomain\\TWSUser"1 Begin ... End #Second User Definition in the Security File USER Second CPU=@+LOGON=TWSUser Begin ... End
| | | | | |
1. Backslash (\) characters must be escaped on Windows. This means that the character must be repeated and the entire value must be wrapped by double quotes. Updates to users and user groups, and to their access rights, do not come into effect until Tivoli Workload Scheduler (and WebSphere Application Server) are restarted. See Sample security file on page 51 for more information.
Specifying objects
| | | | Specify one or more attributes that identify a set of objects that the user of the user definition is authorized to access. If you specify the object type but no attributes, the authorized actions defined for the user with the access keyword apply to all the objects of that type defined in the Tivoli Workload Scheduler domain. Table 7 lists object attributes that are used to identify a specific object within the set of objects of the same type. For example, a resource object is characterized by a name and the workstation where the resource is defined.
Table 7. Object attributes Type of object name yes yes no yes yes yes yes yes yes yes yes cpu no no yes no no no yes yes no no yes custom no no no yes no no no no no no no jcl no no no no no no yes no no no no logon no no no no no no yes no no no no provider yes no no yes no no no no no no no type yes no no yes no no no no no no no host yes no no no no no no no no no no port yes no no no no no no no no no no
action calendar cpu
| |
event eventrule file job parameter prompt report resource
40
Specifying objects
Table 7. Object attributes (continued) Type of object schedule userobj name yes no cpu yes yes custom no no jcl no no logon no yes provider no no type no no host no no port no no
Note: A parameter is characterized by a CPU only when it represents a local parameter defined on the workstation using the parms utility. Specify object attributes as follows: object-attribute[{+ | ~}object-attribute[...]] where: object-attribute Can be any of the following: name=name[,...] Specifies one or more names for the object type. Wildcard characters are permitted. Multiple names must be separated by commas. v The following values apply to the file object type: globalopts Allows to set global options with the optman command. Gives the following access types: Display access for optman ls and optman show Modify access for optman chg prodsked Allows to create, extend, or reset the production plan. security Allows to manage the security file. Symphony Allows to run stageman and JnextPlan. trialsked Allows to create trial and forecast plans or to extend trial plans. Note that users who have restricted access to files should be given at least the following privilege to be able to display other objects (ie. calendars and cpus):
file name=globalopts access=display
| | | |
| | | | | | | | | |
v For the event object type use one or more of the event type names listed in tables 31 and 32. In addition, you can use the custom attribute to: Specify different rights for different users based on SAP R/3 event names when defining event rules for SAP R/3 events. Define your own security attribute for your custom-made event providers. v For the action object type use one or more of the action type names listed in table 33. cpu=workstation[,...] Specifies one or more workstation, domain, or workstation class names. Wildcard characters are permitted. Multiple names must be separated by commas. If this attribute is not specified, all defined workstations and domains can be accessed. The following Tivoli Workload Scheduler variables are permitted:
41
Specifying objects
The variables supplied with the product that can be used in object attributes are as follows: $jclgroup $jclowner $master $owner $remotes $slaves $thiscpu $user The group name of a jobs executable file. The owner of a jobs executable file. The Tivoli Workload Scheduler master domain manager. The creator of a job stream and its jobs. All standard agent workstations. All fault-tolerant agent workstations. The workstation on which the user is running the Tivoli Workload Scheduler command or program. The user running the Tivoli Workload Scheduler command or program.
Note: The variables $jclgroup and $jclowner can only be verified if the user is running a Tivoli Workload Scheduler program on the workstation where the jobs executable file resides. If the program is being run on a different workstation, the user is denied access. jcl=path | cmd Specifies the command or the path name of a job objects executable file. The command or path must be enclosed in double quotes (). Wildcard characters are permitted. If omitted, all defined job files and commands qualify. logon=username[,...] Specifies the user names. Wildcard characters are permitted. Multiple names must be separated by commas. If omitted, all user names qualify. For the job type object, the following variables are permitted: $jclowner, $owner, and $user. provider=providername[,...] For action object types, specifies the name of the action provider. For event object types, specifies the name of the event provider. Wildcard characters are permitted. Multiple names must be separated by commas. If provider is not specified, no defined objects can be accessed. type=type[,...] For action object types, is the actionType. For event object types, is the eventType. Wildcard characters are permitted. Multiple names must be separated by commas. If type is not specified, all defined objects are accessed for the specified providers. host=hostname For action object types, specifies the TEC or SNMP host name (used for some types of actions, such as sending TEC events, or sending SNMP). If it does not apply, this field must be empty. port=portnumber For action object types, specifies the TEC or SNMP port number (used for
42
Specifying objects
some types of actions, such as sending TEC events, or sending SNMP). If it does not apply, this field must be empty. + ~ Indicates an attribute that objects must have. Indicates an attribute that objects must not have.
Order of object qualification

In a user definition, you can use multiple statements for a single object type to assign different access capabilities to different sets of objects. Because the first matching statement is used, the order of object statements is important. They must be ordered from most specific to least specific. For example:
#Incorrect: job name=@ access=display job name=ar@ access=@ #Correct: job name=ar@ access=@ job name=@ access=display
See Sample security file on page 51 for more information.
Specifying access
Specify the type of access the selected users are allowed to perform on the specified objects as follows: access[=action[,...]] If none are specified, no actions are permitted. Entering access=@ gives users the ability to perform all actions. Table 8 on page 44 lists the available access keywords for each object type, and the capabilities given to users in the Tivoli Workload Scheduler command line.
43
Specifying access
Table 8. Access keywords Object type Access keyword display list submit Note: This keyword has no effect in the current release. use Use specific action types in event rule definitions. Note: For actions with provider TWSAction and types sbj, sbd, or sbs, you must set this keyword in combination with the submit access keyword set for the specific jobs and job streams (schedules) specified in the action. For actions with provider TWSAction and type reply, you must set this keyword in combination with the reply access keyword set for the specific prompts specified in the action. The tws_user of the workstation running the event processing server should not be revoked these submit and reply authorizations. If this happens, the event processing server will not be able to run this type of actions. calendar add add modify Add new calendar definitions in the database. Rename calendar definitions in the database. The user needs add access to the old object and modify access the new object. Delete calendar definitions from the database. Either display or extract calendar definitions from the database. Modify, or lock, or unlock calendar definitions owned by the user in the database. Unlock calendar definitions locked by other users in the database. Use calendars to schedule job streams. composer add, modify, new, replace composer rename Action allowed Display action instances on Tivoli Dynamic Workload Console. List action instances on Tivoli Dynamic Workload Console. CLI command allowed Tivoli Dynamic Workload Console user interface Tivoli Dynamic Workload Console user interface
| | | | | | | | | | | | | | | | | | | | | | | | |
action
delete display modify unlock use
composer delete composer display, create/extract, list, print composer add, modify, lock, new, replace, unlocks composer unlock composer - use calendar in schedules
44
Specifying access
Table 8. Access keywords (continued) Object type cpu (Includes workstations, domains, and workstation classes) Access keyword add add modify Action allowed Add new definitions for workstations, workstation classes, and domains in the database. CLI command allowed composer add, modify, new, replace
Rename definitions for workstations, workstation composer rename classes, and domains in the database. The user needs add access to the old object and modify access the new object. View and send messages to the Tivoli Workload Scheduler conman console. Delete definitions for workstations, workstation classes, and domains from the database. conman console composer delete
console delete display list fence limit link modify
Either display or extract definitions for workstations, composer display, workstation classes, and domains from the database. create/extract, list, print Allows the user to display workstations, domains and links in the plan. Alter workstation job fences in the production plan. Alter workstation job limits in the production plan. Open workstation links. Modify, or lock, or unlock definitions for workstations, workstation classes, and domains owned by the user in the database. Shut down Tivoli Workload Scheduler processing. Start Tivoli Workload Scheduler processing. Force update of the monitoring configuration file for the event monitoring engine. Start the event processor server. Start the event monitoring engine. Start the application server. Stop Tivoli Workload Scheduler processing. Stop the event processor server. Stop the event monitoring engine. Stop the application server. Unlock definitions for workstations, workstation classes and domains locked by other users in the database. Close workstation links. Switch the domain manager functionality to a workstation. Switch the event processor server from the master domain manager to the backup master or vice versa. Use the event in an event rule definition. composer list, conman showcpus conman fence conman limit cpu conman link composer add, modify, lock, new, replace, unlocks conman shutdown conman deployconf, start, starteventprocessor, startmon, startappserver Startup utility conman stop, stop;progressive, stopeventprocessor, stopmon, stopappserver composer unlock
shutdown
| | | | | | | | |
start
stop
unlock
unlink
conman unlink switchmgr, switcheventprocessor
| | | | |
event
start and stop
use
45
Specifying access
Table 8. Access keywords (continued) Object type Access keyword add delete display list modify unlock file (valid only build for CLI) delete You must specify the file display names to which the type of modify access applies. Action allowed Add a new event rule in the database. Delete a event rule from the database. Display and extract event rules from the database and from log records. Display information about event rules in the database and in log records. Modify event rules in the database. Unlock event rules locked by other users in the database. Generate the production plan, trial plans and forecast plans. Deploy rules. Delete objects from the database. Dump the settings contained in the compiled security file. Display global options. Compile the security file to update security settings on a workstation. Edit global options. dumpsec, optman ls, optman show makesec, optman change CLI command allowed composer add, modify, new, rename, replace composer delete composer display, list, print, create, extract composer list composer modify, lock, new, rename, replace composer unlock JnextPlan, prodsked, stageman, planman deploy
| | | | | | | | | | | | | | | | | | | |
eventrule
46
Specifying access
Table 8. Access keywords (continued) Object type job Access keyword add add modify Action allowed Add new job definitions in the database. CLI command allowed composer add, modify, new, replace
Rename job definitions in the database. The user composer rename needs add access to the old object and modify access the new object. Add dependencies to jobs in the production plan. Not valid for workstations in end-to-end environment. Alter the priority of jobs in the production plan. Not valid for workstations in end-to-end environment. Cancel jobs in the production plan. Not valid for workstations in end-to-end environment. Confirm completion of jobs in the production plan. Not valid for workstations in end-to-end environment. Delete dependencies from jobs in the production plan. Not valid for workstations in end-to-end environment. Delete job definitions from the database. Either display or extract job definitions from the database. Display job from the plan. Display information about jobs in the production plan. Kill running jobs. Modify, or lock, or unlock job definitions owned by the user in the database. Release jobs from dependencies in the production plan. Not valid for workstations in end-to-end environment. Reply to job prompts in the production plan. Rerun jobs in the production plan. Not valid for workstations in end-to-end environment. Submit jobs, or commands, or files as jobs into the production plan. Not valid for workstations in end-to-end environment. Unlock job definitions locked by other users in the database. Use job definition as dependency in a job stream. conman adddep
adddep
altpri cancel confirm
conman altpri conman cancel job conman confirm
deldep
conman deldep job
delete display
composer delete composer display, create/extract, list, print, conman display conman showjobs conman kill composer add, modify, lock, new, replace, unlocks conman release job
list kill modify release
reply rerun submit
conman reply conman rerun conman submit docommand, submit file, submit job composer unlock composer - use job in job stream
unlock use
47
Specifying access
Table 8. Access keywords (continued) Object type parameter Access keyword add add modify Action allowed Add new parameter definitions in the database. Rename parameter definitions in the database. The user needs add access to the old object and modify access the new object. Delete parameter definitions from the database. Either display or extract parameter definitions from the database. Modify, or lock, or unlock parameters definitions owned by the user in the database. Unlock parameter definitions locked by other users in the database. Add new prompt definitions in the database. CLI command allowed composer add, modify, new, replace composer rename
delete display
composer delete composer display, create/extract, list, print, utility parms composer add, modify, lock, new, replace, unlocks composer unlock composer add, modify, new, replace
modify unlock prompt add add modify
Rename prompt definitions in the database. The user composer rename needs add access to the old object and modify access the new object. Delete prompt definitions from the database. Either display or extract prompt definitions from the database. Display prompts waiting for a response. Display information about prompts. composer delete composer display, create/extract, list, print, conman recall conman showprompts
delete display
list modify reply unlock use
Modify, or lock, or unlock prompt definitions owned composer add, modify, lock, by the user in the database. new, replace, unlocks Reply to a job or job stream prompt. Unlock resource definitions locked by other users in the database. Use prompts when defining or submitting jobs and job streams and when adding dependencies from prompts. Display reports on Tivoli Dynamic Workload Console. conman reply composer unlock composer - use prompt in job and job stream, and conman add dependencies, submit docommand, file, job, sched Tivoli Dynamic Workload Console user interface
| |
report
display
48
Specifying access
Table 8. Access keywords (continued) Object type resource Access keyword add add modify Action allowed Add new resource definitions in the database. Rename resource definitions in the database. The user needs add access to the old object and modify access the new object. Delete resource definitions from the database. Either display or extract resource definitions from the database. Displays information about resources. Modify, or lock, or unlock resource definitions owned by the user in the database. Change the number of units of a resource on a workstation. Use resources when defining or submitting jobs and job streams and when adding dependencies from resources. CLI command allowed composer add, modify, new, replace composer rename
delete display list modify resource use
composer delete composer display, create/extract, list, print conman showresources composer add, modify, lock, new, replace, unlocks conman resource composer - use resource in job and job stream, and conman - add dependencies, submit docommand, file, job, sched
49
Specifying access
Table 8. Access keywords (continued) Object type schedule Access keyword add add modify Action allowed Add new job stream definitions in the database. Rename job stream definitions in the database. The user needs add access to the old object and modify access the new object. Add dependencies to job stream in the production plan. Not valid for workstations in end-to-end environment. Alter the priority of job stream in the production plan. Not valid for workstations in end-to-end environment. Cancel job stream in the production plan. Not valid for workstations in end-to-end environment. Delete dependencies from job stream in the production plan. Not valid for workstations in end-to-end environment. Delete job stream definitions from the database. Either display or extract job stream definitions from the database. Display job streams from the plan. Displays information about job streams. Modify the limit for job concurrently running within a job stream. Modify, or lock, or unlock job stream definitions owned by the user in the database. Release job streams from dependencies. Reply to a job stream prompts. Submit job streams in the current production. Unlock job stream definitions locked by other users in the database. Add new user definitions in the database. CLI command allowed composer add, modify, new, replace composer rename
adddep
conman adddep
altpri
conman altpri
cancel deldep
conman cancel sched conman deldep sched
delete display
composer delete composer display, create/extract, list, print, conman display conman showschedules conman limit sched composer add, modify, lock, new, replace, unlocks conman release sched conman reply conman submit sched composer unlock composer add, modify, new, replace
list limit modify release reply submit unlock userjob add add modify
Rename user definitions in the database. The user composer rename needs add access to the old object and modify access the new object. Alter user passwords in the database. Delete user definitions from the database. Either display or extract user definitions from the database. conman altpass composer delete composer display, create/extract, list, print
altpass delete display modify unlock
Modify, or lock, or unlock user definitions owned by composer add, modify, lock, the user in the database. new, replace, unlocks Unlock user definitions locked by other users in the database. composer unlock
50
Sample security file

The following is a sample security file. A description of the file follows the listing.
########################################################### # Sample Security File ###########################################################
| |
# (1) APPLIES TO TWS_users AND ROOT USERS LOGGED IN ON THE # begin # OBJECT job schedule resource prompt file calendar cpu parameter name=@ ~ name=r@ userobj cpu=@ + logon=@ eventrule name=@ action event report provider=@ provider=@ name=@ ATTRIBUTES ACCESS CAPABILITIES ---------------------access=@ access=@ access=@ access=@ access=@ access=@ access=@ access=@ access=@ access=add,delete,display,modify,list,unlock access=display,submit,use,list access=use access=display # ---------- -----------MASTER DOMAIN MANAGER. user mastersm cpu=$master + logon=TWS_user,root
| | | |
| | | | | | | | | | | | | |
end ########################################################### # (2) APPLIES TO TWS_users AND ROOT USERS LOGGED IN ON ANY # WORKSTATION OTHER THAN THE MASTER DOMAIN MANAGER. user sm logon=TWS_user,root begin # OBJECT ATTRIBUTES ACCESS CAPABILITIES # ---------- --------------------------------job cpu=$thiscpu access=@ schedule cpu=$thiscpu access=@ resource cpu=$thiscpu access=@ prompt access=@ calendar access=@ cpu cpu=$thiscpu access=@ parameter cpu=$thiscpu ~ name=r@ access=@ action provider=@ access=display,submit,use,list event provider=@ access=use report name=RUNHIST,RUNSTATS access=display file name=globalopts access=display end ########################################################### # (3) APPLIES TO USERS LOGGED INTO THE SYS GROUP ON THE # MASTER DOMAIN MANAGER. user masterop cpu=$master + group=sys begin # OBJECT ATTRIBUTES ACCESS CAPABILITIES # ---------- --------------------------------job cpu=@ + logon="TWS_domain\\TWS_user" access=@
51

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
job cpu=@ + logon=root
access=adddep,altpri,cancel, confirm,deldep,release, reply,rerun,submit,use
job
schedule schedule resource
file file file file calendar cpu parameter report end ########################################################### # (4) APPLIES TO USERS LOGGED INTO THE SYS GROUP ON ANY # WORKSTATION OTHER THAN THE MASTER DOMAIN MANAGER user op group=sys begin # OBJECT ATTRIBUTES ACCESS CAPABILITIES # ---------- --------------------------------job cpu=$thiscpu + logon=$user access=@ job cpu=$thiscpu + logon=root access=adddep,altpri,cancel, confirm,deldep,release, reply,rerun,submit,use job cpu=$thiscpu ~ logon=root access=adddep,altpri,cancel, confirm,deldep,release, reply,rerun,submit,use schedule cpu=$thiscpu access=@ resource access=add,display,resource,use prompt access=add,display,reply,use calendar access=use cpu cpu=$thiscpu access=console,fence,limit, link,start,stop,unlink parameter name=@ ~ name=r@ access=@ end ########################################################### # (5) APPLIES TO USERS LOGGED INTO THE MIS GROUP ON # ANY WORKSTATION. user misusers group=mis begin # OBJECT ATTRIBUTES ACCESS CAPABILITIES # ---------- --------------------------------job cpu=$thiscpu + logon=$user access=@ job cpu=$thiscpu + logon=$jclowner ~ logon=root access=submit,use schedule cpu=$thiscpu access=add,submit, modify,display parameter name=r@ access=@ parameter name=@ access=display
cpu=@ + logon=$user,$jclowner ~ logon=root access=add,adddep,altpri, cancel,confirm, deldep,release,reply, rerun,submit,use cpu=$thiscpu access=@ cpu=@ access=adddep,altpri,cancel, deldep,limit,release, submit access=add,display, resource,use name=globalopts access=display name=prodsked access=display name=symphony access=display name=trialsked access=build, display access=display,use cpu=@ access=@ name=@ ~ name=r@ access=@ name=RUNHIST,RUNSTATS access=display
52

| | | | | | | | | | | | | | | | | | |
end ########################################################### # (6) APPLIES TO ALL OTHER USERS LOGGED IN ON ANY # WORKSTATION. user default logon=@ begin # OBJECT ATTRIBUTES ACCESS CAPABILITIES # ---------- --------------------------------job cpu=$thiscpu + logon=$user access=@ job cpu=$thiscpu + logon=$jclowner ~ logon=root access=submit,use schedule cpu=$thiscpu access=add,submit, modify,display parameter name=u@ access=@ parameter name=@ ~ name=r@ access=display end ###########################################################
Note that the order of definitions is from most to least specific. Because of the order, TWS_users and root users are matched first, followed by users in the sys group, and then users in the mis group. All other users are matched with the last definition, which is the least specific. | | | | | | | | | | | | | | | | | | | # (1) APPLIES TO TWS_users AND ROOT USERS LOGGED IN ON THE MASTER DOMAIN MANAGER. user mastersm cpu=$master + logon=TWS_user,root This user definition applies to GUI and CLI access for TWS_users and root users logged into a master domain manager. They are given unrestricted access to all objects, except parameters that have names beginning with r. Access to the r parameters is given only to users in the mis group. They are the only ones who can generate all kinds of plans and who can create, update, and delete event rule definitions. # (2) APPLIES TO TWS_users AND ROOT USERS LOGGED IN ON ANY WORKSTATION OTHER THAN THE MASTER DOMAIN MANAGER. user sm logon=maestro,root This user definition applies to TWS_users and root users to whom definition (1) does not apply, which are those who are logged in on any workstation other than the master domain manager. They are given unrestricted access to all objects on their login workstation. Note that prompts, files, and calendars are global in nature and are not associated with a workstation. They can use event rules, but are not allowed to create, update, or delete event rule definitions. # (3) APPLIES TO USERS LOGGED INTO THE SYS GROUP ON THE MASTER DOMAIN MANAGER. user masterop cpu=$master + group=sys This user definition applies to users logged into the sys group on the master domain manager. They are given a unique set of access capabilities. Multiple object statements are used to give these users specific types of access to different sets of objects. For example, there are three job statements: v The first job statement permits unrestricted access to jobs that run on any workstation (@) under the users name ($user).
53

v The second job statement permits specific types of access to jobs that run on any workstation and that run as root. v The third job statement permits specific types of access to jobs that run on any workstation. The jobs must run under the users name ($user) or under the name of the owner of the job file ($jclowner). Jobs that run as root are excluded. They are the only users defined on the master domain manager, different from maestro or root, who can generate trial and forecast plans. # (4) APPLIES TO USERS LOGGED INTO THE SYS GROUP ON ANY WORKSTATION OTHER THAN THE MASTER DOMAIN MANAGER. user op group=sys This user definition applies to sys group users to whom definition (3) does not apply, which are those who are logged in on any workstation other than the master domain manager. They are given a set of access capabilities similar to those in definition (3). The exception is that access is restricted to objects on the users login workstation ($thiscpu). # (5) APPLIES TO USERS LOGGED INTO THE MIS GROUP ON ANY WORKSTATION. user misusers group=mis This user definition applies to users logged into the mis group on any workstation. They are given a limited set of access capabilities. Resources, prompts, files, calendars, and workstations are omitted, which prevents access to these objects. These users are given unrestricted access to parameters with names that begin with r, but can only display other parameters. # (6) APPLIES TO ALL OTHER USERS LOGGED IN ON ANY WORKSTATION. user default logon=@ This user definition gives a set of default capabilities to users other than those covered by the preceding definitions (1 to 5). These users are given unrestricted access to parameters with names that begin with u, but can only display other parameters. No access is permitted to parameters with names that begin with r.
54
Chapter 5. Managing the production cycle

The core part of a job management and scheduling solution is the creation and management of the production plan. The production plan is the to-do list that contains the actions to be performed in a stated interval of time on the workstations of the scheduling network using the available resources and preserving the defined relationships and restrictions. This chapter describes how Tivoli Workload Scheduler manages plans. The chapter is divided into the following sections: v What is new in managing the plan v Plan management basic concepts v Customizing plan management using global options on page 65 v Generating a production plan - JnextPlan on page 69 v Planman command line on page 72 v Starting production plan processing on page 87 v Automating production plan processing on page 87 | | | | | | | | | | | |
What is new in managing the plan

The following enhancements are new in plan management: v The JnextPlan command and the final job stream now start WebSphere Application Server automatically as their first step. There is no longer a need to run the CheckPrerequisites script to ensure that the application server is up before running final. v A new planning process (independent from JnextPlan and from the Symphony file creation and deployment processes) activates event rules and deploys event management configuration to the agents. The process is described in The event rule management process on page 92. v A new planman deploy command can be used to manually deploy all event rules that are not in draft state.
Plan management basic concepts

The production plan contains information about the jobs to run, on which fault-tolerant agent, and what dependencies must be satisfied before each job is launched. Tivoli Workload Scheduler creates the production plan starting from the modeling data stored in the database and from an intermediate plan called preproduction plan. The preproduction plan is automatically created and managed by the product. To avoid problems the database is locked during the generation of the plan, and is unlocked when the generation completes or if an error condition occurs. The preproduction plan is used to identify in advance the job stream instances and the external follows job stream dependencies involved in a specified time-window. You use the JnextPlan script on the master domain manager to generate the production plan and distribute it across the Tivoli Workload Scheduler network. For additional information on the JnextPlan script, refer to Generating a production plan - JnextPlan on page 69.
55
Plan management basic concepts

To generate and start a new production plan Tivoli Workload Scheduler performs the following steps: 1. Updates the preproduction plan with the objects defined in the database that were added or updated since the last time the plan was created or extended. 2. Retrieves from the preproduction plan the information about the job streams to run in the specified time period and saves it in an intermediate production plan. 3. Includes in the new production plan the uncompleted job streams from the previous production plan. 4. Creates the new production plan and stores it in a file named Symphony. 5. Distributes a copy of the Symphony file to the workstations involved in the new product plan processing. 6. Logs all the statistics of the previous production plan into an archive 7. Updates the job stream states in the preproduction plan. The copy of the newly generated Symphony file is deployed starting from the top domain's fault-tolerant agents and domain managers of the child domains and down the tree to all subordinate domains. Each fault-tolerant agent that receives the production plan can continue processing even if the network connection to its domain manager goes down. At each destination fault-tolerant agent the Tivoli Workload Scheduler processes perform the following actions to manage job processing: 1. Access the copy of the Symphony file and read the instructions about which jobs to run. 2. Make calls to the operating system to launch jobs as required. 3. Update its copy of the Symphony file with the job processing results and send notification back to the master domain manager and to all full status fault-tolerant agents. The original copy of the Symphony file stored on the master domain manager and the copies stored on the backup master domain managers, if defined, are updated accordingly. This means that during job processing, each fault-tolerant agent has its own copy of the Symphony file updated with the information about the jobs it is running (or that are running in its domain and child domains if the fault-tolerant agent is full-status or a domain manager). Also the master domain manager (and backup master domain manager if defined) has the copy of the Symphony file that contains all updates coming from all fault-tolerant agents. In this way the Symphony file on the master domain manager is kept up to date with the jobs that need to be run, the ones that are running, and the ones that have completed. The processing that occurs on each workstation involved in the current production plan activities is described in more detail in Tivoli Workload Scheduler workstation processes on page 11. Note: While the current production plan is in process, any changes you make to the plan using conman do not affect the definitions in the database. Changes to the objects in the database do not affect the plan until the production plan is extended or created again using the JnextPlan script or planman command-line interface. Updates to objects in the database do not affect instances of those objects already in the production plan.
56
Preproduction plan
Preproduction plan
The preproduction plan is used to identify in advance the job stream instances and the job stream dependencies involved in a specified time period. This improves performance when generating the production plan by preparing in advance a high-level schedule of the anticipated production workload. The preproduction plan contains: v The job stream instances to be run during the covered time interval. v The external follows dependencies that exist between the job streams and jobs included in different job streams. A job or job stream that cannot start before another specific external job or job stream is successfully completed is named successor. An external job or job stream that must complete successfully before the successor job or job stream can start is named predecessor. Tivoli Workload Scheduler automatically generates, expands, and updates, if necessary, the preproduction plan by performing the following steps: v Removes the job stream instances in COMPLETE and CANCEL states. v Selects all the job streams scheduled after the end of the current production plan and generates their instances. v Resolves all job and job stream dependencies, including external follows dependencies, according to the defined matching criteria. To avoid any conflicts the database is locked during the generation of the preproduction plan and unlocked when the generation completes or if an error condition occurs. At this stage only the job streams with the time they are scheduled to start and their dependencies are highlighted. All the remaining information about the job streams and the other scheduling objects (calendars, prompts, domains, workstations, resources, files, and windows users) that will be involved in the production plan for that time period are not included, but are retrieved from the database as soon as the production plan is generated. When the production plan is extended, old job stream instances are automatically removed. The criteria used in removing these instances takes into account this information: v The first job stream instance that is not in COMPLETE state at the time the new plan is generated (FNCJSI). This job stream instance can be both a planned instance, that is an instance added to the plan when the production plan is generated, and a job stream instance submitted from the command line during production using the conman sbs command. v The time period between the time FNCJSI is planned to start and the end time of the old production plan. Assuming T is this time period, the algorithm used to calculate which job stream instances are removed from the preproduction plan is the following: if T < 7 All job stream instances older than 7 days from the start time of the new production plan are removed from the preproduction plan; all job stream instances closer than 7 days to the start time of the new production plan are kept regardless of their states.
57
Preproduction plan
if T > 7 All job stream instances older than FNCJSI are removed from the preproduction plan; all job stream instances younger than FNCJSI are kept. This algorithm is used to ensure that the preproduction plan size does not increase continuously and, at the same time, to ensure that no job stream instance that is a potential predecessor of a job stream newly added to the new preproduction plan is deleted. Note: In the Tivoli Workload Scheduler for z/OS terminology the concept that corresponds to the preproduction plan is long term plan (LTP).
Identifying job stream instances in the plan

In earlier versions than 8.3 the plan had a fixed duration of one day. Since version 8.3 the plan can cover a period lasting several days or less than one day. This change has added the possibility to have in the same plan more than one instance of the same job stream with the same name, and also the need to define a new convention to uniquely identify each job stream instance in the plan. Each job stream instance is identified in the plan by the following values: workstation Specifies the name of the workstation on which the job stream is scheduled to run. jobstreamname Corresponds to the job stream name used in earlier versions of Tivoli Workload Scheduler. scheddateandtime Represents when the job stream instance is planned to start in the preproduction plan. It corresponds to the day specified in the run cycle set in the job stream definition by an on clause and the time set in the job stream definition by an at or schedtime keyword. If set, the schedtime keyword is used only to order chronologically the job stream instances in the preproduction plan while, if set, the at keyword also represents a dependency for the job stream. For more information about these keywords refer to on on page 161, at on page 138 and schedtime on page 171. Together with these two values that you can set in the job stream definition, Tivoli Workload Scheduler generates and assigns a unique alphanumeric identifier to each job stream instance, the jobstream_id, for its internal processing. For more information on the format of the jobstream_id refer to showjobs on page 321. You can use any of the two types of identifiers, workstation#jobstreamname and scheddateandtime instead of workstation#jobstream_id, to uniquely identify a job stream instance when managing job streams in the plan using the conman command-line program. The default convention used to identify a job stream instance, both in this guide and in the command-line interfaces of the product, is the one that uses workstation#jobstreamname and scheddateandtime. For more information on how to specify a job stream instance in a command using conman, refer to Selecting job streams in commands on page 257.
58
Managing external follows dependencies
Managing external follows dependencies for jobs and job streams

During the creation of the preproduction plan, all external follows dependencies to job streams and jobs are resolved using four different possible matching criteria: Closest preceding Using the closest earlier job or job stream instance. In this case the follows...previous clause is set in the object definition. Figure 4 shows a job stream Js1 which has an external follows dependency from the closest earlier instance of job stream Js2 The time window where the predecessor is searched is greyed out in the figure.
Js2
Js1
Figure 4. Closest preceding matching criteria
Within a relative interval Considering the job or job stream instances defined in a range with an offset relative to the start time of the dependent job or job stream, for example from -25 hours before the dependent job stream start time to -5 hours after the dependent job stream start time. In this case the follows...relative to clause is set in the object definition. Figure 5 shows a job stream Js1 which has an external follows dependency on the job stream instance of Js2 that starts with an offset of 2 hours with respect to Js1.
Js2
-2h
Js1
+2h
Figure 5. Within a relative interval matching criteria
Within an absolute interval Using only the job or job stream instances defined in a range, for example from today at 6:00 a.m. to the day after tomorrow at 5:59 a.m. In this case the follows ... absolute to clause is set in the object definition. Figure 6 shows a job stream Js1 which has an external follows dependency from the instance of job stream Js2 that is positioned in the preproduction plan between 7 a.m. and 9 a.m.
Js2
Js1
7a.m.
9a.m.
Figure 6. Within an absolute interval matching criteria
Same day Considering the job or job stream instances planned to run on the same
59

day. In this case the clause follows...sameday is set in the object definition. Figure 7 shows a job stream Js1 which has an external follows dependency from the instance of job stream Js2 that is positioned to start on the same day.
Js2
startOfDay
Js1
1 minute before the next startOfDay
Figure 7. Sameday matching criteria
Regardless of which matching criteria are used, if multiple instances of potential predecessor job streams exist in the specified time interval, the rule used by the product to identify the correct predecessor instance is the following: 1. Tivoli Workload Scheduler searches for the closest instance that precedes the depending job or job stream start time. If such an instance exists, this is the predecessor instance. 2. If there is no preceding instance, Tivoli Workload Scheduler considers the correct predecessor instance as the closest instance that starts after the depending job or job stream start time. This behavior applies for external follows dependencies between job streams. For external follows dependencies of a job stream or job from another job the criteria are matched by considering by the start time of the job stream hosting the predecessor job instead of the start time of the predecessor job itself. Figure 8 shows in bold the instances of job1 the successor job or job stream is dependent on.
Js1 job1
Js1
job1
Successor job or job stream
Figure 8. Closest preceding predecessor job
External follows dependencies are identified between jobs and job streams stored in the database whose instances are added to the preproduction plan when the preproduction plan is automatically created or extended. Job and job stream instances submitted in production from the conman command line are written in the preproduction plan but they are not used to recalculate predecessors of external follows dependencies already resolved in the preproduction plan. A job or job stream not yet included in the production plan, but that can be a potential predecessor of instances of jobs and job streams added to the production plan as the production plan is extended, is called a pending predecessor. A pending predecessor is like a dummy occurrence created by the planning process to honor a dependency that has been resolved in the preproduction plan, but that cannot be resolved in the current production plan because the predecessors start time is not
60

within the current production plan end time. Figure 9 shows how a pending predecessor and its successor are positioned in the preproduction plan. The way in which pending predecessors are managed is strictly linked to whether
Pending predecessor
Successor
End of Production Plan
Figure 9. Pending predecessor instance
or not the successor job or job stream is carried forward: v If the successor is carried forward when the production plan is extended, the predecessor is included in the new production plan and the dependency becomes current. v If the successor is not carried forward when the production plan is extended, the predecessor is included in the new production plan, but the dependency becomes orphaned. This can happen, for example, if, when extending the production plan, the successor is carried forward and the pending predecessor is not added to the plan because it was flagged as draft in the database. The orphaned dependencies are marked with a [O] in the Dependencies column in the output of the conman sj command. For information about the conman sj command refer to showjobs on page 321. When dealing with an orphaned dependency you must verify if it can be released and if so cancel it.
Production plan
After having created or updated the preproduction plan, Tivoli Workload Scheduler completes the information stored in the preproduction plan with the information stored in the database about the operations to be performed in the selected time period and the other scheduling objects involved when processing the plan and copies it in a new Symphony file. It also adds in this file the cross-plan dependencies, such as job streams carried forward from the production plan already processed, and archives the old Symphony file in the schedlog directory. At the end of this process the newSymphony file contains all the information implementing the new production plan. A copy of the new Symphony file is distributed to all the workstations involved in running jobs or job streams for that production plan. In the security file the user authorization required to generate the production plan is the build access keyword on the prodsked and Symphony files. Note: To avoid running out of disk space, keep in mind that each job or job stream instance increases the size of the Symphony file by 512 bytes. For information on how to generate the production plan refer to Generating a production plan - JnextPlan on page 69.
Understanding carry forward options

Job streams are carried forward when the production plan is generated. How the job stream is carried forward depends on: v The carryforward keyword in the job stream. See carryforward on page 139.
61

v The enCarryForward global option. See IBM Tivoli Workload Scheduler Planning and Installation Guide. v The stageman -carryforward command-line keyword. See The stageman command on page 82. v The carryStates global option. See IBM Tivoli Workload Scheduler Planning and Installation Guide. Table 9 shows how the carry forward global options work together.
Table 9. Carry forward global options settings Global options enCarryForward=all carryStates=() enCarryForward=no enCarryForward=yes carryStates=(states) Carry forward operation Job streams are carried forward only if they did not complete. All jobs are carried forward with the job streams. This is the default setting. No job streams are carried forward. Job streams are carried forward only if they have both jobs in the specified states and the carryforward keyword set in the job stream definition. Only the jobs in the specified states are carried forward with the job streams. Job streams are carried forward only if they did not complete and have the carryforward keyword set in the job stream definition. All jobs are carried forward with the job streams. Job streams are carried forward only if they have jobs in the specified states. Only jobs in the specified states are carried forward with the job streams.
enCarryForward=yes carryStates=()
enCarryForward=all carryStates=(states)
Table 10 shows the result of the carry forward setting based on how the enCarryForward global option and the stageman -carryforward keywords are set.
Table 10. Resulting carry forward settings enCarryForward NO NO YES ALL ALL YES YES stageman -carryforward YES ALL NO NO YES ALL YES Resulting carry forward setting NO NO NO NO ALL ALL YES
The carry forward option set in the job stream definition is persistent. This means that an unsuccessful job stream that is marked as carryforward, continues to be carried forward until one of the following occurs: v It ends in a SUCC state v Its UNTIL time is reached v It is cancelled.
62

The carried forward job stream naming convention is affected by the value assigned to the global option enLegacyId. For more information on the different settings for this option, refer to Customizing plan management using global options on page 65. Note: Regardless of how carry forward options are set, job streams that do not contain jobs are not carried forward. If you set carryStates=(succ) and either enCarryForward=all or enCarryForward=yes, then the next time you run JnextPlan there will be misalignment between the preproduction plan and the new Symphony file. This happens because, the preproduction plan does not contain the instances of job streams that ended successfully, but the new Symphony file does. The result of this misalignment is that dependencies are not resolved according to carried forward successful job stream instances because they no longer exist in the preproduction plan.
Trial plan
A trial plan is a projection of what a production plan would be if it covered a longer period of time. For example, if you generate a production plan that covers two days, but you want to know what the plan would be if it covered three days you can generate a trial plan. These are the characteristics of a trial plan: v Its start date matches: The preproduction plan start date. The production plan end date. v It is based on the static information stored in the current preproduction plan. v It cannot be run to manage production. v It can be managed by users with access build on trialsked file object type set in the security file on the master domain manager. v It produces a file stored in the schedlog directory with these properties: The same format as the Symphony file. The file name starts with a leading T. Trial plan generations may result in the extension of the preproduction plan end time. This depends on the settings of the minLen and maxLen global options. When this happens, the database is locked and only unlocked when the operation completes. There is no restriction on the time period selected for a trial plan, but the size of the resulting file containing all trial plan information must be taken into account. Because the trial plan is based on the static information stored in the preproduction plan, it does not take into account any dynamic updates made to the Symphony file while the production plan is being processed, so all the job streams it contains are in one of these two states: HOLD If they are dependent on other job streams or if their start time is later than the start of plan time. READY If they are free from dependencies and their start time has elapsed.
| | |
63
Trial plan
The operations that can be performed on a trial plan on the master domain manager are: creation Used to create a trial plan to have an overview of production when a production plan does not yet exist. extension Used to create a trial plan of the extension of the current production plan to have an overview of how production evolves in the future. For information on how to create or extend a trial plan, refer to Planman command line on page 72.
Forecast plan
The forecast plan is a projection of what the production plan would be in a chosen time frame. For example, if you generated a production plan that covers two days and you want to know what the plan would be for the next week you can generate a forecast plan. These are the characteristics of a forecast plan: v It covers any time frame, in the future, in the past or even partially overlapping the time period covered by the current production plan. v It is based on a sample preproduction plan covering the same time period selected for the forecast plan. This sample preproduction plan is deleted after the forecast plan is created. v It cannot be run to manage production. v It can be managed by users with access build on trialsked file object type set in the security file on the master domain manager. v It produces a file stored in the schedlog directory with these properties: The same format as the Symphony file. The file name starts with a leading F. While creating a forecast plan the database is locked, and only unlocked when the operation completes. There is no restriction on the time period selected to generate a forecast plan, but the size of the resulting file containing all forecast plan information must be taken into account. Because the forecast plan is based on the static information stored in the database, it does not take into account any dynamic updates made to the Symphony file while the production plan is being processed or the preproduction plan, so all the job streams it contains are in one of these two states: HOLD If they are dependent on other job streams or if their start time is later than the start of plan time. READY If they are free from dependencies and their start time has elapsed. The operation that can be performed on a forecast plan on the master domain manager is:
64
Forecast plan
creation It is used to create a forecast plan to have an overview of production in a chosen time frame. For information on how to create a forecast plan, refer to Planman command line on page 72.
Customizing plan management using global options

You can customize some criteria for Tivoli Workload Scheduler to use when managing plans by setting specific options on the master domain manager using the optman command-line program. You need to generate the plan again to activate the new settings. The options you can customize are: Properties impacting the generation of the preproduction plan: minLen It is the minimum length, calculated in days, of the preproduction plan which is left, as a buffer, after the end of the newly generated production plan. The value assigned to this option is used when the script UpdateStats is run from within JnextPlan. The default setting for this property is the lowest value that can be assigned to it, 8 days. maxLen It is the maximum length, calculated in days, of the preproduction plan which is left, as a buffer, after the end of the newly generated production plan. The default setting for this option is the lowest value that can be assigned to it, 14 days. Properties impacting the generation or extension of the production plan: startOfDay It represents the start time of the Tivoli Workload Scheduler processing day in 24-hour format: hhmm (0000-2359). The default setting is 0600. enCarryForward 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 old to the new production plan. The available settings for enCarryForward are yes, no, and all. The default setting is all. carryStates This is an option that affects how the stageman command manages jobs in carried forward job streams. Its setting determines, based on their state, the jobs to be included in job streams that are carried forward. For example if :
carryStates=abend exec hold
then all jobs that are in states abend, exec, or hold are included in carried forward job streams. The default setting is:
carryStates=null
that means that all jobs are included regardless of their states. enCFInterNetworkDeps This is an option that affects how the stageman command manages internetwork dependencies. Enter yes to have all EXTERNAL job
65
Customizing plan management

streams carried forward . Enter no to completely disable the carry forward function for internetwork dependencies. The default setting is yes. enCFResourceQuantity This is an option that affects how the stageman command manages resources. When the production plan is extended, one of the following situations occurs: v A resource not used by any of the job streams carried forward from the previous production plan is referenced by new job or job stream instances added to the new production plan. In this case the quantity of the resource is obtained from the resource definition stored in the database. v A resource used by one or more job streams carried forward from the previous production plan is not referenced by job or job stream instances added to the new production plan. In this case the quantity of the resource is obtained from the old Symphony file. v A resource used by one or more job streams carried forward from the previous production plan is referenced by job or job stream instances added to the new production plan. In this case the quantity of the resource that is taken into account is based on the value assigned to the enCFResourceQuantity option: If enCFResourceQuantity is set to YES The quantity of the resource is obtained from the old Symphony file. If enCFResourceQuantity is set to NO The quantity of the resource is obtained from the resource definition stored in the database. The default setting is yes. enEmptySchedsAreSucc This option rules the behavior of job streams that do not contain jobs. The available settings are: yes no The jobs streams that do not contain jobs are marked as SUCC as their dependencies are resolved. The jobs streams that do not contain jobs remain in READY state.
enPreventStart This is an option to manage, for multiple day production plan, any job streams without an at time constraint set. It is used to prevent job stream instances not time dependent from starting all at once as the production plan is created or extended. The available settings are: yes A job stream cannot start before the startOfDay of the day specified in its scheduled time even if free from dependencies. A job stream can start immediately as the production plan starts if all its dependencies are resolved.
no
enLegacyId This is an option that affects how job streams are named in the plan and its aim is to keep consistency in identifying job streams in
66

the plan in mixed environments with a Tivoli Workload Scheduler version 8.3 master domain manager. The value assigned to this option is read either when the production plan is created or extended or when submitting job streams in production using conman. The available settings are: yes The jobstream_id of job stream named jobstream_name is set to jobstream_nameN where N is an incremental number assigned by an internal counter; it is set to null if only one instance of that job stream exists in the plan. If the job stream named jobstream_name is then carried forward, its identifier is set to CFjobstream_nameN. This setting is useful to keep consistency when managing job streams, even those carried forward, using conman when logged on a Tivoli Workload Scheduler 8.2.x agent in a Tivoli Workload Scheduler network with an 8.3 master domain manager.In particular, if the production period is one day and no multiple instances of the same job stream are submitted, the backward compatibility, when managing job streams in production from a Tivoli Workload Scheduler version 8.2.x agent, is complete. no The job stream identifier jobstream_id is generated as described in showjobs on page 321. Carried forward job streams keep their original names and identifiers, and they report between braces {} the date when they were carried forward.
logmanSmoothPolicy This is an option that affects how the logman command handles statistics and history. It sets the weighting factor that favors the most recent job run when calculating the normal (average) run time for a job. This is expressed as a percentage. The default setting is -1, which means that this property is not enabled. logmanMinMaxPolicy This option defines how the minimum and maximum job run times are logged and reported by logman. The available settings for the logmanMinMaxPolicy option are: elapsedtime The maximum and minimum run times and dates that are logged are based only on a jobs elapsed time. Elapsed time, expressed in minutes, is greatly affected by system activity. It includes both the amount of time a job used the CPU and the time the job had to wait for other processes to release the CPU. In periods of high system activity, for example, a job might have a long elapsed time, and yet use no more CPU time than in periods of low system activity. The values are updated only if the latest job run has an elapsed time greater than the existing maximum, or less than the existing minimum. The maximum and minimum run times and dates that are logged are based only on a job's CPU time. The CPU time is a measure, expressed in seconds, of the actual time a job used the CPU, and it does
cputime
67

not include the intervals when the job was waiting. The values are updated only if the latest job run has a CPU time greater than the existing maximum, or less than the existing minimum. both The elapsed time and CPU time values are updated independently to indicate their maximum and minimum extremes, but the run dates correspond only to the elapsed time values. No record is kept, in this case, of the run dates for maximum and minimum CPU times.
The default setting is both. enTimeZone By setting the option you enable or disable the management of time zones across the Tivoli Workload Scheduler network. The available settings for the enTimeZone option are: no Disable time zone management. This means that the values assigned to all timezone keywords in the definitions are ignored. Enable time zone management. This means that the values assigned to the timezone settings are used to calculate the time when the jobs and jobs streams will run on the target workstations.
yes
Refer toEnabling time zone management on page 461 for more information about the enTimeZone variable. enLegacyStartOfDayEvaluation This option affects the way the startOfDay variable is managed across the Tivoli Workload Scheduler network. This option is introduced with Tivoli Workload Scheduler version 8.3 Fix Pack 01 and it requires the enTimeZone variable set to yes to become operational. The available settings for the enLegacyStartOfDayEvaluation option are: no The value assigned to the startOfDay option on the master domain manager is not converted to the local time zone set on each workstation across the network. The value assigned to the startOfDay option on the master domain manager is converted to the local time zone set on each workstation across the network.
yes
Refer to How Tivoli Workload Scheduler manages time zones on page 462 for more information about the enLegacyStartOfDayEvaluation variable. For information on how to set options using the optman command-line program, refer to the IBM Tivoli Workload Scheduler Planning and Installation Guide.
68
Generating a production plan - JnextPlan

The entire process of moving from an old to a new production plan, including its activation across the Tivoli Workload Scheduler network, is managed by the JnextPlan script. You can run JnextPlan at any time during the processing day. The new production plan that is generated is immediately activated on the target workstations regardless the time set in the startOfDay variable. Notes: 1. When you run the JnextPlan script, the workstation processes are stopped and restarted on all the workstations across the Tivoli Workload Scheduler network. For more information about workstation processes, refer to Chapter 2, Understanding workstation processes, on page 11. 2. Check the IBM Tivoli Workload Scheduler: Administration and Troubleshooting guide for information on specific scenarios that might require JnextPlan customization.
Authorization
The JnextPlan command is issued from a command prompt shell on the master domain manager and can be invoked by one of the following users: v The TWS_user user who installed the product on that machine, if not disabled by the settings defined in the security file. v Either root or Administrator, depending on the operating system installed on that machine, if not disabled by the settings defined in the security file. v Any Tivoli Workload Scheduler user authorized in the security file on the master domain manager as follows:
file name=prodsked,Symphony access=build
JnextPlan can be run at any time while the production plan is in process to update in the production plan the topology of the Tivoli Workload Scheduler network in terms of workstation, workstation class and domain object definitions. For example, if you created a new workstation definition in the database and you want to add that workstation definition into the plan to later submit jobs or job streams on that workstation you run the command:
JnextPlan -for 0000
Note: Make sure the enCarryForward option is set to ALL before running:
JnextPlan -for 0000
Syntax
JnextPlan [-from mm/dd/[yy]yy[hhmm[tz | timezone tzname]]] {-to mm/dd/[yy]yy[hhmm[tz | timezone tzname]] | -for [h]hhmm [-days n] | -days n}
Arguments
-from Sets the start time of the production plan. The format of the date is specified in the localopts file; where hhmm identifies the hours and the minutes and tz is the time zone. This flag is used only if a production plan does not already exist. If the -from argument is not specified the default value is the "today +startOfDay".
69

-to Is the production plan end time. The format for the date is the same as that used for the -from argument. The -to argument is mutually exclusive with the -for and -days arguments. Is the plan extension expressed in time. The format is hhhmm, where hhh are the hours and mm are the minutes. The -for argument is mutually exclusive with -to. Is the number of days you want to create or extend the production plan for. The -days parameter is mutually exclusive with the -to parameter. If no -to, -for, or -days arguments are specified then the default production plan length is one day. Note: Assuming that the value assigned to startOfDay is 6:00 a.m. and that the date format set in the localopts file is mm/dd/yyyy, if the values set are -from 05/07/2005 and -to 07/07/2005 then the plan is created to span the time frame from 07/05/2005 at 6:00 to 07/07/2005 at 5:59 and not to 08/07/2005 at 5:59.
-for
-days n
Comments
The JnextPlan script is run using the default connection parameters defined in either localopts or useropts files. If you want to run JnextPlan using different connection parameter settings you can edit the MakePlan script and modify the invocation to the planman statement as it is described in Planman command line on page 72. The JnextPlan script is composed of the following sequence of commands and specialized scripts, each managing a specific aspect of the production plan generation: | | | conman startappserver This command is invoked to start the WebSphere Application Server if it is not already running. MakePlan This script inherits the flags and the values assigned to them from JnextPlan. Its syntax is: MakePlan [-from mm/dd/[yy]yy[hhmm[tz | timezone tzname]]] {-to mm/dd/[yy]yy[hhmm[tz | timezone tzname]] | -for [h]hhmm [-days n] | -days n} MakePlan invokes internally the planman command line. MakePlan performs the following actions: 1. Creates a new plan or extends the current plan and stores the information in an intermediate production plan containing: v All the scheduling objects (jobs, job streams, calendars, prompts, resources, workstations, domains, files, Windows users, dependencies) defined in the selected time period. v All dependencies between new instances of jobs and job streams and the jobs and job streams existing in the previous production plan. 2. Prints preproduction reports.
70

SwitchPlan This script invokes internally the stageman command. For more information refer to The stageman command on page 82. SwitchPlan performs the following actions: 1. Stops Tivoli Workload Scheduler processes. 2. Generates the new Symphony file starting from the intermediate production plan created by MakePlan. 3. Archives the old plan file with the current date and time in the schedlog directory. 4. Creates a copy of the Symphony file to distribute to the workstations. 5. Restarts Tivoli Workload Scheduler processes which distribute the copy of the Symphony file to the workstation targets for running the jobs in plan. Note: Make sure no conman start command is run while the production plan is been processed. CreatePostReports This script prints postproduction reports. UpdateStats This script invokes internally the logman command. For more information refer to The stageman command on page 82. UpdateStats performs the following actions: 1. Logs job statistics. 2. Checks the policies and if necessary extends the preproduction plan. 3. Updates the preproduction plan reporting the job stream instance states.
71
Planman command line

| | | | | The planman command line is used to manage intermediate production plans, trial plans, and forecast plans. It is also used to have information about the currently active production plan, to unlock the database entries locked by the plan management processes, and to deploy scheduling event rules. The command runs on the master domain manager. Use the following syntax when running planman: planman -U planman -V planman [connection_parameters] command where: -U -V Displays command usage information and exit. Displays the command version and exit.
connection_parameters Represents the set of parameters that rule the interaction between the product interface, planman running on the master domain manager in this case, and the WebSphere Application Server infrastructure using HTTP or HTTPS. Use this syntax to specify the settings for the connection parameters: [-host hostname] [-port port_number] [-protocol protocol_name] [-proxy proxy_name] [-proxyport proxy_port_number] [-password user_password] [-timeout timeout] [-username username] where: hostname Is the hostname of the master domain manager. port_number Is the port number used when establishing the connection with the master domain manager. protocol_name Is the protocol used during the communication. It can be HTTP with basic authentication, or HTTPS with certificate authentication. proxy_name Is the proxy hostname used in the connection with HTTP protocol. proxy_port_number Is the proxy port number used in the connection with HTTP protocol. user_password Is the password of the user that is used to run planman. | | | | | timeout Is the maximum time, expressed in seconds, the connecting Note: On Windows workstations, when you specify a password that contains double quotation marks (") or other special characters, make sure that the character is escaped. For example, if your password is tws11"tws, write it as "tws11\"tws".
72

command-line program can wait for the master domain manager response before considering the communication request as failed. username Is the username of the user running planman. Make sure this username is specified in the security file on the master domain manager with the following authorization: file name=prodsked,Symphony access=build To perform commands against the production plan. file name=trialsked access=build To perform commands against the trial and forecast plans. file name=@ access=build To perform commands against all types of plan. If any of these parameters is omitted when invoking planman, Tivoli Workload Scheduler searches for that value first in the useropts file and then in the localopts file. If a setting for the parameter is not found an error is displayed. Refer to Setting up options for using the user interfaces on page 29 for information on useropts and localopts files. command Represents the command you run against plans using the planman interface. These are the actions you can perform against plans: v Creating an intermediate production plan v Creating an intermediate plan for a plan extension on page 75 v Retrieving the production plan information on page 75 v Creating a trial plan on page 76 v Creating a trial plan of a production plan extension on page 78 v Creating a forecast plan on page 78 v Unlocking the production plan on page 80 v Resetting the production plan on page 81 | | | | You can also use planman to deploy scheduling event rules. The command is explained in: Deploying rules on page 79. Refer to the related subsections for additional details on these commands.
Creating an intermediate production plan

The planman with the crt option is invoked from within the JnextPlan command in one of these two situations: v The first time the JnextPlan command is run after having installed the product. v When generating a production plan after having reset the production plan using the ResetPlan command. The result of running this command is the creation of a new intermediate production plan, named Symnew, covering the whole time the new production plan that is being generated will cover. The following syntax is used: planman [connection_parameters] crt [-from mm/dd/[yy]yy [hhmm [tz | timezone tzname]]]
73
Creating an intermediate production plan

{-to mm/dd/[yy]yy[hhmm[tz | timezone tzname]] | -for [h]hhmm [-days n] | -days n} where: connection_parameters Defines the settings to use when establishing the connection using HTTP or HTTPS through WebSphere Application Server to the master domain manager. For more information refer to Planman command line on page 72. -from Sets the start time of the new production plan. If the -from argument is omitted, then: v The default date is today. v The default hour is the value set in the startOfDay global option using optman on the master domain manager. -to Is the new production plan end time. The format for the date is the same as that used for the -from argument. The -to argument is mutually exclusive with the -for and -days arguments. Is the plan extension expressed in time. The format is hhhmm, where hhh are the hours and mm are the minutes. The -for argument is mutually exclusive with -to argument. Is the number of days you want to create the production plan for. The -days argument is mutually exclusive with the-to argument.
-for
-days n
Notes: 1. Make sure you run the planman command from within the JnextPlan command. 2. The format used for the date depends on the value assigned to the date format variable specified in the localopts file. If no -to, -for, or -days arguments are specified then the default production plan length is one day. These are some examples of using the planman command assuming the date format set in the localopts file is mm/dd/yyyy: 1. This command creates the production plan from 03/21/2005 at 23:07 to 03/22/2005 at 23:06 in the local time zone:
planman crt from 03/21/05 2307
2. This command creates the production plan from 03/21/2005 at 09:00 to 03/21/2005 at 15:00:
planman crt from 03/21/2005 0900 for 0600
3. If today is 03/21/05 and the value set for the startOfDay variable stored in the database is 0600, this command creates the production plan from 03/21/2005 at 6:00 to 03/25/2005 at 5:59:
planman crt to 03/25/2005
4. This command creates a production plan from 03/21/2005 at 18:05 to 03/24/2005 at 23:00 in the time zone of Europe\Paris:
planman crt from 03/21/2005 1805 tz Europe\Rome to 03/24/2005 2300 tz Europe\Rome
74
Creating an intermediate plan for a plan extension
Creating an intermediate plan for a plan extension

The planman command with the ext option is invoked from within the JnextPlan command when: v JnextPlan is invoked. v A production plan, represented by the Symphony file on the master domain manager, already exists. The result of running this command is the creation of a new intermediate production plan, named Symnew, covering the extra time the new production plan that is being generated will span. The following syntax is used: planman [connection_parameters] ext {-to mm/dd/[yy]yy[hhmm[tz | timezone tzname]] | -for [h]hhmm [-days n] | -days n} where: connection_parameters Defines the settings to use when establishing the connection using HTTP or HTTPS through WebSphere Application Server to the master domain manager. For more information refer to Planman command line on page 72. -to -for Sets the end time of the extended production plan. The -to argument is mutually exclusive with the -for and -days arguments. Sets the length of the production plan extension. The format is hhhmm, where hhh are the hours and mm are the minutes. The -for argument is mutually exclusive with the -to argument. Sets the number of days you want to extend the production plan for. The -days argument is mutually exclusive with the-to argument.
-days n
Notes: 1. Make sure you run the planman command from within the JnextPlan command. 2. The format used for the date depends on the value assigned to the date format variable specified in the localopts file. 3. When the production plan is extended the numbers associated to prompts already present in the plan are modified. If no -to, -for, or -days arguments are specified then the production plan is extended by one day.
Retrieving the production plan information

The following syntax is used to show information about the current production plan: planman [connection_parameters] showinfo where:
75
Retrieving the production plan information

connection_parameters Defines the settings to use when establishing the connection using HTTP or HTTPS through WebSphere Application Server to the master domain manager. For more information refer to Planman command line on page 72. Note: You can install the Tivoli Workload Scheduler Command Line Client feature on fault-tolerant agents and systems outside the Tivoli Workload Scheduler network to issue from those systems the planman showinfo command. The output of this command shows: v The installation path. v The start time of the production plan. v The end time of the production plan. v The duration of the production plan, after the last plan extension, if extended. v The date and time of the last plan update, done either using JnextPlan or planman. v The end time of the preproduction plan. v The start time of the first not completed job stream instance. v The run number, that is the total number of times the plan was generated. v The confirm run number, that is the number of times the plan was successfully generated. The start and end times of the production and preproduction plans are displayed using the format specified in the date format variable set in the localopts file and the time zone of the local machine. A sample output of this command is the following:
C:\TWS\maestro830>bin\planman showinfo TWS for WINDOWS/PLANMAN 8.3 (1.0) Licensed Materials Property of IBM 5698-WKB (C) Copyright IBM Corp 1998, 2006 US Government User Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Installed for user STEFANO03\maestro830. Locale LANG set to the following: "en" Plan Creation Start Time: 01/03/2006 06:00 TZ CST Production Plan End time: 01/05/2006 05:59 TZ CST Production Plan Time Extention: 048:00 Plan Last Update: 01/03/2006 12:24 TZ CST Pre-Production Plan End Time: 01/19/2006 06:00 TZ CST Start Time of first incomplete JobStream Instance: 01/03/2006 23:00 TZ CST Run Number: 5 Confirm Run Number: 5 C:\TWS\maestro830>
Creating a trial plan

The following syntax is used to create a trial plan: planman [connection_parameters] crttrial file_name [ -from mm/dd/[yy]yy [hhmm [tz | timezone tzname]]] {-to mm/dd/[yy]yy[hhmm[tz | timezone tzname]] |
76
Creating a trial plan

-for [h]hhmm [-days n] | -days n} where: connection_parameters Defines the settings to use when establishing the connection using HTTP or HTTPS through WebSphere Application Server to the master domain manager. For more information refer to Planman command line on page 72. file_name Assigns a name to the file to be created under the directory TWS_home/schedTrial and that contains the trial plan. The file name of the file containing the trial plan is Tfilename. This means that if the value assigned to file_name is myfile then the file name that contains the generated trial plan is Tmyfile. Sets the start time of the trial plan. If the -from argument is omitted, then: v The default date is today. v The default hour is the value set in the startOfDay global option using optman on the master domain manager. -to -for Sets the end time of the trial plan. The -to argument is mutually exclusive with the -for and -days arguments. Sets the length of the trial plan. The format is hhhmm, where hhh are the hours and mm are the minutes. The -for argument is mutually exclusive with the -to argument. Sets the number of days you want the trial plan to last for. The -days argument is mutually exclusive with the -to argument.
-from
-days n
Note: The format used for the date depends on the value assigned to the date format variable specified in the localopts file. If no -to, -for, or -days arguments are specified then the default trial plan length is one day.
77
Creating a trial plan of a production plan extension
Creating a trial plan of a production plan extension

The following syntax is used to create a trial plan with the extension of the current production plan: planman [connection_parameters] exttrial file_name {-to mm/dd/[yy]yy[hhmm[tz | timezone tzname]] | -for [h]hhmm [-days n] | -days n} where: connection_parameters Defines the settings to use when establishing the connection using HTTP or HTTPS through WebSphere Application Server to the master domain manager. For more information refer to Planman command line on page 72. file_name Assigns a name to the file to be created under the directory TWS_home/schedTrial and that contains the trial plan. The file name of the file containing the trial plan is Tfilename. This means that if the value assigned to file_name is myfile then the file name that contains the generated trial plan is Tmyfile. Sets the end time of the trial plan containing the production plan extension. The -to argument is mutually exclusive with the -for and -days arguments. Sets the length of the trial plan containing the production plan extension. The format is hhhmm, where hhh are the hours and mm are the minutes. The -for argument is mutually exclusive with the -to argument. Sets the number of days you want the trial plan containing the production plan extension to last for. The -days argument is mutually exclusive with the -to argument.
-to
-for
-days n
Note: The format used for the date depends on the value assigned to the date format variable specified in the localopts file. If no -to, -for, or -days arguments are specified then the default production plan extension contained in the trial plan is one day.
Creating a forecast plan

The following syntax is used to create a forecast plan: planman [connection_parameters] crtfc file_name [ -from mm/dd/[yy]yy [hhmm [tz | timezone tzname]]] {-to mm/dd/[yy]yy[hhmm[tz | timezone tzname]] | -for [h]hhmm [-days n] | -days n}
78
Creating a forecast plan

where: connection_parameters Defines the settings to use when establishing the connection using HTTP or HTTPS through WebSphere Application Server to the master domain manager. For more information refer to Planman command line on page 72. file_name Assigns a name to the file to be created under the directory TWS_home/schedForecast and that contains the forecast plan. The name of the file containing the forecast plan is Ffilename. This means that if the value assigned to file_name is myfile then the file name that contains the generated forecast plan is Fmyfile. The maximum length of file_name can be 148 characters. -from Sets the start time of the forecast plan. If the -from argument is omitted, then: v The default date is today. v The default hour is the value set in the startOfDay global option using optman on the master domain manager. -to -for Sets the end time of the forecast plan. The -to argument is mutually exclusive with the -for and -days arguments. Sets the length of the forecast plan. The format is hhhmm, where hhh are the hours and mm are the minutes. The -for argument is mutually exclusive with the -to argument. Sets the number of days you want the forecast plan to last for. The -days argument is mutually exclusive with the -to argument.
-days n
Note: The format used for the date depends on the value assigned to the date format variable specified in the localopts file. If no -to, -for, or -days arguments are specified then the default forecast plan length is one day. | | | | | | | | | | | | | | | | | |
Deploying rules
The planman deploy command is used in event management. You can use it to manually deploy all rules that are not in draft state (the isDraft property is set to NO in their definition). The command operates as follows: 1. Selects all event rule definitions not in draft state from the Tivoli Workload Scheduler database. 2. Builds event rule configuration files. 3. Deploys the configuration files to the monitoring engines running on the Tivoli Workload Scheduler agents. The new configuration files update the event rules running on each monitoring engine in terms of: v New rules v Changed rules v Rules deleted or set back to draft state You can use this command in addition to, or in replacement of, the deploymentFrequency (df) optman configuration option, which periodically checks event rule definitions for changes to deploy (see the Planning and Installation guide for details on this option).
79
Deploying rules
| | | | | | | | | | | | | | | | | | | | | | | The changes applied to the event rule definitions in the database become effective only after deployment has taken place. The command syntax is: planman [connection_parameters] deploy [-scratch] where: connection_parameters Defines the settings to use when establishing the connection using HTTP or HTTPS through WebSphere Application Server to the master domain manager. For more information refer to Planman command line on page 72. -scratch Without this option, the command affects only the rules that have been added, changed, deleted, or set back to draft state . With this option, the command deploys all the non-draft rules existing in the database, including the ones that are already in deployment and have not changed. Use of this option results in a complete reset of the event processor and should be used with caution. The command may cause the loss of any rule instances in progress at the time you issue it. The typical case is a sequential rule that has been triggered and is waiting for additional events to take place: if you use the option at this time, the event rule environment is reset and the tracked events are lost. To run this command, you need build access on the prodsked file.
Unlocking the production plan

When Tivoli Workload Scheduler starts to create the production plan, it locks the definitions of scheduling objects in the database and then unlocks them either when the creation of the production plan is finished or if an error condition occurs. The lock is applied to prevent object definitions from being modified when the production plan in generated or extended. If the processing ends abnormally the database entries might remain locked. Only users with build access on the prodsked file object type specified in the security file on the master domain manager are allowed to unlock the database. The command used to perform this action is: planman [connection_parameters] unlock where: connection_parameters Defines the settings to use when establishing the connection using HTTP or HTTPS through WebSphere Application Server to the master domain manager. For more information refer to Planman command line on page 72. Note: You can install the Tivoli Workload Scheduler Command Line Client feature on fault-tolerant agents and systems outside the Tivoli Workload Scheduler network to issue from those systems the planman unlock command.
80
Resetting the production plan
Resetting the production plan

The following script is used to either reset or scratch the production plan: ResetPlan [connection_parameters] [-scratch] where: connection_parameters Defines the settings to use when establishing the connection using HTTP or HTTPS through WebSphere Application Server to the master domain manager. For more information refer to Planman command line on page 72. The difference between resetting and scratching the production plan is the following: v If you reset the production plan, the preproduction plan is kept, it is updated with job statistics, and it is used later to generate a new production plan. This means that when you create a new production plan, it will contain all job stream instances which were not in COMPLETE state when you run the ResetPlan. The steps performed by the product when resetting the production plan are the following: 1. All Tivoli Workload Scheduler processes are stopped on the master domain manager. 2. The current Symphony file is archived. 3. The job statistics are updated. v If you scratch the production plan, the preproduction plan is scratched too. The preproduction plan will be created again based on the modeling information stored in the database when you later generate a new production plan. This means that the new production plan will contain all job stream instances scheduled to run in the time frame covered by the plan regardless of whether or not they were already in COMPLETE state when the plan was scratched. The steps performed by the product when scratching the production plan are the following: 1. All Tivoli Workload Scheduler processes are stopped on the master domain manager. 2. The current Symphony file is archived. 3. The job statistics are updated. 4. The preproduction plan is scratched. Note: If you use the -scratch option, make sure you run dbreorg and dbrunstats before the JnextPlan script.
81
stageman
The stageman command

The stageman command carries forward uncompleted job streams, archives the old production plan, and installs the new production plan. A copy of Symphony, is sent to domain managers and agents as part of the initialization process for the new production plan. When running JnextPlan, stageman is invoked from within the SwitchPlan script. You must have build access to the Symphony file to run stageman.
Syntax
stageman -v | -U stageman [-carryforward{yes|no|all}] [-log log_file| -nolog] [symnew]
Arguments
-v -U Displays the command version and exits. Displays command usage information and exits.
-carryforward Defines how uncompleted job streams are managed when moving to a new production plan. The available settings are: no yes all Does not carry forward any job streams. Carries forward only the uncompleted job streams whose definition contains the keyword carryforward. Carries forward all uncompleted job streams, regardless whether or not contain the keyword carryforward in the job stream definition.
If you omit this keyword, by default it is set to the value specified globally using optman for the enCarryForward option. Refer to Understanding carry forward options on page 61 to have information on the resulting carry forward setting when both the enCarryForward global option and the -carryforward keywords are set. -log Archives the old production plan in the directory TWS_home/schedlog with file name log_file. The archived production plans can then be listed and selected using the commands listsym on page 297 and setsym on page 311. If neither -log nor -nolog keywords are specified, Tivoli Workload Scheduler archives the old production plan using the following naming convention:
Myyyymmddhhtt
where yyyymmddhhtt corresponds to the year, month, day, hour, minutes the old production plan is archived. If you generate the production plan using JnextPlan you can customize this naming convention in the SwitchPlan script. Note: Be sure to monitor the disk space in the schedlog directory and remove older log files on a regular basis.
82
stageman
-nolog Does not archive the old production plan. symnew The name assigned to the intermediate production plan file created by planman. If not specified, stageman uses the file name Symnew.
Comments
To allow carry forward procedures to work properly in a network, the master domain managers production plan file, Symphony, must be updated with the latest job stream status from its agents and subordinate domain managers. Run the following command:
conman "link @"
before running stageman. This command links any unlinked workstations so that messages about job processing status queued in the Mailbox.msg file are sent back to the master domain manager to update the Symphony file. Note: In UNIX only, stageman also determines which executable files associated to jobs submitted using the at and batch utility commands can be deleted when Tivoli Workload Scheduler is started for the new production period. These jobs are not carried forward.
Examples
Carry forward all uncompleted job streams (regardless of the status of the Carry Forward option), log the old Symphony file, and create the new Symphony file:
DATE=datecalc today pic YYYYMMDDHHTT stageman -carryforward all -log schedlog/M$DATE
Carry forward uncompleted job streams as defined by the carryforward global option, do not log the old Symphony file, and create an intermediate production plan named mysym:
stageman -nolog mysym
83
Managing concurrent accesses to Symphony
Managing concurrent accesses to the Symphony file

This section contains two sample scenarios describing how Tivoli Workload Scheduler manages possible concurrent accesses to the Symphony file when running stageman.
Scenario 1: Access to Symphony file locked by other Tivoli Workload Scheduler processes
If Tivoli Workload Scheduler processes are still active and accessing the Symphony file when stageman is run, the following message is displayed:
Unable to get exclusive access to Symphony. Shutdown batchman and mailman.
To continue, stop Tivoli Workload Scheduler and rerun stageman. If stageman aborts for any reason, you must rerun both planman and stageman.
Scenario 2: Access to Symphony file locked by stageman

If you try to access the plan using the command-line interface while the Symphony is being switched, you get the following message:
Current Symphony file is old. Switching to new Symphony. Schedule mm/dd/yyyy (nnnn) on cpu, Symphony switched.
Managing follows dependencies using carry forward prompt

To retain continuity when carrying forward job streams, stageman generates prompts for each job stream that is carried forwarded and has a follows dependency on another job stream which is not carried forward. These prompts are issued after the new processing period begins, when Tivoli Workload Scheduler checks to see if the job or job stream is ready to launch, and are replied to as standard prompts. The following is an example of a carry forward prompt:
INACT 1(SYS2#SKED2[(0600 01/11/06),(0AAAAAAAAAAAAA2Y)]) follows SYS1#SKED1, satisfied?
This prompt indicates that a job stream, which is carried forward from the previous production plan, (SYS2#SKED2[(0600 01/11/06),(0AAAAAAAAAAAAA2Y)]), has a follows dependency from a job stream named SYS1#SKED1 which was not carried forward. For information on the syntax used to indicate the carried forward job stream refer to Selecting job streams in commands on page 257. The state of the prompt, INACT in this case, defines the state of the corresponding follows dependency. The possible states are: INACT The prompt has not been issued and the dependency is not satisfied. ASKED The prompt has been issued, and is awaiting a reply. The dependency is not satisfied. NO Either a no reply was received, or it was determined before carry forward occurred that the followed job stream SKED3 had not completed successfully. The dependency is not satisfied. Either a yes reply was received, or it was determined before carry forward occurred that the followed job stream SKED3 had completed successfully. The dependency is satisfied.
YES
84
logman
The logman command

The logman command logs job statistics from a production plan log file.
Syntax
logman -v|-u logman [connection_parameters] [-prod symphony-file] [-minmax setting] [-smooth weighting]
Arguments
-u -v Displays command usage information and exits. Displays the command version and exits.
connection_parameters Represents the set of parameters that control the interaction between the product interface, logman running on the master domain manager in this case, and the WebSphere Application Server infrastructure using HTTP or HTTPS. Use this syntax to specify the settings for the connection parameters: [-host hostname] [-port port_number] [-protocol protocol_name] [-proxy proxy_name] [-proxyport proxy_port_number] [-password user_password] [-timeout timeout] [-username username] where: hostname Is the hostname of the master domain manager. port_number Is the port number used when establishing the connection with the master domain manager. protocol_name Is the protocol used during the communication. It can be HTTP with basic authentication, or HTTPS with certificate authentication. proxy_name Is the proxy hostname used in the connection. proxy_port_number Is the proxy port number used in the connection. user_password Is the password of the user that is used to run logman. | | | | | timeout Is the maximum time, expressed in seconds, the connecting
Note: On Windows workstations, when you specify a password that contains double quotation marks (") or other special characters, make sure that the character is escaped. For example, if your password is tws11"tws, write it as "tws11\"tws".
85
logman
command-line program can wait for the master domain manager response before considering the communication request as failed. username Is the username of the user running logman. If any of these parameters is omitted when invoking logman, Tivoli Workload Scheduler searches for a value first in the useropts file and then in the localopts file. If a setting for the parameter is not found an error is displayed. Refer to Setting up options for using the user interfaces on page 29 for information on useropts and localopts files. -prod Updates the preproduction plan with the information on the job streams in COMPLETE state in production. By doing so the preproduction plan is kept up-to-date with the latest processing information. This avoids the possibility of the new production plan running again, job streams already completed in the previous production period.
-minmax setting Defines how the minimum and maximum job run times are logged and reported. The available settings are: elapsed cpu Base the minimum and maximum run times on elapsed time. Base the minimum and maximum run times on CPU time.
This setting is used when the logman command is run from the command line and not by the JnextPlan script. When the logman command is run by JnextPlan, the setting used is the one specified in the logmanMinMaxPolicy global option. -smooth weighting Uses a weighting factor that favors the most recent job run when calculating the normal (average) run time for a job. This is expressed as a percentage. For example, -smooth 40 applies a weighting factor of 40% to the most recent job run, and 60% to the existing average. The default is 0%. This setting is used when the logman command is run from the command line and not by the JnextPlan script. When the logman command is run by JnextPlan, the setting used is the one specified in the logmanSmoothPolicy global option. symphony-file The name of an archived symphony file from which job statistics are extracted.
Comments
Jobs that have already been logged, cannot be logged again. Attempting to do so generates a 0 jobs logged error message.
Examples
Log job statistics from the log file M199903170935:
logman schedlog/M199903170935
86
Starting production plan processing
Starting production plan processing

To start a production cycle, follow these steps: 1. Log in as TWS_user on the master domain manager. 2. At a command prompt, run the script command . ./TWS_home/tws_env.sh in UNIX or TWS_home\tws_env.cmd in Windows to set up the environment, then run the JnextPlan job by entering, for example on a UNIX workstation, the following command:
JnextPlan.sh -from 05/03/06 0400 -to 06/06/06
This creates a new production plan that starts on the third of May 2006 at 4:00 a.m. and stops on the sixth of June 2006 at 3:59 a.m. The processing day will start at the time specified on the master domain manager in the variable startOfDay. 3. When the JnextPlan job completes, check the status of Tivoli Workload Scheduler:
conman status
If the Tivoli Workload Scheduler started correctly, the status is

Batchman=LIVES
If mailman is still running a process on the remote workstation, you might see that the remote workstation does not initialize immediately. This happens because the workstation needs to complete any ongoing activities involving the mailman process before re-initializing. After the interval defined in the mm retry link parameter set in the TWS_home/localopts configuration file elapses, the domain manager tries again to initialize the workstation. As soon as the ongoing activities complete, the activities for the next day are initialized. For information about the localopts configuration file, refer to IBM Tivoli Workload Scheduler: Planning and Installation Guide. 4. Increase the limit to allow jobs to run. The default job limit after installation is zero. This means no jobs will run.
conman "limit;10"
Automating production plan processing

If you want to extend your production plan at a fixed time interval, for example every week, you have the option to automate the extension. This section explains how you can do this. Tivoli Workload Scheduler includes a sample job stream named final that helps you automate plan management. A copy of this job stream is in the Sfinal file in the TWS_home/config/Sfinal directory. A copy of the job script is in the TWS_home/JnextPlan directory. You can use either this Sfinal file or create and customize a new one. The final job stream runs the sequence of script files described in JnextPlan to generate the new production plan. See Generating a production plan - JnextPlan on page 69 for reference. By default, the final job stream is set to run once a day. You can modify the time it runs by modifying two settings in the final job stream definition. These are the details about the two steps you need to follow to do this, for example, to make the final job stream run every three days:
87
Automating production plan processing

v Modify the run cycle by setting inside the final job stream definition to schedule the job stream to run every three days. v In the statement that invokes MakePlan inside the final job stream, set the production plan to last for three days by specifying -for 72. Then you need to add the final job stream to the database by performing the following steps: 1. Log in as TWS_user. 2. Run the tws_env script to set the Tivoli Workload Scheduler environment as follows: v UNIX: on C shells launch . ./TWS_home/tws_env.csh v UNIX: on Korn shells launch . ./TWS_home/tws_env.sh v From a Windows command line: launch TWS_home\tws_env.cmd where TWS_home represents the product installation directory. 3. Run the composer command. 4. Add the final job stream definition to the database by running the following command:
composer add Sfinal
If you did not use the Sfinal file provided with the product but you created a new one, use its name in place of Sfinal. 5. Start the production cycle by running the JnextPlan script. In this way the final job stream will be included in the current production plan. Note: Even if you decided to automate the production plan extension you can still run JnextPlan at any time.
88
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Chapter 6. Running event-driven workload automation

Event-driven workload automation adds the capability to perform on-demand workload automation in addition to plan-based job scheduling. It provides the capability to define rules that can trigger on-demand workload automation. The object of event-driven workload automation in Tivoli Workload Scheduler is to carry out a predefined set of actions in response to events that occur on nodes running Tivoli Workload Scheduler (but also on non-Tivoli Workload Scheduler ones, when you use the sendevt command line). This implies the capability to submit workload and run commands on the fly, notify users via e-mail, or send messages to Tivoli Enterprise Console. The main tasks of event-driven workload automation are: v Trigger the execution of batch jobs and job streams based on the reception or combination of real time events. v Reply to prompts v Notify users when anomalous conditions occur in the Tivoli Workload Scheduler scheduling environment or batch scheduling activity. v Invoke an external product when a particular event condition occurs. Event-driven workload automation is based upon the concept of event rule. In Tivoli Workload Scheduler an event rule is a scheduling object that includes the following items: v Events v Event-correlating conditions v Actions When you define an event rule, you specify one or more events, a correlation rule, and the one or more actions that are triggered by those events. Moreover, you can specify validity dates, a daily time interval of activity, and a common time zone for all the time restrictions that are set. The events that Tivoli Workload Scheduler can detect for action triggering can be: Internal events They are events involving Tivoli Workload Scheduler internal application status and changes in the status of Tivoli Workload Scheduler objects. Events of this category can be job or job stream status changes, critical jobs or job streams being late or canceled, and workstation status changes. External events They are events not directly involving Tivoli Workload Scheduler that may nonetheless impact workload submission. Events of this category can be messages written in log files, events sent by third party applications, or a file being created, updated, or deleted. Within a rule two or more events can be correlated through correlation attributes such as a common workstation or job. The correlation attributes provide a way to direct the rule to create a separate rule (or copy of itself) for each group of events that share common characteristics. Typically, each active rule has one copy that is running in the event processing server. However, sometimes the same rule is needed for different groups of events, which are often related to different groups of
89
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
resources. Using one or more correlation attributes is a method for directing a rule to create a separate rule copy for each group of events with common characteristics. The actions that Tivoli Workload Scheduler can run when it detects any of these events can be: Operational actions They are actions that cause the change in the status of scheduling objects. Actions of this category are submitting a job, job stream, or command, or replying to a prompt. Notification actions They are actions that have no impact on the status of scheduling objects. Actions belonging to this category are sending an e-mail, logging the event in an internal auditing database, forwarding the event to Tivoli Enterprise Console, or running a non-Tivoli Workload Scheduler command. This classification of events and actions is conceptual. It has no impact on how they are handled by the event-driving mechanism. Table 11 lists some simple scenarios involving the use of event rules. The corresponding XML coding is shown in Table 15 on page 98.
Table 11. Simple event rule scenarios Scenario 1: Send e-mail notification 1. The administrator defines the following event rule: v When any of the job123@ jobs terminates in error, send an e-mail to operator john.smith@mycorp.com. The subject of the e-mail includes the names of the job instance and of the associated workstation. The event rule is valid from December 1st to December 31st in the 12:00-16:00 EST time window. 2. The administrator saves the rule as non-draft in the database and it is readily deployed by Tivoli Workload Scheduler. 3. The scheduler starts monitoring the jobs and every time one of them ends in error, John Smith is sent an e-mail so that he can check the job and take corrective action. Scenario 2: Monitor that workstation links back 1. The administrator defines the following event rule: v If workstation CPU1 becomes unlinked and does not link back within 10 minutes, send a notification e-mail to chuck.derry@mycorp.com. 2. The administrator saves the rule as non-draft in the database and it is readily deployed by Tivoli Workload Scheduler. 3. The scheduler starts monitoring CPU1. If the workstation status becomes unlinked, Tivoli Workload Scheduler starts the 10 minute timeout. If the CPU1 linked event is not received within 10 minutes, the scheduler sends the notification e-mail to Chuck Derry. 4. Rick Jones receives the e-mail, queries the actions/rules that were triggered in the last 10 minutes, and from there navigates to the CPU1 instance and runs a first problem analysis.
90
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 11. Simple event rule scenarios (continued) Scenario 3: Submit job stream when FTP has completed 1. The administrator defines the following event rule: v When file daytransac* is created in the SFoperation directory in workstation system1, and modifications to the file have terminated, submit the calmonthlyrev job stream. The event rule is valid year-round in the 18:00-22:00 EST time window. 2. The administrator saves the rule as non-draft in the database and it is readily deployed by Tivoli Workload Scheduler. 3. The scheduler starts monitoring the SFoperation directory. As soon as file daytransac* is created and is no longer in use, it submits job stream calmonthlyrev. 4. The operator can check the logs to find if the event rule or the job stream were run. Scenario 4: Start long duration jobs based on timeout 1. The administrator defines the following event rule: v When the job-x=exec event and the job-x=succ/abend event are received in 5 minutes, the scheduler should reply Yes to prompt-1 and start the jobstream-z job stream, otherwise it should send an e-mail to twsoper@mycompany.com alerting that the job is late. 2. The administrator saves the event rule in draft status. After a few days he edits the rule, changes the e-mail recipient and saves it as non-draft. The rule is deployed. 3. Every time the status of job-x becomes exec, Tivoli Workload Scheduler starts the 5 minutes timeout. If the internal state of job-x does not change to succ or abend within 5 minutes and the corresponding event is not received, Tivoli Workload Scheduler sends the e-mail, otherwise it replies Yes to the prompt and submits jobstream-z. Scenario 5: Integration with SAP R/3 (in combination with Tivoli Workload Scheduler for Applications) 1. The administrator defines the following event rule: v When an event called ID3965 is generated on SAP R/3 server Billing, Tivoli Workload Scheduler must: a. Run the command: /usr/apps/helpDesk openTicket text Processing error $parameter on SAP system $wsname to open a service desk ticket b. Send an event to Tivoli Enterprise Console. 2. The administrator saves the rule as non-draft and it is readily deployed. 3. Tivoli Workload Scheduler starts monitoring the status of SAP R/3 events activated on the Billing system. When the ID3965 event is detected, Tivoli Workload Scheduler runs the specified help desk command and sends an event to TEC. 4. After some time, the administrator sets the event rule in draft status. The rule is automatically deactivated. It can be deployed again when needed.
91
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
The event rule management process

Event-driven workload automation is an ongoing process and can be reduced to the following steps: 1. An event rule definition is created or modified with the Tivoli Dynamic Workload Console or with the composer command line and saved in the objects database. Rule definitions can be saved as draft or non-draft. 2. All new and modified non-draft rules saved in the database are periodically (by default every five minutes) found, built, and deployed by an internal process named rule builder. At this time they become active. Meanwhile, an event processing server, which is normally located in the master domain manager, receives all events from the agents and processes them. 3. The updated monitoring configurations are downloaded to the Tivoli Workload Scheduler agents and activated. Each Tivoli Workload Scheduler agent runs a component named monman that manages two services named monitoring engine and ssmagent that are to catch the events occurring on the agent and perform a preliminary filtering action on them. 4. Each monman detects and sends its events to the event processing server. 5. The event processing server receives the events and checks if they match any deployed event rule. 6. If an event rule is matched, the event processing server calls an actions helper to carry out the actions. 7. The action helper creates an event rule instance and logs the outcome of the action in the database. 8. The administrator or the operator reviews the status of event rule instances and actions in the database and logs. The event-driven workload automation feature is automatically installed with the product. You can at any time change the value of the enEventDrivenWorkloadAutomation global option if you do not want to use it in your Tivoli Workload Scheduler network. Event-driven workload automation is based on a number of services, subsystems, and internal mechanisms. The following ones are significant because they can be managed: monman Is installed on every Tivoli Workload Scheduler agent where it checks for all local events. All detected events are forwarded to the event processing server. The following conman commands are available to manage monman:
Table 12. conman commands for managing monitoring engines Command deployconf Purpose Updates the monitoring configuration file for the event monitoring engine on an agent. It is an optional command since the configuration is normally deployed automatically. Returns the list of event rules defined for the monitor running on an agent. This command can be used remotely to get the information of the configuration file in another agent of the network Starts monman on an agent. Can be issued from a different agent.
showcpus getmon
startmon
92
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 12. conman commands for managing monitoring engines (continued) Command stopmon Purpose Stops monman on an agent. Can be issued from a different agent.
monman starts up automatically each time a new Symphony is activated (on Windows also when Tivoli Workload Scheduler is restarted). This is determined by the autostart monman local option that is set to yes by default (and that you can disable if you do not want to monitor events on a particular agent). Following each rule deployment cycle, updated monitoring configurations are automatically distributed to the agents hosting rules that have been changed since the last deployment. Note that there might be some transitory situations while deployment is under course. For example, if a rule is pending deactivation, the agents might be sending events in the time fraction that the new configuration files have not been deployed yet, but the event processor already discards them. Event processing server Can be installed on the master domain manager, the backup master, or on any fault-tolerant agent installed as a backup master. It runs in the embedded application server. It can be active on only one node in the network. It builds the rules, creates configuration files for the agents, and notifies the agents to download the new configurations. It receives and correlates the events sent by the monitoring engines and runs the actions. The following conman commands are available to manage the event processing server:
Table 13. conman commands for managing the event processing server Command starteventprocessor stopeventprocessor switcheventprocessor Purpose Starts the event processing server Stops the event processing server Switches the event processing server from the master domain manager to the backup master or vice versa
The event processing server starts up automatically with the master domain manager.
Using the involved interfaces and commands

Running and managing event-driven workload automation calls for the following tasks: v Edit configuration settings v Model event rules v Manually deploy or undeploy event rules v Manage monitoring and event processing devices v Monitor and manage event rule instances You must be ready to utilize several Tivoli Workload Scheduler interfaces and commands to do them. Table 14 summarizes the ones you need:
93
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 14. Interfaces and commands for managing event-driven workload automation Interface or command optman Use to... Change the default values of global options associated with event management. Global options are used to configure: v The frequency with which rule definitions are checked for updates (deploymentFrequency). Modified definitions are deployed in the Tivoli Workload Scheduler domain v The EIF port number where the event processing server receives events (eventProcessorEIFPort). v Management of the cleanup policies of rule instance, action run, and message log data (logCleanupFrequency). v SMTP server properties if you deploy rules implementing actions that send e-mails via an SMTP server (smtpServerName, smtpServerPort, smtpUseAuthentication, smtpUserName, smtpUserPassword, smtpUseSSL, smtpUseTLS ). v Tivoli Enterprise Console server properties if you deploy rules implementing actions that forward events to TEC (TECServerName, TECServerPort). v The possibility to disable the event rule management mechanism (enEventDrivenWorkloadAutomation) which is installed by default with the product. See the Planning and Installation guide for a list of global options. composer Run modeling and management tasks of event rule definitions like add, create, delete, display, extract, list, lock, modify, new, print, unlock, validate. Event rules are defined in XML. Query the Tivoli Workload Scheduler relational database for: v event rule definitions filtered by: rule, event, and action properties jobs and job streams involved with the rule action v event rule instances, actions run, and message log records See Event rule definition on page 178 to learn how to define event rules. See Chapter 8, Managing objects in the database - composer, on page 189 for command reference.
94
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 14. Interfaces and commands for managing event-driven workload automation (continued) Interface or command Tivoli Dynamic Workload Console Use to... Have a graphical user interface to: v Model and manage event rule definitions (browse, create, delete, modify, query, unlock) v Query the Tivoli Workload Scheduler relational database for: event rule definitions filtered by: - rule, event, and action properties - jobs and job streams involved with the rule action event rule instances, actions run, and message log records v Manage the event processing server and monitoring engines, as described in tables 12 and 13 See the Tivoli Dynamic Workload Console online documentation. conman Manage the monitoring devices, namely the event processing server and monitoring engines, as described in tables 12 and 13. See Chapter 9, Managing objects in the plan - conman, on page 243 for command reference. utility commands Create custom event definitions and manually send custom events to the event processing server. See evtdef on page 385 and sendevent on page 405 for details on these commands. Manually deploy new and changed rules. See Deploying rules on page 79 for details. Security file Set security authorizations to manage event rules, events, actions, and their instances. See Configuring the security file on page 36 for reference.
planman
Defining event rules

When you define an event rule, you specify one or more events, a correlation rule, and one or more actions. To define event rules you can use: v The composer command line v The Tivoli Dynamic Workload Console v A set of APIs described in a separate document In composer, you edit the rules with an XML editor of your choice (preferable but not mandatory) since event rule definitions are made using XML syntax. The explanation of how you use composer to define event rules is in Event rule definition on page 178, while the explanation of how you use the Tivoli Dynamic Workload Console can be found in its online help. Event rule definitions are saved in the Tivoli Workload Scheduler database like all other scheduling objects. You can save them as: Draft The rule is saved in the database but is not ready yet to be deployed and activated.
95
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
This state is determined by the isDraft=yes attribute. Not draft This rule is being deployed or is ready to be deployed in the scheduling environment. This state is determined by the isDraft=no attribute. Non-draft rules are ready to be activated. The rule builder calculates the status of each rule. The status can be: v active v not active v update pending v update error v activation pending v activation error v deactivation pending v deactivation error The scheduler periodically (every five minutes or in accordance with a time set in the deploymentFrequency global configuration option) scans the database for non-draft rules and builds rule configuration files for deployment. The new monitoring configurations are downloaded to the agents (each agent gets its own configuration file containing strictly the rules it is to run) only if there have been changes since the previous configuration files. As an additional feature, a planman deploy command is available to deploy rules manually at any time. You can deploy and undeploy rules as you need by setting the isDraft attribute to no or to yes with composer or with the Tivoli Dynamic Workload Console. Based on their characteristics, rules are classified as: filter The rule is activated upon the detection of a single specific event.
sequence The rule is activated when an ordered group of events is detected or fails to complete within a specific time interval. set The rule is activated when an unordered group of events is detected or fails to complete within a specific time interval.
Filter rules are based on the detection of one event such as a job being late, a Tivoli Workload Scheduler workstation going down, a file being modified, a job stream completing its run successfully, and so on. Set and sequence rules are based on the detection of more events. Optionally, they can be based on a time out condition. A rule times out when the first event(s) in a sequence or part of the events in a set are received, but not all the events are received within a specified time interval counted from when the first event was received. Rule definitions may include attributes that specify a validity period and an activity time window within each day of validity. If you do not specify these attributes, the rule is active perpetually at all times once it is deployed and until it is changed back to draft status or deleted from the database.
96
| | | | | | | | | | | | | | | | | | | | | | | | | |
You can use variable substitution. This means that when you define action parameters, you can use attributes of occurrences of events that trigger the event rule in either of these two forms: v ${event.property} Replaces the value as is. This is useful to pass the information to an action that works programmatically with that information, for example the schedTime of a job stream. v %{event.property} Replaces the value formatted in human readable format. This is useful to pass the information to an action that forwards that information to a user, for example to format the schedTime of a job stream in the body of an e-mail. Where: event Is the name you set for the triggering eventCondition.
property Is the attributeFilter name in the filtering predicate of the triggering event condition. The value taken by the attribute filter when the rule is triggered is replaced as a parameter value in the action definition before it is performed. Note that you can use variable substitution also if no attributeFilter was specified for an attribute and also if the attribute is read-only. You can see the use of variable substitution in some of the following sample definitions, where attribute filter values are replaced in e-mail subject and body matters.
Event rule examples

The following tables describe the event rule definitions that apply to the scenarios described in table 11.
97
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 15. Event rule definition for scenario1 When any of the job123@ jobs terminates in error, send an e-mail to operator john.smith@mycorp.com. The subject of the e-mail includes the names of the job instance and of the associated workstation. The event rule is valid from December 1st to December 31st in the 12:00-16:00 EST time window. <?xml version="1.0" encoding="UTF-8"?> <eventRuleSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules" xsi:schemaLocation="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules EventRules.xsd"> <eventRule name="scenario1_rule" ruleType="filter" isDraft="no"> <description>This is the definition for scenario1</description> <timeZone>America/Indianapolis</timeZone> <validity from="2007-12-01" to="2007-12-31" /> <activeTime start="12:00:00" end="16:00:00" /> <eventCondition name="event1" eventProvider="TWSObjectsMonitor" eventType="JobStatusChanged"> <filteringPredicate> <attributeFilter name="JobName" operator="eq"> <value>job123@</value> </attributeFilter> <attributeFilter name="Status" operator="eq"> <value>Error</value> </attributeFilter> </filteringPredicate> </eventCondition> <action actionProvider="MailSender" actionType="SendMail" responseType="onDetection"> <description>Send email to John Smith including names of job and associated workstation </description> <parameter name="To"> <value>john.smith@mycorp.com</value> </parameter> <parameter name="Subject"> <value>Job ${event1.JobName} on agent ${event1.Workstation} ended in error</value> </parameter> </action> </eventRule> </eventRuleSet>
98
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 16. Event rule definition for scenario2 If workstation CPU1 becomes unlinked and does not link back within 10 minutes, send a notification e-mail to rick.jones@mycorp.com. <?xml version="1.0" encoding="UTF-8"?> <eventRuleSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules" xsi:schemaLocation="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules EventRules.xsd"> <eventRule name="scenario2_rule" ruleType="filter" isDraft="no"> <description>This is the definition for scenario2</description> <timeZone>America/Anchorage</timeZone> <timeInterval amount="10" unit="minutes" /> <eventCondition name="WSevent" eventProvider="TWSObjectsMonitor" eventType="ChildWorkstationLinkChanged"> <filteringPredicate> <attributeFilter name="Workstation" operator="eq"> <value>CPU1</value> </attributeFilter> <attributeFilter name="LinkStatus" operator="eq"> <value>Unlinked</value> </attributeFilter> </filteringPredicate> </eventCondition> <action actionProvider="MailSender" actionType="SendMail" responseType="onTimeOut"> <description>Send email to Chuck Derry with name of unlinked workstation </description> <parameter name="To"> <value>chuck.derry@mycorp.com</value> </parameter> <parameter name="Subject"> <value>Agent CPU1 has been unlinked for at least 10 minutes</value> </parameter> <parameter name="Body"> <value>The cause seems to be: ${WSevent.UnlinkReason}</value> </parameter> </action> </eventRule> </eventRuleSet>
99
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 17. Event rule definition for scenario3 When file daytransac* is created in the SFoperation directory in workstation system1, and modifications to the file have terminated, submit the calmonthlyrev job stream. The event rule is valid year-round in the 18:00-22:00 EST time window. <?xml version="1.0" encoding="UTF-8"?> <eventRuleSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules" xsi:schemaLocation="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules EventRules.xsd"> <eventRule name="scenario3_rule" ruleType="filter" isDraft="no"> <description>This is the definition for scenario3</description> <timeZone>America/Louisville</timeZone> <validity from="2007-01-01" to="2007-12-31" /> <activeTime start="18:00:00" end="22:00:00" /> <eventCondition eventProvider="FileMonitor" eventType="ModificationCompleted"> <filteringPredicate> <attributeFilter name="FileName" operator="eq"> <value>daytransac*</value> </attributeFilter> </filteringPredicate> </eventCondition> <action actionProvider="TWSAction" actionType="SubmitJobStream" responseType="onDetection"> <description>Submit the calmonthlyrev job stream.</description> <parameter name="JobStreamName"> <value>calmonthlyrev</value> </parameter> <parameter name="JobStreamWorkstationName"> <value>act5cpu</value> </parameter> <parameter name="priority"> <value>high</value> </parameter> </action> </eventRule> </eventRuleSet>
100
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 18. Event rule definition for scenario4 When the job-x=exec event and the job-x=succ/abend event are received in 5 minutes, the scheduler should reply Yes to prompt-1 and start the jobstream-z job stream, otherwise it should send an e-mail to twsoper@mycompany.com alerting that the job is late. Save as draft. <?xml version="1.0" encoding="UTF-8"?> <eventRuleSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules" xsi:schemaLocation="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules EventRules.xsd"> <eventRule name="scenario4_rule" ruleType="sequence" isDraft="yes"> <description>This is the definition for scenario2</description> <timeZone>America/Buenos_Aires</timeZone> <timeInterval amount="5" unit="minutes" /> <eventCondition eventProvider="TWSObjectsMonitor" eventType="JobStatusChanged"> <filteringPredicate> <attributeFilter name="JobName" operator="eq"> <value>job-x</value> </attributeFilter> <attributeFilter name="InternalStatus" operator="eq"> <value>Exec</value> </attributeFilter> </filteringPredicate> </eventCondition> <eventCondition eventProvider="TWSObjectsMonitor" eventType="JobStatusChanged"> <filteringPredicate> <attributeFilter name="JobName" operator="eq"> <value>job-x</value> </attributeFilter> <attributeFilter name="InternalStatus" operator="eq"> <value>Abend</value> <value>Succ</value> </attributeFilter> </filteringPredicate> </eventCondition> <action actionProvider="MailSender" actionType="SendMail" responseType="onTimeOut"> <description>Send email to operator saying that job-x is late</description> <parameter name="To"> <value>twsoper@mycorp.com</value> </parameter> <parameter name="Subject"> <value>Job-x is late by at least 5 minutes</value> </action> <action actionProvider="TWSAction" actionType="ReplyPrompt" responseType="onDetection"> <description>Reply Yes to prompt-1</description> <parameter name="PromptName"> <value>prompt-1</value> </parameter> <parameter name="PromptAnswer"> <value>Yes</value> </parameter> </action> <action actionProvider="TWSAction" actionType="SubmitJobStream" responseType="onDetection"> <description>Submit jobstream-z</description> <parameter name="JobStreamName"> <value>jobstream-z</value> </parameter> <parameter name="JobStreamWorkstationName"> <value>act23cpu</value> </parameter> </action> </eventRule> </eventRuleSet>
101
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Rule operation notes

The following table contains critical information on event rule behavior that might help you understand the reason for unexpected results:
Table 19. Rule operation notes Topic Lack of persistence in rule instance status Note If the event processor is stopped or crashes, the status of rule instances that are only partially matched is lost. Typically, each active rule has one, and only one, copy that runs in the event processing server.Set and sequence rules use the mechanism explained in the following example: 1. You define a sequence rule with two events, A and B. 2. When the first event that matches the sequence occurs (event A), it activates the rule and waits for the second event (event B). Once the rule is active, any additional event A events that may arrive are ignored. No additional rules are created for any newly detected event A events as long as the rule is waiting for event B. 3. Once event B occurs, the rule is completed and resets, waiting for event A to occur again. The mechanism of set and sequence rules is such that any additional occurrences of an already detected event are ignored and discarded if the other defined events have not arrived. You can prevent this problem by using correlation attributes. Using one or more correlation attributes is a method for directing a rule to create a separate rule copy when another event A arrives.
Repeating set and sequence rules
102
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 19. Rule operation notes (continued) Topic Set and sequence rule types with shorter than 24 hours activity time windows Note Occurrences of set or sequence rules that were defined to be active for only a few hours of every day, are not purged when the activity period within each day expires if only part of the events arrive. They remain in an idle state, waiting to receive the remaining events in the following days. For example, you define a set rule that includes two events. The rule is valid from January 1 to January 10, and is active daily from 6 to 10 AM. If on January 1 the first event is received at 8 AM, the rule waits for the second event to take place, and stays alive beyond 10 AM if the event is not detected. If the second event is received at 11 AM (which is out of the activity time window), it is discarded, but the rule keeps on staying alive. If the second event is received again at 7 AM of January 2, the rule is triggered and the actions are implemented. If you don not want the rule to carry over to the next day, you should purge it.
Triggered rule elements

Every time the event conditions listed in a deployed event rule are matched, or time out, an event rule instance is created. An event rule instance includes information like event rule name, date and time when it was matched, and the list of action instances, and their status, that were run as a result of the matching event conditions. The RuleInstance object is used to collect information about triggered rules in a history log of rule instances. Actions carried out by a triggered rule are collected in a history log of action runs. The provided information includes action runs that have been completed with errors or warnings, as opposed to successful ones. If at least one action ends in error, then the whole rule instance will be reported in error. As part of the information tracked in action runs, rule fields are also maintained, and queries can be executed to look for action runs based on these fields (the rule instance identifier is also available).
Defining custom events

In addition to the already defined event types and event classes (known as providers) listed in detail in Event providers and definitions on page 509, Tivoli Workload Scheduler supplies the template of a generic event provider named GenericEventPlugIn that programmers with specific application and XML programming skills can modify to define custom event types that might be of use to the organization. The tools supplied to define custom event types are:
103
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
v The GenericEventPlugIn event provider in XML v The evtdef utility command with which a programmer can download the GenericEventPlugIn event provider as a local file to define the custom events v The XML schema definition (XSD) files necessary to validate the modified generic event provider. They also contain online guidelines to aid in the programming task. v The sendevent utility command with which the custom events can be sent to the event processing server to trigger rules from any agent or any workstation running simply the Tivoli Workload Scheduler remote command line client. This is the flow for defining and using custom events: 1. With the evtdef command, the programmer: a. Downloads the generic event provider as a local file. b. Follows the schema definitions to add custom event types and to define their properties and attributes in the file with an XML editor. c. Uploads the local file as the modified generic event provider containing the new custom event type definitions. The modified generic event provider is saved in an XML file on the master domain manager. 2. The rule builder, or the administrator, defines, with either composer or the Tivoli Dynamic Workload Console, the event rules that are to be triggered by these custom events, specifying: v The generic event provider as the event provider v The custom event types as the event types v The custom event type properties (or attributes) defined for the custom events in the generic event provider with the particular values that will trigger the rules. 3. Deploy the rules. 4. When the occurrence of a custom event takes place, it can be sent to the event processing server in one of the following ways: v By the sendevent command, run from a script or from the command line v By another application, such as Tivoli Enterprise Console or Tivoli Monitoring As soon as the event is received by the event processing server, it triggers the rule.
104
Chapter 7. Defining objects in the database

Tivoli Workload Scheduler is based on a set of object definitions that are used to map your scheduling environment into the database. Scheduling objects are: v calendars v domains v event rules v jobs v job streams v prompts v parameters v resources v workstations v workstation classes This chapter is divided into the following sections: v What is new in defining scheduling objects v Defining scheduling objects | |
What is new in defining scheduling objects

The major enhancement is the addition of the event rule scheduling object.
Defining scheduling objects

Scheduling objects are managed with the composer command-line program and are stored in the Tivoli Workload Scheduler database. The composer command-line program can be installed and used on any machine connected through TCP/IP to the system where the master domain manager is installed. It does not require the installation of a Tivoli Workload Scheduler workstation as a prerequisite. It communicates through HTTP/HTTPS with the master domain manager where the DB2 database is installed. The HTTP/HTTPS communication setup and the authentication check are managed by the WebSphere Application Server infrastructure. The composer program uses edit files to update the scheduling database. The format of the edit file used to define a specific object is described later in this chapter. For example, to create a new object, enter its definition in an edit file, and then use composer to add it to the database by specifying the edit file containing the definition. The composer command-line program checks for correct syntax inside the edit file, and, if correct, transforms the object definition into XML language and then sends the request through HTTP/HTTPS to the master domain manager. On the master domain manager the XML definition is parsed, semantic and integrity checks are performed, and then the update is stored in the database. With this version of the product all entries are managed individually. Another feature introduced with this new version is the object locking mechanism. Scheduling objects defined in the database are locked while accessed by a user to prevent concurrent accesses. This means that only the user locking the object has write permission to that object, and other users have read only access to that object. For additional information refer to lock on page 224 and unlock on page 238.
105
Defining object in the database

| | | | | | | | | | | | | | | | | | | | | | You can use short and long keywords when issuing commands from composer, as Table 20 shows. The first two columns on the left list the long and short keyword formats currently supported by Tivoli Workload Scheduler. The rightmost column lists the backward compatible formats you want to use if your network includes pre-version 8.3 installations.
Table 20. List of supported scheduling object keywords backward compatible keywords with pre-version 8.3 installations calendars cpu jobs sched parms prompts resources users cpu cpu
Long keywords calendar domain eventrule jobdefinition jobstream parameter prompt resource user workstation workstationclass
Short keywords cal dom erule | er jd js parm prom res user ws wscl
Note: The cpu keyword is maintained to represent domains, workstations, and workstation classes for backward compatibility. The composer program does not issue specific warnings if scheduling language keywords are used as names of scheduling objects. However, the use of such keywords can result in errors, so avoid using the keywords listed in Table 21 when defining jobs and job streams:
Table 21. List of reserved words when defining jobs and job streams abendprompt after at autodocoff autodocon canc carryforward confirmed continue dateval day(s) day_of_week deadline description tasktype runcycle docommand end every everyday except extraneous fdignore fdnext fdprev filename follows freedays go hi after validfrom i18n_id i18n_priority interactive isuserjob jobfilename keyjob keysched limit needs nextjob notempty number on onuntil abendprompt validto op opens order prompt qualifier rccondsucc recovery request rerun sa schedule scriptname stop streamlogon draft schedtime su timezone token_in until weekday(s) workday(s) jobs priority as matching previous sameday relative from to
Avoid using the keywords listed in Table 22 on page 107 when defining workstations, workstation classes and domains:
106
Defining object in the database

Table 22. List of reserved words when defining workstations access AIX agent_type autolink behindfirewall command cpuclass cpuname description domain parent enabled end extraneous for force fullstatus host hpux ignore type linkto maestro manager master members mpeix mpexl mpev mpix fta node number off on os other parent posix tz access server secureaddr securitylevel tcpaddr timezone tzid UNIX using wnt timezone
Avoid using the keywords listed in Table 23 when defining Windows users:
Table 23. List of reserved words when defining users username password end
107
Workstation definition
A workstation is a scheduling object that runs jobs. It is usually an individual computer on which jobs and job streams are run. A workstation definition is required for every computer that runs jobs in the IBM Tivoli Workload Scheduler network. Primarily workstation definitions refer to physical workstations. However, in the case of extended agents, the workstations are logical definitions that must be hosted by a physical workstation. You can include multiple workstation definitions in the same text file, along with workstation class definitions and domain definitions. Each workstation definition has the following format and arguments:
Syntax
cpuname workstation [description description] os os-type node hostname [tcpaddr port] [secureaddr port][timezone|tz tzname] [domain domainname] [for maestro [host host-workstation [access method]] [type fta | s-agent | x-agent | manager] [ignore] [autolink on | off] [behindfirewall on | off] [securitylevel enabled | on | force] [fullstatus on | off] [server serverid]] end [cpuname ...] [cpuclass ...] [domain ...]
Arguments
Table 24 on page 109 gives you an overview about specifying settings for the different types of workstations that can be defined. Mandatory settings are written in bold. For additional details about the mentioned options refer to the options descriptions that follow.
108
Table 24. Option settings for workstation types Options Master Domain Manager Domain Manager Backup Domain Manager Fault-tolerant Agent Standard Agent Extended Agent Must be set to NULL for some extended agent. Refer to the selected access method specifications.
Node
Systems hostname or IP address
TCP Port
Default Value 31111. The value must match nm port number in the localopts file. (For multiple workstations on a system, enter an unused port number)
Operating System Domain (the default value is MASTERDM) Time Zone Description
UNIX or WNT, for supported operating systems. OTHER for AS/400 systems as OTHER fault-tolerant agent or standard agent. MASTERDM The name of the managed Domain. The name of the managed Domain. Existing domain Mutually exclusive with Host setting Not used. Not Applicable
The time zone in which the system is located. The value must match the value set on the operating system. This is just a comment
Hosts time zone
SSL This option depends on the security needs of the site. It is not applicable for Communications AS/400 workstations. Firewall Secure Port Type Autolink Ignore Full Status Server This option depends on the security needs of the site. This option depends on the security needs of the site. Manager Optional Manager fault-tolerant agent fault-tolerant agent S-agent
Not Applicable Not Applicable Not applicable X-agent Not Applicable
Usually OFF, turn ON if you do not want this workstation to appear in the next plan. ON Not Applicable ON ON Optional OFF Not Applicable Not Applicable
Not Applicable 0-9, A-Z. Used to create multiple mailman processes on parent.
Access Method
Not Applicable
Select the appropriate access method file name. Mutually The host exclusive with workstation. Domain setting
Host
Not Applicable
cpuname workstation Specifies the name of the workstation. The name must start with a letter, and can contain alphanumeric characters, dashes, and underscores. It can contain up to 16 characters. See Table 21 on page 106 for a list of words to avoid using when specifying the cpuname. Note: Workstation names must be unique and cannot be the same as workstation class names.
109
description description Provides a description of the workstation. The text must be enclosed within double quotes. os os_type Specifies the operating system of the workstation. Valid values are UNIX, WNT, and OTHER. Use: UNIX For supported operating systems running on UNIX-based systems. WNT For supported Windows operating systems.
OTHER Used in connection with extended agents. Note: Refer to the IBM Tivoli Workload Scheduler Release Notes for an up-to-date list of supported operating system. node hostname Specifies the host name or the TCP/IP address of the workstation. Fully-qualified domain names are accepted. tcpaddr port Specifies the TCP/IP port number that Tivoli Workload Scheduler uses for communicating between workstations. Its value must match with the value assigned in the localopts file for variable nm port number. The default is 31111. secureaddr Defines the port used to listen for incoming SSL connections. This value must match the one defined in the nm SSL port local option of the workstation. It must be different from the nm port local option that defines the port used for normal communications. If securitylevel is specified but this attribute is missing, 31113 is used as the default value. See the IBM Tivoli Workload Scheduler Planning and Installation Guide for information about SSL authentication and local options set in the TWS_home/localopts configuration file. timezone|tz tzname Specifies the time zone of the workstation. See Chapter 12, Managing time zones, on page 461 for valid time zone names. To ensure the accuracy of scheduling times, this time zone must be the same as the computers operating system time zone. domain domainname Specifies the name of Tivoli Workload Scheduler domain of the workstation. The default for fault-tolerant is the master domain, usually named MASTERDM. The default for a domain manager is the domain in which it is defined as the manager. In a standard agent workstation definition the domain and the host settings are mutually exclusive; if the domain is not set then its default is the domain of the hosting workstation. Tivoli Workload Scheduler ignores domain setting when defined for extended agents. host host-workstation Specifies the name of the agents host workstation. This is required for extended agents. The host is the workstation with which the extended agent communicates and where its access method resides. Note that the host cannot be another extended agent. You can use the key $MASTER to indicate that the agents host workstation for the extended agent or the standard agent is the master domain manager; in this case if the master
110
domain manager name is modified later on, Tivoli Workload Scheduler automatically updates the value assigned to the $MASTER key. In a standard agent workstation definition the domain and the host settings are mutually exclusive and, if set, the host setting is used only to determine the setting of the domain keyword. access method Specifies an access method for extended and network agents. This must be the name of a file that resides in the TWS_home/methods directory on the agents host workstation. type Specifies the type of workstation. Enter one of the following: fta s-agent Standard agent. x-agent Extended agent. Note: For some access methods you must set the Node Name to NULL. For more information, refer to IBM Tivoli Workload Scheduler for Applications. manager Domain manager. The information about whether a workstation is a manager is also set in the manager field in the Domain definition on page 117. An extra check on the consistency of the values set in these two fields is automatically made by Tivoli Workload Scheduler. These are the specific settings when defining a domain manager: v Server - NULL v Domain - if different from MASTERDM it corresponds to the name of the domain it manages ignore Specifies that this workstation definition must not be added to the production plan. autolink Specifies whether to open the link between workstations at startup. For fault-tolerant and standard agents, enter on to have the domain manager open the link to the agent when the domain manager is started. For the domain manager, enter on to have its agents open links to the domain manager when they are started. Autolink is useful primarily during the startup sequence when activating a new production plan. At that time, a new production plan is created and compiled on the master domain manager, and all workstations are stopped and restarted. For each agent with autolink turned on, the domain manager automatically sends a copy of the new production plan and starts the agent. If autolink is also turned on for the domain manager, the agent, in turn, opens a link back to the domain manager. If the value of autolink is off for an agent, it is initialized when you run a conman link command on the agents domain manager or the master domain manager. behindfirewall If this attribute is set to ON, it means there is a firewall between the workstation and the master domain manager. Only a direct connection
Fault-tolerant agent, including backup domain managers and backup master domain manager.
111
between the workstation and its domain manager is allowed. For all the workstations with behindfirewall set to ON, the start workstation, stop workstation, and showjobs commands are sent following the domain hierarchy, instead of making the master domain manager or the domain manager open a direct connection with the workstation. fullstatus Specifies whether the agent is updated with full or partial status. This is for FTAs only, for domain managers this keyword is automatically set to on. Enter on to have the agent operate in Full Status mode. In this mode, the agent is updated with the status of jobs and job streams running on all other workstations in its domain and in subordinate domains, but not on peer or parent domains. This setting automatically sets accordingly the resolve dependencies option. If the value of fullstatus is off, the agent is informed only about the status of jobs and job streams on other workstations that affect its own jobs and job streams. This can improve performance by reducing network activity. To keep an agents production plan at the same level of detail as its domain manager, set fullstatus to on. securitylevel Specifies the type of SSL authentication for the workstation. It can have one of the following values: enabled The workstation uses SSL authentication only if its domain manager workstation or another FTA below it in the domain hierarchy requires it. on The workstation uses SSL authentication when it connects with its domain manager. The domain manager uses SSL authentication when it connects to its parent domain manager. The FTA refuses any incoming connection from its domain manager if it is not an SSL connection. force The workstation uses SSL authentication for all of its connections and accepts connections from both parent and subordinate domain managers. It refuses any incoming connection that is not an SSL connection. If this attribute is omitted, the workstation is not configured for SSL connections. In this case, any value for secureaddr is ignored. You should also set the nm ssl port local option to 0 to be sure that this port is not opened by netman. See the IBM Tivoli Workload Scheduler Planning and Installation Guide for information about SSL authentication. Table 25 describes the type of communication used for each type of securitylevel setting.
Table 25. Type of communication depending on the security level value Fault-tolerant Agent (Domain Manager) Domain Manager (Parent Domain Manager) Connection Type TCP/IP Enabled On Force On Enabled On TCP/IP No connection No connection TCP/IP TCP/IP
112
Table 25. Type of communication depending on the security level value (continued) Fault-tolerant Agent (Domain Manager) On Force Domain Manager (Parent Domain Manager) On On Enabled Enabled On Force Enabled Enabled Enabled Force Enabled On Force Force Force Force Connection Type SSL SSL TCP/IP TCP/IP SSL SSL No connection SSL SSL SSL
server ServerID Specifies a mailman server on the domain manager to handle communications with the fault-tolerant agent. Using servers can reduce the time required to initialize agents and improve the timeliness of messages. This setting is used for fault-tolerant agents. If you are defining a fault-tolerant agent that can work as backup domain manager, the ServerID set is used when the workstation works as fault-tolerant agent; the setting is ignored when the workstation works as a backup domain manager. For information on how to switch domain managers in a domain, refer to switchmgr on page 367. Within the ServerID, the ID is a single letter or a number (A-Z and 0-9). The IDs are unique to each domain manager, so you can use the same IDs in other domains without conflict. If more than 36 server IDs are required in a domain, consider dividing it into two or more domains. If a ServerID is not specified, communications with the agent are handled by the main mailman process on the domain manager. When the domain manager starts, it creates a separate server for each unique ServerID. If the same ID is used for multiple agents, a single server is created to handle their communications. Define extra servers to prevent a single server from handling more than eight agents. Note: You can add workstation definitions to the database at any time but you need to run JnextPlan -for 0000 again to be able to run jobs on newly created workstations. Every time you run JnextPlan all workstations are shut down and restarted.
Examples
The following example creates a master domain manager named hdq-1, and a fault-tolerant agent named hdq-2 in the master domain. Note that a domain argument is optional in this example, because the master domain defaults to masterdm.
cpuname hdq-1 description Headquarters master DM os unix tz America/Los_Angeles node sultan.ibm.com domain masterdm
113
for maestro type manager autolink on fullstatus on end cpuname hdq-2 os wnt tz America/Los_Angeles node opera.ibm.com domain masterdm for maestro type fta autolink on end
The following example creates a domain named distr-a with a domain manager named distr-a1 and a standard agent named distr-a2:
domain distr-a manager distr-a1 parent masterdm end cpuname distr-a1 description District A domain mgr os wnt tz America/New_York node pewter.ibm.com domain distr-a for maestro type manager autolink on fullstatus on end cpuname distr-a2 os wnt node quatro.ibm.com tz America/New_York domain distr-a for maestro type s-agent end
The following example creates a workstation with SSL authentication. The securitylevel security definition specifies that the connection between the workstation and its domain manager can be only of the SSL type. Port 32222 is reserved for listening for incoming SSL connections.
cpuname ENNETI3 os WNT node apollo tcpaddr 30112 secureaddr 32222 for maestro autolink off fullstatus on securitylevel on end
See also
For the equivalent Job Scheduling Console task, see Creating a z/OS Workstation and Creating a Distributed Workstation in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
114
Workstation class definition

A workstation class is a group of workstations for which common jobs and job streams can be written. You can include multiple workstation class definitions in the same text file, along with workstation definitions and domain definitions. Each workstation class definition has the following format and arguments:
Syntax
cpuclass workstationclass [description description] [ignore] members [workstation | @] [...] end [cpuname ...] [cpuclass ...] [domain ...]
Arguments
cpuclass workstationclass Specifies the name of the workstation class. The name must start with a letter, and can contain alphanumeric characters, dashes, and underscores. It can contain up to 16 characters. Note: You cannot use the same names for workstations, workstation classes, and domains. description description Provides a description of the workstation class. The text must be enclosed within double quotes. ignore Specifies that Tivoli Workload Scheduler must ignore all workstations included in this workstation class when generating the production plan. members workstation Specifies a list of workstation names, separated by spaces, that are members of the class. The @ wildcard character means that the workstation class includes all workstations.
Examples
The following example defines a workstation class named backup:
cpuclass backup members main site1 site2 end
The following example defines a workstation class named allcpus that contains every workstation:
cpuclass allcpus members @ end
115
See also
For the equivalent Job Scheduling Console task, see Creating a Workstation Class in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
116
Domain definition
Domain definition
A domain is a group of workstations consisting of one or more agents and a domain manager. The domain manager acts as the management hub for the agents in the domain. You can include multiple domain definitions in the same text file, along with workstation definitions and workstation class definitions. Each domain definition has the following format and arguments:
Syntax
domain domainname[description description] * manager workstation [parent domainname | ismaster] end [cpuname ...] [cpuclass ...] [domain ...]
Arguments
domain domainname The name of the domain. It must start with a letter, and can contain alphanumeric characters, dashes, and underscores. It can contain up to 16 characters. You cannot use the same names for workstations, workstation classes, and domains. description description Provides a description of the domain. The text must be enclosed within double quotes. * manager workstation This is a commented field used only to show, when displaying the domain definition, the name of the workstation that has the role of domain manager for that domain. Make sure this field remains commented. It is kept for backward compatibility. With Tivoli Workload Scheduler version 8.3 the information about whether a workstation is a domain manager is set in the type field in the Workstation definition on page 108. parent domainname The name of the parent domain to which the domain manager is linked. The default is the master domain, which does not require a domain definition. The master domain is defined by the global options master and master domain. ismaster If specified, indicates that the domain is the top domain of the Tivoli Workload Scheduler network. If set it cannot be removed later.
Examples
The following example defines a domain named east, with the master domain as its parent, and two subordinate domains named northeast and southeast:
domain east description The Eastern domain * manager cyclops end domain northeast description The Northeastern domain
117
Domain definition
* manager boxcar parent east end domain southeast description The Southeastern domain * manager sedan parent east end
See also
For the equivalent Job Scheduling Console task, see Creating a Domain in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
118
Job definition
Job definition
A job is an executable file, program, or command that is scheduled and launched by Tivoli Workload Scheduler. You can write job definitions in edit files and then add them to Tivoli Workload Scheduler database with the composer command line program. You can include multiple job definitions in a single edit file. Each job definition has the following format and arguments:
Syntax
$jobs [workstation#]jobname {scriptname filename | docommand command} streamlogon username [description description] [tasktype tasktype] [interactive] [rccondsucc Success Condition] [recovery {stop | continue | rerun} [after [workstation#]jobname] [abendprompt text] ] A job itself has no settings for dependencies, these must be added to the job when it is included in a job stream definition. You can add or modify job definitions from within job stream definitions. Modifications to jobs definitions made in job streams definitions are reflected in the job definitions stored in the database. This means that if you modify the job definition of job1 in job stream definition js1 and job1 is used also in job stream js2, also the definition of job1 in js2 definition is modified accordingly. Refer to section Job stream definition on page 133 for information on how to write job streams definitions. Note: Wrongly typed keywords used in job definitions lead to truncated job definitions stored in the database. In fact the wrong keyword is considered extraneous to the job definition and so it is interpreted as the job name of an additional job definition. Usually this misinterpretation causes also a syntax error or an inexistent job definition error for the additional job definition.
Arguments
workstation# Specifies the name of the workstation or workstation class on which the job runs. The default is the workstation specified for defaultws when starting the composer session. For more information on how to start a composer session refer to Running the composer program on page 191. The pound sign (#) is a required delimiter. If you specify a workstation class, it must match the workstation class of any job stream in which the job is included. jobname Specifies the name of the job. The name must start with a letter, and can contain alphanumeric characters, dashes, and underscores. It can contain up to 40 characters. scriptname filename
119
Job definition
Specifies the name of the file the job runs. Use scriptname for UNIX and Windows jobs. For an executable file, enter the file name and any options and arguments. The length of filename plus the length of Success Condition (of the rccondsucc keyword) must not exceed 4095 characters. You can also use Tivoli Workload Scheduler parameters. See Using parameters in job definitions on page 123 for more information. For Windows jobs, include the file extensions. Universal Naming Convention (UNC) names are permitted. Do not specify files on mapped drives. If the file path or the file name of the scriptname argument contain spaces, the entire string must be enclosed between "\" and \" " as shown below:
scriptname "\"C:\Program Files\tws\myscript.cmd\""
If special characters are included, other than slashes (/) and backslashes (\), the entire string must be enclosed in quotes (). docommand command Specifies a command that the job runs. Enter a valid command and any options and arguments enclosed in double quotes (). The length of command plus the length of Success Condition (of the rccondsucc keyword) must not exceed 4095 characters. A command is run directly and, unlike scriptname, the configuration script, jobmanrc, is not run. Otherwise, the command is treated as a job, and all job rules apply. You can also enter Tivoli Workload Scheduler parameters. See Using parameters in job definitions on page 123 for more information. streamlogon username The user name under which the job runs. The name can contain up to 47 characters. If the name contains special characters it must be enclosed in double quotes (). Specify a user that can log on to the workstation on which the job runs. You can also enter Tivoli Workload Scheduler parameters. See Using parameters in job definitions on page 123 for more information. For Windows jobs, the user must also have a user definition. See Windows user definition on page 125 for user requirements. description description Provides a description of the job. The text must be enclosed in double quotes.The maximum number of characters allowed is 120. tasktype tasktype Specifies the job type. It can have one of the following values: UNIX WINDOWS OTHER For jobs that run on UNIX platforms. For jobs that run on Windows platforms. For jobs that run on extended agents.
Note: Refer to IBM Tivoli Workload Scheduler for Applications: User's Guide for information on customized task types for supported third party applications. interactive | | Specifies that the job runs interactively on the user's desktop. This feature is available only on Windows environments.
120
Job definition
rccondsucc Success Condition An expression which determines the return code (RC) required to consider a job successful. The success condition can be a maximum of 256 characters. This expression can contain a combination of comparison and Boolean expressions: Comparison expression Specifies the job return codes. The syntax is:
(RC operator operand)
RC
The RC keyword.
operator Comparison operator. It can have the following values:

Table 26. Comparison operators Example RC<a RC<=a RC>a RC>=a RC=a RC!=a RC<>a Operator < <= > >= = != <> Description Less than Less than or equal to Greater than Greater than or equal to Equal to Not equal to Not equal to
operand An integer between -2147483647 and 2147483647. For example, you can define a successful job as a job that ends with a return code less than or equal to 3 as follows:
rccondsucc "(RC <= 3)"
Boolean expression Specifies a logical combination of comparison expressions. The syntax is:
comparison_expression operator comparison_expression
comparison_expression The expression is evaluated from left to right. You can use parentheses to assign a priority to the expression evaluation. operator Logical operator. It can have the following values:
Table 27. Logical operators Example expr_a and expr_b expr_a or expr_b Not expr_a Operator And Or Not Result TRUE if both expr_a and expr_b are TRUE. TRUE if either expr_a or expr_b is TRUE. TRUE if expr_a is not TRUE.
121
Job definition
For example, you can define a successful job as a job that ends with a return code less than or equal to 3 or with a return code not equal to 5, and less than 10 as follows:
rccondsucc "(RC=3) OR ((RC>=5) AND (RC<10))"
recovery Recovery options for the job. The default is stop with no recovery job and no recovery prompt. Enter one of the recovery options, stop, continue, or rerun. This can be followed by a recovery job, a recovery prompt or both. stop If the job abends, do not continue with the next job.
continue If the job abends, continue with the next job. rerun If the job abends, rerun the job.
after [workstation#]jobname Specifies the name of a recovery job to run if the parent job abends. Recovery jobs are run only once for each abended instance of the parent job. You can specify the recovery jobs workstation if it is different from the parent jobs workstation. The default is the parent jobs workstation. Not all jobs are eligible to have recovery jobs run on a different workstation. Follow these guidelines: v If either workstation is an extended agent, it must be hosted by a domain manager or a FTA with a value of on for fullstatus. v The recovery job workstation can be in the same domain as the parent job workstation or in an upper domain. v If the recovery job workstation is a FTA, it must have a value of on for fullstatus. abendprompt text Specifies the text of a recovery prompt, enclosed in double quotes, to be displayed if the job abends. The text can contain up to 64 characters. If the text begins with a colon (:), the prompt is displayed, but no reply is required to continue processing. If the text begins with an exclamation mark (!), the prompt is displayed, but it is not recorded in the log file. Table 28 summarizes all possible combinations of recovery options and actions. The table is based on the following criteria from a job stream called sked1: v Job stream sked1 has two jobs, job1 and job2. v If selected for job1, the recovery job is jobr. v job2 is dependent on job1 and does not start until job1 has completed.
Table 28. Recovery options and actions Stop Recovery prompt: No Recovery job: No Intervention is required. Continue Run job2. Rerun Rerun job1. If job1 abends, issue a prompt. If reply is yes, repeat above. If job1 is successful, run job2.
122
Job definition
Table 28. Recovery options and actions (continued) Stop Recovery prompt: Yes Recovery job: No Issue recovery prompt. Intervention is required. Run jobr. If it abends, intervention is required. If it is successful, run job2. Continue Issue recovery prompt. If reply is yes, run job2. Rerun Issue recovery prompt. If reply is yes, rerun job1. If job1 abends, repeat above. If job1 is successful, run job2. Run jobr. If jobr abends, intervention is required. If jobr is successful, rerun job1. If job1 abends, issue a prompt. If reply is yes, repeat above. If job1 is successful, run job2. Issue recovery prompt. If reply is yes, run jobr. If jobr abends, intervention is required. If jobr is successful, rerun job1. If job1 abends, repeat above. If job1 is successful, run job2.
Recovery prompt: No Recovery job: Yes
Run jobr. Run job2.
Recovery prompt: Yes Recovery job: Yes
Issue recovery prompt. If reply is yes, run jobr. If it abends, intervention is required. If it is successful, run job2.
Issue recovery prompt. If reply is yes, run jobr. Run job2.
Notes: 1. Intervention is required means that job2 is not released from its dependency on job1, and therefore must be released by the operator. 2. The continue recovery option overrides the abend state, which might cause the job stream containing the abended job to be marked as successful. This prevents the job stream from being carried forward to the next production plan. 3. If you select the rerun option without supplying a recovery prompt, Tivoli Workload Scheduler generates its own prompt. 4. To reference a recovery job in conman, use the name of the original job (job1 in the scenario above, not jobr). Only one recovery jobs is run for each abend. Using parameters in job definitions: Parameters have the following uses and limitations in job definitions: v Parameters are allowed in the streamlogon, scriptname, and docommand values. v A parameter can be used as an entire string or as part of it. v Multiple parameters are permitted in a single variable. v Enclose parameter names in carets (^), and enclose the entire string in quotation marks. v Ensure that caret characters are not preceded by a backslash in the string. If necessary, include the backslash in the definition of the parameter. Refer to Parameter definition on page 128 for additional information and example. In the example below a parameter named mis is used in the streamlogon value. For additional examples, see Parameter definition on page 128.
Examples
The following is an example of a file containing two job definitions:
123
Using parameters in job definitions

$jobs cpu1#gl1 scriptname "/usr/acct/scripts/gl1" streamlogon acct description "general ledger job1" bkup scriptname "/usr/mis/scripts/bkup" streamlogon "^mis^" recovery continue after recjob1
See also
For the equivalent Job Scheduling Console task, see Creating a Job Definition in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
124
Windows user definition
Windows user definition

The user names used as the streamlogon value for Windows job definitions must have user definitions. This is not required for users who run jobs on other operating system. Each user definition has the following format and arguments:
Syntax
username[workstation#][domain\]username password passwordend [username ...]
Arguments
username [workstation#]username Specifies the name of a Windows user. workstation Specifies the workstation on which the user is allowed to launch jobs. The pound sign is required. The default is blank, meaning all workstations. [domain\]username Specifies the Windows domain of the user and the name of the user. Note: Windows user names are case-sensitive. Also, the user must be able to log on to the workstation on which Tivoli Workload Scheduler launches jobs, and have the permission to Log on as batch. The domain name can contain up to 16 characters (including the backslash), and the user name can contain up to 31 characters. If the name is not unique in Windows, it is taken to mean a local user, a domain user, or a trusted domain user, in that order. password Specifies the user password. The password can contain up to 29 characters, and must be enclosed in quotes. To indicate a null password, use two consecutive double quotes with no blanks in between, . When a user definition has been compiled, you cannot read the password. Users with appropriate security privileges can modify or delete a user, but password information is never displayed. Using the Tivoli Workload Scheduler user and streamlogon definitions: In Windows, user definitions are specified using composer in the form [workstation#]username. The instance [workstation#]username uniquely identifies the Windows user in the Tivoli Workload Scheduler environment. The workstation name is optional; its absence indicates that the user named username defined on all the Windows workstations in the Tivoli Workload Scheduler network. If the user named username is only defined on some Windows workstations in the Tivoli Workload Scheduler network, to avoid inconsistencies, you must create a user definition [workstation#]username for each workstation running on Windows where the user username is defined.
125
Using the Tivoli Workload Scheduler user and streamlogon definitions

When you define or submit a job using composer, you must specify both a workstation and a valid user logon for the workstation. The logon is just a valid user name for Windows, without the workstation name. For example, in the following job definition:
$JOB workstation job01 docommand "dir" streamlogon username
the value for streamlogon is username and not workstation#username. However, when you use the altpass command, you must use the user definition in the format
workstation#username
For this command, you can omit the workstation name only when changing the password of the workstation from where you are running the command. Trusted domain user: If Tivoli Workload Scheduler is to launch jobs for a trusted domain user, follow these guidelines when defining the user accounts. Assuming Tivoli Workload Scheduler is installed in Domain1 for user account maestro, and user account sue in Domain2 needs to launch a job, the following must be true: v There must be mutual trust between Domain1 and Domain2. v In Domain1 on the computers where jobs are launched, sue must have the right to Log on as batch. v In Domain1, maestro must be a domain user. v On the domain controllers in Domain2, maestro must have the right to Access this computer from network.
Examples
The following example defines four users:
username joe password "okidoki" end # username server#jane password "okitay" end # username dom1\jane password "righto" end # username jack password "" end
See also
For the equivalent Job Scheduling Console task, see Creating a Windows User in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
126
Calendar definition
Calendar definition
A calendar is a list of dates which define if and when a job stream runs. Each calendar definition has the following format and arguments:
Syntax
$calendar calendarname [description] date [...] [calendarname ...]
Arguments
calendarname Specifies the name of the calendar. The name can contain up to eight alphanumeric characters, including dashes (-) and underscores (_), and must start with a letter. description Provides a description of the calendar. It must be enclosed in double quotes. It can contain alphanumeric characters as long as it starts with a letter. It can contain the following characters: comma (,), period (.), dash (-), plus (+), single quote (), and equal (=). It cannot contain double quotes () other than the enclosing ones, colon (:), semi-colon (;), and ampersand (&). date [...] Specifies one or more dates, separated by spaces. The format is mm/dd/yy.
Examples
The following example defines three calendars named monthend, paydays, and holidays:
$calendar monthend "Month 01/31/2005 paydays 01/15/2005 03/15/2005 05/14/2005 holidays 01/01/2005 end dates 1st half 2005" 02/28/2005 03/31/2005 04/30/2005 05/31/2005 06/30/2005 02/15/2005 04/15/2005 06/15/2005 02/15/2005 05/31/2005
See also
For the equivalent Job Scheduling Console task, see Creating a Calendar in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
127
Parameter definition
Parameters are values which substitute variables in job and job stream definitions when the new production plan is created or extended.
Syntax
$parm parametername value [parametername ...]
Arguments
parametername The name of the parameter. The name can contain up to eight alphanumeric characters, including dashes (-) and underscores (_), and must start with a letter. value Specifies the value assigned to the parameter. Do not include the names of other parameters.
In Tivoli Workload Scheduler you can use two different types of parameter: global parameters These are the parameters defined as scheduling objects in the database. They can be used in job and job stream definitions to specify the keywords scriptname, docommand, opens, streamlogon and in prompts definitions by enclosing the parametername between carets ^ ^. They are resolved, that is replaced with their assigned value, when the production plan is generated or extended. If a parameter with name parametername is not defined in the database, the name reported unresolved in the Symphony file. An example of global parameter used with the docommand keyword is:
docommand "ls ^MY_HOME^"
local parameters These are the parameters that you can define in a database locally on a workstation using the utility command parms on page 400. They can be used in job and job stream definitions to specify the keywords scriptname and opens. A local parameter is defined within these keywords or from within the invoked job script using the following syntax )bin\parms PARAMETERNAME). They are resolved using the definitions stored in the local PARMS database as follows: v At run time on the workstation where job processing occurs. v At submission time on the workstation where the job or job stream is submitted from the conman command line. For more information on how to submit jobs and job streams in production from the conman command line refer to Chapter 9, Managing objects in the plan conman, on page 243. An example of a local parameter used with the opens keyword is:
opens "/usr/home/tws_99/`/usr/home/tws_99/bin/parms MY_FILE`"
When defining a job or job stream in the database you can enclose to parametername between ) ) to ensure the parameter is solved at run time on the workstation even if a parameter with the same name is defined as a global parameter in the Tivoli Workload Scheduler database. For example, if you add to the database the following job definition:
128
$jobs myjob docommand "ls ^MYDIR^" streamlogon "^MYUSER^"
and two parameters named MYDIR and MYUSER are defined in the database, then as the production plan is created or extended the two parameters are resolved using the definitions contained in the database and their corresponding values are carried with the Symphony file. If you define in the database myjob as follows:
$jobs myjob docommand "ls )bin\parms\ MYDIR)" streamlogon ")bin\parms\ MYUSER)"
then as the production plan is created or extended the only action that is performed against the two parameters in the definition of myjob is the removal of the ) ), the parameters are carried in the Symphony file unresolved and then are resolved at run time locally on the target workstation using the value stored in the PARMS database. You can use multiple parameters in a single variable. When you use a parameter enclose it in carets (^), and then enclose the entire string in quotation marks. If the parameter contains a portion of a path, ensure that the caret characters are not immediately preceded by a backslash (\) because, in that case, the sequence \^ could be wrongly interpreted as an escape sequence and resolved by the parser as caret character. If necessary, move the backslash into the definition of the parameter between carets to avoid bad interpretation of the backslash character. For example, instead of entering the following parameters definition:
$PARM MYDIR "scripts" job01 scriptname "c:\operatorid\home\^MYDIR^\test.cmd"
you enter:
$PARM MYDIR "\scripts" job01 scriptname "c:\operatorid\home^MYDIR^\test.cmd"
Examples
Two parameters, glpah and gllogon, are defined as follows:
$parm glpath gllogon "/glfiles/daily" "gluser"
The glpath and gllogon parameters are used in the gljob2 job of theglsched job stream:
schedule glsched on weekdays : gljob2 scriptname "/usr/gl^glpath^" streamlogon "^gllogon^" opens "^glpath^/datafile" prompt ":^glpath^ started by ^gllogon^" end
See also
For the equivalent Job Scheduling Console task, see Creating a Parameter in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
129
Prompt definition
Prompt definition
A prompt identifies a textual message which is presented to the operator, it pauses the job or job stream processing and requires an affirmatively answer to allow processing to continue. You can use prompts as dependencies in jobs and job streams. There are two types of prompts: local or unnamed prompts An unnamed prompt is a prompt defined within a job or job stream definition using the keyword prompt, it has no name assigned and is not defined as a scheduling object in the database therefore it cannot be used by other jobs or job streams. global or named prompts A global prompt is defined in the database as a scheduling object, it is identified by an unique name and it can be used by any job or job stream. This section describes global prompts. For more information on local prompts refer to Job definition on page 119 and Job stream definition on page 133. Note: Predefined or global prompt definitions are reset each time the JnextPlan job is run.
Syntax
$prompt promptname [: | !]text [promptname ...]
Arguments
promptname Specifies the name of the prompt. The name can contain up to eight alphanumeric characters, including dashes (-) and underscores (_), and must start with a letter. text Provides the text of the prompt. Based on the character preceding the text, the prompt can behave differently: v If the text begins with a colon (:), the prompt is displayed, but no reply is required to continue processing. v If the text begins with an exclamation mark (!), the prompt is displayed, but it is not recorded in the log file. You can use one or more parameters as part or all of the text string for a prompt. If you use a parameter, the parameter string must be enclosed in carets (^). See Parameter definition on page 128 for an example. Note: Within local prompts, carets (^) not identifying a parameter, must be preceded by a backslash (\) to prevent them from causing errors in the prompt. Within global prompts, carets do not have to be preceded by a backslash. You can include backslash n (\n) within the text to create a new line.
Examples
The following example defines three prompts:
130
Prompt definition
$prompt prmt1 "ready for job4? (y/n)" prmt2 ":job4 launched" prmt3 "!continue?"
See also
For the equivalent Job Scheduling Console task, see Creating a Prompt in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
131
Resource definition
Resource definition
Resources represent physical or logical scheduling resources that can be used as dependencies for jobs and job streams.
Syntax
$resource workstation#resourcename units [description ] [workstation#resourcename ...]
Arguments
workstation Specifies the name of the workstation or workstation class on which the resource is used. resourcename Specifies the name of the resource. The name can contain up to eight alphanumeric characters, including dashes (-) and underscores (_), and must start with a letter. units Specifies the number of available resource units. Values can be 0 through 1024.
description Provides a description of the resource. It must be enclosed in double quotes. The resource units involved in needs dependencies for a job or for a job stream remain busy until the job or job stream is completed (successfully or not). The resource units are released as soon as the job or job stream is completed. When multiple jobs and job streams depend on the same resource, if not enough resource units are currently available for all of them it is assigned according to the job or job stream priority. The status of a job or job stream becomes READY as soon as all its dependencies are resolved. If the limit CPU set on the workstation does not allow it to run at the moment, it waits in READY state. The only exception to this behavior is when the job or job stream is GO, in which case it starts regardless of the value set for limit CPU.
Examples
The following example defines four resources:
$resource ux1#tapes 3 ux1#jobslots ux2#tapes 2 ux2#jobslots "tape units" 24 "job slots" "tape units" 16 "job slots"
See also
For the equivalent Job Scheduling Console task, see Creating a Distributed Resource in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
132
Job stream definition

A job stream consists of a sequences of jobs to be run, together with times, priorities, and other dependencies that determine the order of processing. Job streams created using the graphical user interface, even though they do not reference the keywords listed in this chapter, are saved using the same scheduling language syntax and keywords. A job stream begins with a schedule keyword followed by attributes and dependencies. The colon delimiter introduces the jobs invoked by the job stream. Each job has its own attributes and dependencies.
Syntax
schedule [workstation#]jobstreamname # comment [validfrom date] [timezone|tz tzname] [description text] [draft] [freedays calendarname [-sa] [-su]] [on [runcycle name] [validfrom date] [validto date] [description text] {date|day|calendar|request|icalendar} [,...] [fdignore|fdnext|fdprev] [({at time [+n day[s]] | schedtime time [+n day[s]]} [until time [+n day[s]] [onuntil action]] [deadline time [+n day[s]]])]] [,...] [except [runcycle name] [validfrom date] [validto date] [description text] {date|day|calendar|request|icalendar} [,...] [fdignore|fdnext|fdprev] [{(at time [+n day[s]])] | (schedtime time [+n day[s]])}]] [,...] [{at time [timezone|tz tzname] [+n day[s]] | schedtime time [timezone|tz tzname] [+n day[s]]}] [until time [timezone|tz tzname] [+n day[s]] [onuntil action]] [deadline time [timezone|tz tzname] [+n day[s]]] [carryforward] [matching {previous|sameday|relative from [+ | ] time to [+ | ] time| from time [+ | n day[s]] to time [+ n day[s]] [,...]}] [follows {[netagent::][workstation#]jobstreamname[.jobname |@] [previous| sameday|relative from [+|] time to [+|] time| from time [+|n day[s]] to time [+|n day[s]] [,...]]} [keysched] [limit joblimit] [needs [n] [workstation#]resourcename [,...]] [opens [workstation#]filename [(qualifier)] [,...]] [priority number | hi | go] [prompt {promptname|[:|!]text}]
133
: job-statement # comment [{at time [timezone|tz tzname] [+n day[s]] | schedtime time [timezone|tz tzname] [+n day[s]]}][,...] [until time [timezone|tz tzname] [+n day[s]] [onuntil action] [deadline time [timezone|tz tzname] [+n day[s]]] [,...] [every rate] [follows {[netagent::][workstation#]jobstreamname{.jobname @} [previous| sameday|relative from [+|] time to [+|] time | from time [+|n day[s]] to time [+|n day[s]] [,...]]} [confirmed] [keyjob] [needs [n] [workstation#]resourcename [,...]] [opens [workstation#]filename [(qualifier)] [,...]] [priority number | hi | go] [prompt {promptname |[:|!]text}] [job-statement...] end
Arguments
Table 29 contains a brief description of the job stream definition keywords. A detailed description of each scheduling keyword is provided in the next subsections.
Table 29. List of scheduling keywords Keyword at Description Defines the earliest time a job stream or a job run can be launched. When defined in a run cycle specifies the earliest time a job or a job stream can be launched for that specific run cycle. Carries the job stream forward if it is not completed. Includes comments in the definition of a job stream or in a job contained in the job stream. Specifies that the completion of this job requires confirmation. Specifies the time within which a job or job stream should complete. When defined in a run cycle specifies the time within which a job or a job stream must complete in that specific run cycle. Contains a description of the job stream. The maximum length of this field is 120 characters. Specifies that the plan generation process must ignore this job stream. Marks the end of a job stream. Launches the job repeatedly at a specified rate. Specifies dates that are exceptions to the on dates the job stream is selected to run. Page 138
carryforward comment confirmed deadline
139 140 141 142
description draft end every except
143 144 145 146 148
134

Table 29. List of scheduling keywords (continued) Keyword follows Description Specifies jobs or job streams that must complete successfully before the job or the job stream that is being defined is launched. Page 150
freedays
Specifies a freeday calendar for calculating workdays 152 for the job stream. It can also set Saturdays and Sundays as workdays. Defines a job and its dependencies. 154
job statement keyjob
Marks a job as key or critical in both the database 156 and in the plan for monitoring by applications, such as IBM Tivoli Business Systems Manager or IBM Tivoli Enterprise Console. Marks a job stream as key or critical in both the database and in the plan for monitoring by applications, such as IBM Tivoli Business Systems Manager or IBM Tivoli Enterprise Console. Sets a limit on the number of jobs that can be launched concurrently from the job stream. 157
keysched
limit matching
158
Defines the matching criteria used when a matching 159 criteria is not specified in the follows specifications in the job stream definition or in the job definition within the job stream. Defines the number of units of a resource required 160 by the job or job stream before it can be launched. The highest number of resources the job stream can be dependent from is 1024. Defines the dates on which the job stream is selected to run. Defines files that must be accessible before the job or job stream is launched. Specifies the action to take on a job or job stream whose until time has been reached. Defines the priority for a job or job stream. Defines prompts that must be replied to before the job or job stream is launched. Assigns a name to the job stream. Specifies the time used to set the job stream in the time line within the plan to determine successors and predecessors. 161 167 175 169 170 173 171
needs
on opens onuntil priority prompt schedule schedtime
until
Defines a latest time a job or a job stream can be 175 launched. When defined in a run cycle specifies the latest time a job or a job stream can be launched for that specific run cycle. Defines the date from which the job stream instance 177 starts.
validfrom
Notes: 1. Job streams scheduled to run on workstations marked as ignored are not added to the production plan when the plan is created or extended.
135

2. Wrongly typed keywords used in job definitions lead to truncated job definitions stored in the database. In fact the wrong keyword is considered extraneous to the job definition and so it is interpreted as the job name of an additional job definition. Usually this misinterpretation causes also a syntax error or an inexistent job definition error for the additional job definition.
Examples
This is an example of job stream definition:
SCHEDULE M235062_99#SCHED_FIRST1 VALIDFROM 06/30/2005 ON RUNCYCLE SCHED1_PREDSIMPLE VALIDFROM 07/18/2005 "FREQ=DAILY;INTERVAL=1" ( AT 1010 ) ON RUNCYCLE SCHED1_PRED_SIMPLE VALIDFROM 07/18/2005 "FREQ=DAILY;INTERVAL=1" CARRYFORWARD PROMPT "parto o no?" PRIORITY 55 : M235062_99#JOBMDM PRIORITY 30 NEEDS 16 M235062_99#JOBSLOTS PROMPT PRMT3 B236153_00#JOB_FTA FOLLOWS JOBMDM END
See also
For the equivalent Job Scheduling Console task, see the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
136
Job stream definition keyword details

This section describes the job stream definition keywords listed in table 29.
137
job stream keywords - at
at
Specifies a time dependency. If the at keyword is set then the job or job stream cannot start before the time set in this keyword. Syntax: at time [timezone|tz tzname][+n day[s]] [,...] Arguments: time Specifies a time of day. Possible values can range from 0000 to 2359.
tzname Specifies the time zone to be used when computing the start time. See Chapter 12, Managing time zones, on page 461 for time zone names. The default is the time zone of the workstation on which the job or job stream is launched. Note: If an at time and an until or deadline time are specified, the time zones must be the same. n Specifies an offset in days from the scheduled start date and time.
Comments: If an at time is not specified for a job or job stream, its launch time is determined by its dependencies and priority and its position in the preproduction plan is determined by the value assigned to the schedtime keyword. For more information about the schedtime keyword refer to schedtime on page 171. The time value in the at option is considered as follows: v If the time value is less than the value set in the startOfDay global option, it is taken to be for the following day. v If the time value is greater than the value set in the startOfDay global option, it is taken to be for the current day. If neither the at nor the schedtime keywords are specified in the job stream definition then, by default, the job or job stream instance is positioned in the plan at the time specified in the startOfDay global option. Examples: The following examples assume that the Tivoli Workload Scheduler processing day starts at 6:00 a.m. v The following job stream, selected on Tuesdays, is launched no sooner than 3:00 a.m. Wednesday morning. Its two jobs are launched as soon as possible after that time.
schedule sked7 on tu at 0300: job1 job2 end
v The time zone of workstation sfran is defined as America/Los_Angeles, and the time zone of workstation nycity is defined as America/New_York. The following job stream is selected to run on Friday. It is launched on workstation sfran at 10:00 a.m. America/Los_Angeles Saturday. job1 is launched on sfran as soon as possible after that time. job2 is launched on sfran at 2:00 p.m. America/New_York (11:00 a.m. America/Los_Angeles) Saturday. job3 is launched on workstation nycity at 4:00 p.m. America/New_York (1:00 p.m. America/Los_Angeles) Saturday.
sfran#schedule sked8 on fr at 1000 + 1 day: job1 job2 at 1400 tz America/New_York nycity#job3 at 1600 end
138
job stream keywords - carryforward
carryforward
Makes a job stream eligible to be carried forward to the next production plan if it is not completed before the end of the current production plan. Syntax: carryforward Examples: The following job stream is carried forward if its jobs have not completed before preproduction processing begins for a new production time frame.
schedule sked43 on th carryforward : job12 job13 job13a end
139
job stream keywords - comment
comment
Includes comments in a job stream definition and the jobs contained in a job stream. Syntax: # text Comments: Inserts a comment line. The first character in the line must be an pound sign #. You can add comments in a job stream definition immediately after the line with the schedule keyword, or in a job contained in a job stream definition immediately after the job statement line. Examples: The following example includes both types of comments:
schedule wkend on fr at 1830 ########################## # The weekly cleanup jobs ########################## # carryforward : job1 # final totals and reports job2 # update database end
140
job stream keywords - confirmed
confirmed
Specifies that a jobs completion must be confirmed by running a conman confirm command. See confirm on page 278 for more information. Syntax: confirmed Examples: In the following job stream, confirmation of the completion of job1 must be received before job2 and job3 are launched.
schedule test1 on fr: job1 confirmed job2 follows job1 job3 follows job1 end
141
job stream keywords - deadline
deadline
Specifies the time within which a job or job stream must complete. Jobs or job streams that have not yet started or that are still running when the deadline time is reached, are considered late in the plan. When a job (or job stream) is late, the following actions are performed: v Job is shown as late in conman and Job Scheduling Console. v An event is sent to the Tivoli Enterprise Console and the IBM Tivoli Business Systems Manager. v A message is issued to the stdlist and console logs. Note: When using the deadline keyword, ensure the bm check deadline variable is set to a value higher than 0 in the localopts configuration file on the target workstations for the job or job stream. For information, refer to IBM Tivoli Workload Scheduler Planning and Installation Guide. Syntax: deadline time [timezone|tz tzname][+n day[s] [,...] Arguments: time Specifies a time of day. Possible values range from 0000 to 2359.
tzname Specifies the time zone to be used when computing the deadline. See Chapter 12, Managing time zones, on page 461 for time zone names. The default is the time zone of the workstation on which the job or job stream is launched. n Specifies an offset in days from the scheduled deadline time.
Note: If a deadline time and an until or at time are specified, the time zones must be the same. Examples: The following example launches job stream sked7 every day and job jobc to start running at 14:30 and to be completed by 16:00.
schedule sked7 on everyday : jobc at 1430 deadline 1600 end
142
job stream keywords - description
description
Includes a description for the job stream. Syntax: description text Comments: The maximum length of this field is 120 characters. Examples:
schedule test1 description Revenue at the end of the month on monthend : job1 job2 job3 end
143
job stream keywords - draft
draft
Marks a job stream as draft. A draft job stream is not added to the preproduction plan. Syntax: draft Comments: A draft job stream is not considered when resolving dependencies and is not added to the production plan. After removing the draft keyword from a job stream you need to run JnextPlan command to add the job stream to the preproduction plan and so to the production plan. Examples:
schedule test1 on monthend draft : job1 job2 job3 end
144
job stream keywords - end
end
Marks the end of a job stream definition. Syntax: end Examples:
schedule test1 on monthend : job1 job2 job3 end << end of job stream >>
145
job stream keywords - every
every
Defines the repetition rate for a job. The job is launched repeatedly at the specified rate. If the job has a dependency that is not satisfied, the iteration is started only when the dependency is satisfied. Syntax: every rate Arguments: rate The repetition rate expressed in hours and minutes, in the format: hhmm. (The rate can be greater than 24 hours.)
Comments: If an every job abends , the iteration continues. If the every option is used without the at dependency, the rerun jobs scheduled respecting the every rate specified, starting from the time when the job actually started. IF AND ONLY IF the every option is used with the at dependency AND one rerun is delayed (for a dependency or for any other reason) THEN, while Tivoli Workload Scheduler realigns to the at time, there might one or two iterations that do not respect the every rate. For all other cases the every rate is always respected. In the example2 it is explained how Tivoli Workload Scheduler realigns to the at time if the job starts later than the at time set and a some iterations get lost. Examples: 1. The following example runs the job testjob every hour:
testjob every 100
2. The following example shows the job testjob1 that is stated to run every 15 minutes, between the hours of 6:00 p.m. and 8:00 p.m.:
testjob1 at 1800 every 15 until 2000
The job is supposed to run at 1800, 1815, 1830, and so on. If the job is submitted adhoc at 1833, the reruns are at 1833, 1834, 1845 and so on. Here it follows the explanation of the reason why the job iterations runs at 1833, 1834, 1845 and so on. At first notice that in a job there are two time values to consider: v the start_time, that is the time when the job is expected to run, it is set to the at time specified for the job or to the time when the rerun should be launched. This value can be viewed using conman showjobs before the job iteration starts. v the time_started, that is the time when the job actually starts, for example 1833. This value can be viewed it is displayed by using conman showjobs after the job iteration started. Because the job testjob1 was submitted adhoc at 1833, these are the information that you see immediately after the submission occurred: using conman showjobs TESTJOB1 HOLD 1800 in the Symphony file start_time=1800 (because the job is expected to run at 1800)
146
job stream keywords - every

time_started=NULL (because the job has not yet started) Since the start_time (1800) is smaller that the current time (1833), the job testjob1 will start immediately and the updated information become: using conman showjobs TESTJOB1 SUCC 1833 in the Symphony file start_time=1800 (because the job was expected to run at 1800) time_started=1833 (because the job started at 1833) When batchman calculates the time for the next iteration, it uses the following data: start_time=1800 rate=0015 current_time=1833 since the next iteration time (1800+0015=1815) would still be sooner than the current_time value (1833), batchman identifies the last planned iteration that was not run by adding to the start_time as many every_rate as possible without exceeding the current_time 1800 + 0015 + 0015 = 1830 < 1833 and then issues to run that iteration. Assumed that this iteration is run at 1834 the information, after the job starts, become the following: using conman showjobs TESTJOB1 SUCC 1834 in the Symphony file start_time=1830 (because that job iteration was expected to run at 1830) time_started=1834 (because that job iteration started at 1834) After this job iteration completed, batchman calculates again the time the next iteration has to start using these updated values: start_time=1830 rate=0015 current_time=1834 The fact that the next iteration time (1830+0015=1845) is later than the current_time value (1834), indicates to batchman that the iteration is recovered and so the iteration time starting from 1845 on can be realigned with the planned iteration times set in the job definition by the keyword at and every. 3. The following example does not start the job testjob2 iteration until the job testjob1 has completed successfully:
testjob2 every 15 follows testjob1
147
job stream keywords - except
except
Defines the dates that are exceptions to the on dates of a job stream. See on on page 161 for more information. Syntax: except [runcycle name] [validfrom date] [validto date] [description text] {date|day|calendar|request|icalendar} [,...] [fdignore|fdnext|fdprev] Arguments: fdignore|fdnext|fdprev Specifies a rule that must be applied when the date selected for exclusion falls on a freeday. It can be one of the following: fdignore Do not exclude the date. fdnext Exclude the nearest workday after the freeday. fdprev Exclude the nearest workday before the freeday. For explanation about remaining keywords contained in the except syntax refer to on on page 161. Comments: You can define multiple instances of the except keyword for the same job stream. Each instance is equivalent to a run cycle to which you can associate a freeday rule. Multiple except instances must be consecutive within the job stream definition. Each instance of the keyword can contain any of the values allowed by the except syntax. Examples: The following example selects job stream testskd2 to run every weekday except those days whose dates appear on calendars named monthend and holidays:
schedule testskd2 on weekdays except monthend,holidays
The following example selects job stream testskd3 to run every weekday except May 15, 2005 and May 23, 2005:
schedule testskd3 on weekdays except 05/15/2005,05/23/2005
The following example selects job stream testskd4 to run every day except two weekdays prior to any date appearing on a calendar named monthend:
schedule testskd4 on everyday except monthend-2 weekdays
148
job stream keywords - except

Select job stream sked4 to run on Mondays, Tuesdays, and 2 weekdays prior to each date listed in the monthend calendar. If the run date is a freeday, run the job stream on the nearest following workday. Do not run the job stream on Wednesdays.
schedule sked4 on mo on tu, MONTHEND -2 weekdays fdnext except we
Select job stream testskd2 to run every weekday except for the days listed in monthend. If a date in monthend falls on a freeday, exclude the nearest workday before it. In this example, the freedays are Saturdays, Sundays, and all the dates listed in the default holidays calendar .
schedule testskd2 on weekdays except MONTHEND fdprev
149
job stream keywords - follows
follows
Defines the other jobs and job streams that must complete successfully before a job or job stream is launched. Comments: Use the following syntax for job streams: [follows {[netagent::][workstation#]jobstreamname[.jobname |@] [previous|sameday|relative from [+] time to [+] time|from time [+n day[s]] to time [+n day[s]] Use the following syntax for jobs: [follows {[netagent::][workstation#]jobstreamname{.jobname | @} [previous|sameday|relative from [+] time to [+] time | from time [+n day[s]] to time [+n day[s]] Arguments: netagent workstation The name of the network agent where the internetwork dependency is defined. The workstation on which the job or job stream that must have completed runs. The default is the same workstation as the dependent job or job stream. If a workstation is not specified with netagent, the default is the workstation to which the network agent is connected. jobstreamname time jobname The name of the job stream that must have completed. For a job, the default is the same job stream as the dependent job. Specifies a time of day. Possible values range from 0000 to 2359. The name of the job that must have completed. An at sign (@) can be used to indicate that all jobs in the job stream must complete successfully.
Comments: Dependency resolution criteria define how the job stream or job referenced by an external follows dependency is matched to a specific job stream or job instance in the plan. Because the plan allows the inclusion of multiple instances of the same job or job stream, you can identify the instance that resolves the external follows dependency based on the following resolution criteria: Closest Preceding The job or job stream instance that resolves the dependency is the closest preceding the instance that includes the dependency. Same Day The job or job stream instance that resolves the dependency is the closest one in time scheduled to start on the day when the instance that includes the dependency is scheduled to run. Within a Relative Interval The job or job stream instance that resolves the dependency is the closest one in a time interval of your choice, which is defined relatively to the scheduled start time of the dependent instance.
150
job stream keywords - follows

Within an Absolute Interval The job or job stream instance that resolves the dependency is the closest one in a time interval of your choice. The time interval is not related to the scheduled start time of the dependent instance. Regardless of which matching criteria are used, if multiple instances of potential predecessor job streams exist in the specified time interval, the rule used by the product to identify the correct predecessor instance is the following: 1. Tivoli Workload Scheduler searches for the closest instance that precedes the depending job or job stream start time. If such an instance exists, this is the predecessor instance. 2. If there is no preceding instance, Tivoli Workload Scheduler considers the correct predecessor instance as the closest instance that starts after the depending job or job stream start time. For more information and examples on how external follows dependencies are resolved in the plan refer to Managing external follows dependencies for jobs and job streams on page 59. Examples: The following example specifies to not launch job stream skedc until the closest preceding job stream instance sked4 on workstation site1 have completed successfully:
schedule skedc on fr follows site1#sked4 previous
The following example specifies to not launch job stream skedc until the job stream instance of sked4 on workstation site1 that run between 12:00 of 3 days before to 3:00 of the day after have completed successfully:
schedule skedc on fr follows site1#sked4 from 1200 3 days to 0300 1 day
The following example specifies not to launch job stream skedc until job stream sked4 on workstation site1 and job joba in job stream sked5 on workstation site2 have completed successfully:
schedule skedc on fr follows site1#sked4,site2#sked5.joba
Do not launch sked6 until jobx in the job stream skedx on network agent cluster4 has completed successfully:
sked6 follows cluster4::site4#skedx.jobx
The following example specifies not to launch jobd until joba in the same job stream, and job3 in job stream skeda have completed successfully:
jobd follows joba,skeda.job3
151
job stream keywords - freedays
freedays
Use freedays to specify the name of a freedays calendar that lists the days when the job stream should not run. Tivoli Workload Scheduler uses this calendar as the base calendar for calculating workdays for the job stream. The keyword affects only the scheduling of the job streams for which it is specified. Syntax: freedays Calendar_Name [-sa] [-su] Arguments: Calendar_Name The name of the calendar that must be used as the freedays calendar for the job stream. If Calendar_Name is not in the database, Tivoli Workload Scheduler issues a warning message when you save the job stream. If Calendar_Name is not in the database when the command schedulr runs, Tivoli Workload Scheduler issues an error message and uses the default calendar holidays in its place. Do not use the names of weekdays for the calendar names. -sa -su Saturdays are workdays. Sundays are workdays.
Comments: If you specify a freedays calendar in the job stream definition, then the workdays keyword takes the following value: workdays = everyday excluding saturday and sunday (unless you specified -sa or -su along with freedays) and excluding all the dates of Calendar_Name If you do not specify freedays in the job stream definition, then: workdays = everyday excluding saturday and sunday and all the dates of the holidays calendar By default, saturday and sunday are considered as freedays unless you specify the contrary by adding -sa, -su or both after Calendar_Name. Examples: Select job stream sked2 to run on 01/01/2005 and on all workdays as long as they are not listed in the freedays calendar named GERMHOL.
schedule sked2 freedays GERMHOL on 01/01/2005, workdays
Select job stream sked3 to run two workdays before each date in the PAYCAL calendar. Workdays are every day from Monday to Saturday as long as they are not listed in the freedays calendar named USAHOL.
schedule sked3 freedays USAHOL -sa on PAYCAL -2 workdays
Select job stream sked3 on the dates listed in the APDATES calendar. If the selected date is a freeday, do not run the job stream. In this example, Sundays and all the dates listed in the GERMHOL calendar are to be considered as freedays. All days from Monday to Saturday, except for the dates listed in GERMHOL, are workdays.
schedule sked3 freedays GERMHOL -sa on APDATES fdignore
152
job stream keywords - freedays

Select job stream testsked3 to run every weekday except 5/15/2005 and 5/23/2006. If 5/23/2006 is a freeday, do not exclude it. In this example, Saturdays, Sundays, and all the dates listed in GERMHOL are to be considered as freedays. All days from Monday to Friday, except for the dates listed in GERMHOL, are workdays.
schedule testskd3 freedays GERMHOL on weekdays except 5/15/2005 fdignore except 5/23/2006
Select job stream testsked4 to run every day except two weekdays prior to every date listed in the MONTHEND calendar. If the date to be excluded is a freeday, do not exclude it, but exclude the nearest following workday. In this example, freedays are all the dates listed in USAHOL, while workdays are all the days from Monday to Sunday that are not listed in USAHOL.
schedule testskd4 freedays USAHOL -sa -su on everyday except MONTHEND -2 weekdays fdnext
153
job stream keywords - job statement
job statement
Jobs can be defined in the database independently (as described in Job definition on page 119), or as part of job streams. In either case, the changes are made in the database and do not affect the production plan until the start of a new production plan. Syntax: To define a job as part of a job stream, use the following syntax inside the job stream definition: [workstation#]jobname [as newname] {scriptname filename | docommand command} streamlogon username [description description] [tasktype tasktype] [interactive] [rccondsucc Success Condition] [recovery {stop | continue | rerun} [after [workstation#]jobname] [abendprompt text] ] To use a job already defined in the database in the job stream definition define job statement using the following syntax: [workstation#]jobname [as newname] Arguments: as The name you want to use to refer to the job instance within that job stream.
For the other keywords refer to Job definition on page 119. Comments: When defining a job as part of a job stream as the job stream definition is added to the database also the new job definition is added and can be referenced, from that moment on, also from other job streams. Note: Wrongly typed keywords used in job definitions lead to truncated job definitions stored in the database. In fact the wrong keyword is considered extraneous to the job definition and so it is interpreted as the job name of an additional job definition. Usually this misinterpretation causes also a syntax error or an inexistent job definition error for the additional job definition. When a job stream is added or modified, the attributes or recovery options of its jobs are also added or modified. Remember that when you add or replace a job stream, any job modifications affect all other job streams that use the jobs. Note that the cross reference report, xref, can be used to determine the names of the job streams including a specific job. For more information about cross reference report refer to xref on page 424. Note: Jobs scheduled to run on workstations marked as ignored, and belonging to job streams scheduled to run on active workstations, are added to the plan even though they are not processed. Examples: The following example defines a job stream with three previously defined jobs:
154
job stream keywords - job statement

schedule bkup on fr at 20:00 : cpu1#jbk1 cpu2#jbk2 needs 1 tape cpu3#jbk3 follows jbk1 end
The following job stream definition contains job statements that add or modify the definitions of two jobs in the database:
schedule sked4 on mo : job1 scriptname d:\apps\maestro\scripts\jcljob1 streamlogon jack recovery stop abendprompt continue production site1#job2 scriptname d:\apps\maestro\scripts\jcljob2 streamlogon jack follows job1 end
155
job stream keywords - keyjob
keyjob
The keyjob keyword is used to mark a job as key or critical in both the database and in the plan and for monitoring by applications, such as Tivoli Business Systems Manager or Tivoli Enterprise Console. See the IBM Tivoli Workload Scheduler Planning and Installation Guide for information about enabling the key flag mechanism. Syntax: keyjob Examples: The following example
SCHEDULE cpu1#sched1 ON everyday KEYSCHED AT 0100 cpu1#myjob1 KEYJOB END
156
job stream keywords - keysched
keysched
The keysched keyword is used to mark a job stream as key or critical in both the database and in the plan and for monitoring by applications, such as Tivoli Business Systems Manager. See the IBM Tivoli Workload Scheduler Planning and Installation Guide for information about enabling the key flag mechanism. Syntax: keysched Examples: The following example :
SCHEDULE cpu1#sched1 ON everyday KEYSCHED AT 0100 cpu1#myjob1 KEYJOB END
157
job stream keywords - limit
limit
The limit keyword limits the number of jobs that can run simultaneously in a job stream on the same CPU. Syntax: limit joblimit Arguments: joblimit Specifies the number of jobs that can be running at the same time in the job stream. Possible values are 0 through 1024. If you specify 0, you prevent all jobs from being launched even the one with priority set to GO.
Examples: The following example limits to five the number of jobs that can run simultaneously in job stream sked2:
schedule sked2 on fr limit 5 :
158
job stream keywords - matching
matching
Sets a default for the matching criteria to be used in all follows dependencies where a matching criteria is not set in the job stream definition or in the jobs contained in the job stream. Syntax: matching {previous |sameday | relative from [+] time to [+] time Arguments: For information about the keyword used with matching see the follows on page 150 keyword. Examples: The following example shows the definition of job stream SCHED2 that: v Contains a job1 that can be run today only if it was run yesterday. v Needs the instance of job stream SCHED1 running the same day to complete before running.
SCHEDULE PDIVITA1#SCHED2 ON RUNCYCLE RULE1 "FREQ=DAILY;" ON RUNCYCLE CALENDAR2 CAL1 MATCHING PREVIOUS FOLLOWS PDIVITA1#SCHED1.@ SAMEDAY FOLLOWS PDIVITA1#SCHED2.JOB1 : PDIVITA1#JOB1 PDIVITA1#JOB2 END
In this sample the external follows dependency from PDIVITA1#SCHED2.JOB1 inherits the matching criteria specified in the matching keyword.
159
job stream keywords - needs
needs
The needs keyword defines resources that must be available before a job or job stream is launched. You can use the needs keyword either in a job stream definition or in the definition of the contained jobs, not in both. Syntax: needs [n] [workstation#]resourcename [,...] Arguments: n workstation Specifies the number of resource units required. Possible values are 1 to 1024 for each needs statement. The default is 1. Specifies the name of the workstation on which the resource is locally defined. If not specified, the default is the workstation where the dependent job or job stream runs. Resources can be used as dependencies only by jobs and job streams that run on the workstation where the resource is defined. However, a standard agent and its host can reference the same resources. Specifies the name of the resource.
resourcename
Comments: A job or job stream can request a maximum of 1024 units of a resource in a needs statement. At run time, each needs statement is converted in holders, each holding a maximum of 32 units of a specific resource. Independently from the amount of available units of the resource, for a single resource there can be a maximum of 32 holders. If 32 holders are already defined for a resource, the next job or job stream waiting for that resource waits until a current holder terminates AND the needed amount of resource becomes available. Examples: The following example prevents job stream sked3 from being launched until three units of cputime, and two units of tapes become available:
schedule sked3 on fr needs 3 cputime,2 tapes :
The jlimit resource has been defined with two available units. The following example allows no more than two jobs to run concurrently in job stream sked4:
schedule sked4 joba needs 1 jobb needs 1 jobc needs 2 jobd needs 1 end on mo,we,fr : jlimit jlimit jlimit <<runs alone>> jlimit
160
job stream keywords - on
on
This is a job stream keyword that defines when and how often a job stream is selected to run. If omitted the job stream is not added to the preproduction plan. The on keyword must follow the schedule keyword. See except on page 148 for more information. Syntax: on [runcycle name] [validfrom date] [validto date] [description text] {date|day|calendar|request|icalendar} [,...] [fdignore|fdnext|fdprev] Arguments: runcycle name Specifies a label with a friendly name for the run cycle specified in the following lines. validfrom date ... validto date Delimits the time frame during which the job stream is active, that is the job stream is added to the production plan. description text Contains a description of the run cycle. date Specifies a run cycle that runs on specific dates. The syntax used for this type is: yyyymmdd [,yyyymmdd][,...]For example, for a job stream that is scheduled to run on the 25th of May 2006 and on the 12th of June 2006 the value is:
on 20060525,20060612
day
Specifies a run cycle that runs on specific days. The syntax used for this type is: {mo|tu|we|th|fr|sa|su}For example, for a job stream that is scheduled to run every Monday the value is:
on mo
calendar The dates specified in a calendar with this name. The calendar name can be followed by an offset in the following format: {+ | -}n {day[s] | weekday[s] | workday[s]} Where: n days The number of days, weekdays, or workdays. Every day of the week.
weekdays Every day of the week, except Saturday and Sunday. workdays Every day of the week, except for Saturdays and Sundays (unless
161

otherwise specified with the freedays keyword) and for the dates marked either in a designated freedays calendar or in the holidays calendar. request Selects the job stream only when requested. This is used for job streams that are selected by name rather than date. To prevent a scheduled job stream from being selected for JnextPlan, change its definition to ON REQUEST. Note: When attempting to run a job stream that contains on request times, consider that: v On request always takes precedence over at. v On request never takes precedence over on. icalendar Represents a standard used to specify a recurring rule that describes when a job stream runs. The syntax used for run cycle with type icalendar is the following: FREQ={DAYLY|WEEKLY|MONTHLY|YEARLY} [;INTERVAL=[-]n] [;{BYFREEDAY|BYWORKDAY|BYDAY=weekday_list| BYMONTHDAY=monthday_list}] where the default value for keyword INTERVAL is 1. Using icalendar you can specify that a job stream runs: every n days by using the following format: FREQ=DAILY[;INTERVAL=n] where the value set for validfrom is the first day of the resulting dates. For example, for a job stream that is scheduled to run daily the value is:
FREQ=DAILY
For a job stream that is scheduled to run every second day the value is:
FREQ=DAILY;INTERVAL=2
every free or work days by using the following format: FREQ=DAILY[;INTERVAL=n];BYFREEDAY|BYWORKDAY For example, for a job stream that is scheduled to run every freeday the value is:
FREQ=DAILY;BYFREEDAY
For a job stream that is scheduled to run every second workday the value is:
FREQ=DAILY;INTERVAL=2;BYWORKDAY
every n weeks on specific weekdays by using the following format: FREQ=WEEKLY[;INTERVAL=n];BYDAY=weekday_list
162

where the value set for weekday_list is
[SU][,MO][,TU][,WE][,TH][,FR][,SA]
For example, for a job stream that is scheduled to run every week on Friday and Saturday the value is:
FREQ=WEEKLY;BYDAY=FR,SA
For a job stream that is scheduled to run every three weeks on Friday the value is:
FREQ=WEEKLY;INTERVAL=3;BYDAY=FR
every n months on specific dates of the month by using the following format: FREQ=MONTHLY[;INTERVAL=n];BYMONTHDAY=monthday_list where the value set for monthday_list is represented by a list of
[+number_of_day_from_beginning_of_month] [number_of_day_from_end_of_month] [number_of_day_of_the_month]
. For example, for a job stream that is scheduled to run monthly on the 27th day the value is:
FREQ=MONTHLY;BYMONTHDAY=27
For a job stream that is scheduled to run every six months on the 15th and on the last day of the month the value is:
FREQ=MONTHLY;INTERVAL=6;BYMONTHDAY=15,-1
every n months on specific days of specific weeks by using the following format: FREQ=MONTHLY[;INTERVAL=n];BYDAY=day_of_m_week_list where the value set for day_of_m_week_list is represented by a list of
[+number_of_week_from_beginning_of_month] [number_of_week_from_end_of_month] [weekday]
For example, for a job stream that is scheduled to run monthly on the first Monday and on the last Friday the value is:
FREQ=MONTHLY;BYDAY=1MO,-1FR
For a job stream that is scheduled to run every six months on the 2nd Tuesday the value is:
FREQ=MONTHLY;INTERVAL=6;BYDAY=2TU
every n years by using the following format: FREQ=YEARLY[;INTERVAL=n] where the value set for validfrom is the first day of the resulting dates. For example, for a job stream that is scheduled to run yearly the value is:
FREQ=YEARLY
163

For a job stream that is scheduled to run every two years the value is:
FREQ=YEARLY;INTERVAL=2
fdignore|fdnext|fdprev Indicates the rule to be applied if the date selected for running the job or job stream falls on a freeday. The available settings are: fdignore Do not add the date. fdnext Add the nearest workday after the freeday. fdprev Add the nearest workday before the freeday. Comments: You can define multiple instances of the on keyword for the same job stream. Multiple on instances must be consecutive within the job stream definition. Each instance is equivalent to a run cycle to which you can associate a freeday rule. Each instance of the keyword can contain any of the values allowed by the on syntax. Examples: The following example selects job stream sked1 on Mondays and Wednesdays:
schedule sked1 on mo,we
The following example selects job stream sked3 on June 15, 1999, and on the dates listed in the apdates calendar:
schedule sked3 on 6/15/99,apdates
The following example selects job stream sked4 two weekdays before each date appearing in the monthend calendar:
schedule sked4 on monthend -2 weekdays
The following example selects job stream testskd1 every weekday except on Wednesdays:
schedule testskd1 on weekdays except we
The following example selects job stream testskd3 every weekday except May 15, 2005 and May 24, 2005:
schedule testskd3 on weekdays except 05/16/2005,05/24/2005
The following example selects job stream testskd4 every day except two weekdays prior to any date appearing in a calendar named monthend:
schedule testskd4 on everyday except monthend -2 weekdays
Select job stream sked1 to run all Mondays, Fridays, and on 29/12/2005. If Mondays and 29/12/2005 are freedays, run the job stream on the nearest following workday. If Fridays are freedays, run the job stream on the nearest preceding day. In this example, the freedays are Saturdays, Sundays, and all the dates listed in the default HOLIDAYS calendar. Workdays are all days from Monday to Friday if they are not listed in the HOLIDAYS calendar.
164

schedule sked1 on mo, 12/29/2005 fdnext on fr fdprev
This example shows the output of the display command of job stream testcli defined to run on different run cycles on workstation site2:
display js=site2#testcli
obtained in 120-column format by setting MAESTROCOLUMNS=120 before accessing the composer command-line:
JobstreamName Workstation Draft ValidFrom ValidTo UpdatedBy UpdatedOn LockedBy ------------- ----------- ----- -------- ------- --------- --------- -------TESTCLI SITE2 Y 08/25/2005 mdmDBE4 08/25/2005 mdmDBE4 SCHEDULE W5#TESTCLI VALIDFROM 08/25/2005 TIMEZONE ACT DESCRIPTION "Job stream with several run cycle settings." DRAFT ON RUNCYCLE M5 VALIDFROM 08/25/2005 DESCRIPTION "monthly" "FREQ=MONTHLY;INTERVAL=5;BYMONTHDAY=-3,1" ( START 0000 ) ON RUNCYCLE W4 VALIDFROM 08/25/2005 DESCRIPTION "weekly" "FREQ=WEEKLY;INTERVAL=5;BYDAY=MO,WE" FDNEXT ( START 0000 ) ON RUNCYCLE D3 VALIDFROM 08/25/2005 DESCRIPTION "daily" "FREQ=DAILY;INTERVAL=2" FDPREV ( START 0000 ) ON RUNCYCLE C2 VALIDFROM 08/25/2005 DESCRIPTION "calendar" ITALY +2 DAYS ( START 0000 ) ON RUNCYCLE M6 VALIDFROM 08/25/2005 DESCRIPTION "monthly" "FREQ=MONTHLY;INTERVAL=2;BYDAY=1MO,1TH,2WE" ( START 0000 +2 DAYS ) ON RUNCYCLE Y7 VALIDFROM 08/25/2005 DESCRIPTION "yearly" "FREQ=YEARLY;INTERVAL=7" ( AT 0100 ) ON RUNCYCLE SS1 VALIDFROM 08/25/2005 08/10/2005,08/18/2005,08/20/2005,08/25/2005 ( AT 0000 UNTIL 0000 +1 DAYS ONUNTIL SUPPR DEADLINE 0000 +2 DAYS ) EXCEPT RUNCYCLE S1 VALIDFROM 08/25/2005 DESCRIPTION "simple" 08/26/2005,08/28/2005,08/30/2005,09/13/2005 ( AT 0000 ) CARRYFORWARD MATCHING SAMEDAY FOLLOWS LAB235004#SROBY2.@ FOLLOWS X8#COPYOFJS2.RR FOLLOWS XA15::TPA KEYSCHED LIMIT 22 PRIORITY 15 : X8#PIPPO AS JOBTC CONFIRMED PRIORITY 13 KEYJOB FOLLOWS W5#POPO.@
165

FOLLOWS X8#JS2.F3 END AWSBIA291I Total objects: 1
The calendar ITALY is a custom calendar defined in the database that sets the workdays and holidays of the calendar in use in Italy.
166
job stream keywords - opens
opens
Specifies files that must be available before a job or job stream can be launched. Syntax: opens [workstation#]filename [(qualifier)] [,...] Arguments: workstation Specifies the name of the workstation or workstation class on which the file exists. The default is the workstation or workstation class of the dependent job or job stream. If you use a workstation class, it must be the same as that of the job stream that includes this statement. filename Specifies the name of the file, enclosed in quotation marks. You can use Tivoli Workload Scheduler parameters as part or all of the file name string. If you use a parameter, it must be enclosed in carets (^). The file name must be fully qualified for all workstation types with the exception of extended agents (XAs), where this is not a requirement. qualifier Specifies a valid test condition. In UNIX, the qualifier is passed to a test command, which runs as root in bin/sh. In Windows, the test function is performed as the Tivoli Workload Scheduler user. The valid qualifiers are: -d %p -e %p -f %p -r %p -s %p -w %p -a -o True if the file exists and is a directory. True if the file exists. True if the file exists and is a regular file. True if the file exists and is readable. True if the file exists and its size is greater than zero. True if the file exists and is writable. Boolean operator AND. Boolean operator OR.
In both UNIX and Windows, the expression %p, is used to pass the value assigned to filename to the test function. Entering (notempty) is the same as entering (-s %p). If no qualifier is specified, the default is (-f %p). Comments: The combination of the path of the file and the qualifiers cannot exceed 120 characters, and the name of the file cannot exceed 28 characters. Examples: The following example checks to see that file c:\users\fred\ datafiles\file88 on workstation nt5 is available for read access before launching ux2#sked6:
schedule ux2#sked6 on tu opens nt5#"c:\users\fred\datafiles\file88"
The following example checks to see if three directories, /john, /mary, and /roger, exist under /users before launching job jobr2:
jobr2 opens "/users"(-d %p/john -a -d %p/mary -a -d %p/roger)
167
job stream keywords - opens

The following example checks to see if cron has created its FIFO file before launching job job6:
job6 opens "/usr/lib/cron/FIFO"(-p %p)
The following example checks to see that file d:\work\john\execit1 on workstation dev3 exists and is not empty, before running job jobt2:
jobt2 opens dev3#"d:\work\john\execit1"(notempty)
The following example checks to see that file c:\tech\checker\startf on workstation nyc exists, is not empty, and is writable, before running job job77:
job77 opens nyc#"C:\tech\checker\startf"(-s %p -a -w %p)
Security for test(1) Commands: In UNIX, a special security feature prevents unauthorized use of other commands in the qualifier. For example, the file below contains a command in the qualifier:
/users/xpr/hp3000/send2(-n "`ls /users/xpr/hp3000/m*`" -o -r %p)
If the qualifier contains another command, the following checks are made: v The local option jm no root must be set to no. v In the security file, the user documenting the schedule or adding the Open Files dependency with a conman adddep command, must have submit access to a job with the following attributes: name=cmdstest.fileeq logon=root jcl=the path of the opens files cpu=the CPU on which the opens files reside Note that cmdstest and fileeq do not exist.
168
job stream keywords - priority
priority
Sets the priority of a job or job stream. By assigning a different priority to jobs or job streams you determine which one starts first, if the dependencies are solved. Assuming the jobs and job streams are ready to be launched , if you set a priority for the job streams and for the jobs in the job streams: v The job stream that starts first is the one with the highest priority. v Among the jobs in the job stream with the highest priority, the job that starts first is the one with the highest priority. Syntax: priority number | hi | go Arguments: number hi go Specifies the priority. Possible values are 0 through 99. A priority of 0 prevents the job or job stream from launching. Represents a value higher than any value that can be specified with a number. Represents the highest priority that can be set, when set commands the immediate launch of the job or job stream it is free from other dependencies.
Examples: The following example shows the relationship between job stream and job priorities. The two job streams, sked1 and sked2 have the following definitions in the database:
schedule sked1 on tu priority 50 : job1 priority 15 job2 priority 10 end schedule sked2 on tu priority 10 : joba priority 60 jobb priority 50 end
Since the job stream sked1 has the highest priority then the jobs are launched in the following order: job1, job2, joba, jobb. If, instead, the job stream priorities are the same, the jobs are launched in the following order: joba, jobb, job1, job2. If job2 has a dependency A and job1 has a dependency B and the dependency A becomes solved (while B remains not solved) then job2 starts before job1 even though job2 has a priority lower than the one set for job1.
169
job stream keywords - prompt
prompt
Specifies prompts that must be answered affirmatively before a job or job stream is launched. Syntax: prompt promptname [,...] prompt [: | !]text [,...] Arguments: promptname Specifies the name of a prompt in the database. You can specify more than one promptname separated by commas but you cannot mix under the same prompt keyword prompts defined in the database with literal prompts. Specifies a literal prompt as a text string enclosed in quotes (). Multiple strings separated by backlash n (\n) can be used for long messages. If the string begins with a colon (:), the message is displayed but no reply is necessary. If the string begins with an exclamation mark (!), the message is displayed, but it is not recorded in the log file. You can include backslash n (\n) within the text for new lines. You can use one or more parameters as part or all of the text string. To use a parameter, place its name between carets (^). Note: Within a local prompt, when not specifying a parameter, carets (^) must be preceded by a backslash (\) or they cause errors in the prompt. Within global prompts, carets do not have to be preceded by a backslash. Examples: The following example shows both literal and named prompts. The first prompt is a literal prompt that uses a parameter named sys1. When a single affirmative reply is received for the prompt named apmsg, the dependencies for both job1 and job2 are satisfied.
schedule sked3 on tu,th prompt "All ap users logged out of ^sys1^? (y/n)" : job1 prompt apmsg job2 prompt apmsg end
text
The following example defines a literal prompt that appears on more than one line. It is defined with backlash n (\n) at the end of each line:
schedule sked5 on fr prompt "The jobs in this job stream consume \n an enormous amount of cpu time.\n Do you want to launch it now? (y/n)" : j1 j2 follows j1 end
170
job stream keywords - schedtime
schedtime
Represents the time when the job stream is positioned in the plan. The value assigned to schedtime does not represent a dependency for the job stream. While the production plan is in process, the job or job stream instance might start processing before the time set in the schedtime keyword if all its dependencies are resolved and if its priority allows it to start. Syntax: schedtime time [timezone|tz tzname][+n day[s]] [,...] Arguments: time Specifies a time of day. Possible values are from 0000 to 2359.
tzname Specifies the time zone to be used when calculating the start time. See Chapter 12, Managing time zones, on page 461 for time zone names. The default is the time zone of the workstation on which the job or job stream is launched. n Specifies an offset in days from the scheduled start date and time.
Comments: Differently from the at key, the schedtime key does not represent a time dependency, that is it does not state a time before which a job or job stream cannot start. Instead, the value specified in the schedtime keyword is used only to position the specific job or job stream instance in the preproduction plan. While the production plan is in process, the job or job stream instance might start processing before the time set in the schedtime keyword if all its dependencies are resolved and if its priority allows it to start. For an explanation on how the schedtime keyword is used to identify predecessors in the preproduction plan, refer to Managing external follows dependencies for jobs and job streams on page 59. The at and schedtime keywords are mutually exclusive. If schedtime is not specified and the at keyword is specified in the job or job stream, then its value is used to position the instance in the preproduction plan. If neither the at nor the schedtime keywords are specified in the job or job stream definition, it is assumed by default to be the value assigned to the startOfDay global option set on the master domain manager. | | | | | | | | For job streams with a schedtime definition, the value of the Start time field displayed on the Job Scheduling Console and Tivoli Dynamic Workload Console depends on the setting of the enPreventStart global option (which determines if job streams without an at dependency can start immediately, without waiting for the run cycle specified in the job stream): v If enPreventStart is set to yes, the start time is 12:00 AM converted to the time zone specified on the graphical user interface. v If enPreventStart is set to no, the start time field is blank. Examples: The following examples assume that the Tivoli Workload Scheduler processing day starts at 6:00 a.m. v The following job stream, selected on Tuesdays, is scheduled to start at 3:00 a.m. on Wednesday morning. Its two jobs are launched as soon as possible after the job stream starts processing.
171
job stream keywords - schedtime

schedule sked7 on tu schedtime 0300: job1 job2 end
v The time zone of workstation sfran is defined as America/Los_Angeles, and the time zone of workstation nycity is defined as America/New_York. Job stream sked8 is selected to run on Friday. It is scheduled to start on workstation sfran at 10:00 a.m. America/Los_Angeles Saturday (as specified by the + 1 day offset). Job job1 is launched on sfran as soon as possible after the job stream starts processing. Job job2 is launched on sfran at 2:00 p.m. America/New_York (11:00 a.m. America/Los_Angeles) Saturday. job3 is launched on workstation nycity at 4:00 p.m. America/New_York (1:00 p.m. America/Los_Angeles) Saturday.
sfran#schedule sked8 on fr schedtime 1000 + 1 day: job1 job2 at 1400 tz America/New_York nycity#job3 at 1600 end
172
job stream keywords - schedule
schedule
Specifies the job stream name. With the exception of comments, this must be the first keyword in a job stream, and must be followed by the on keyword. Syntax: schedule [workstation#]jstreamname [timezone|tz tzname] Arguments: workstation Specifies the name of the workstation on which the job stream is launched. The default is the workstation on which composer runs to add the job stream.
jstreamname Specifies the name of the job stream. The name must start with a letter, and can contain alphanumeric characters, dashes, and underscores. It can contain up to 16 characters. timezone|tz tzname Specifies the time zone to be used when managing for the job stream. This setting is ignored if the global option enTimeZone is set to no on the master domain manager. For information on time zone settings, refer to Chapter 12, Managing time zones, on page 461. Comments: In a job stream definition you can set a time zone for the entire job stream by using the timezone keyword in the validity interval or when specifying time restrictions using at, until, or deadline. You can set also a time zone for a job contained in a job stream by setting keywords at, until, or deadline for that job. Regardless of whether you are defining a job or a job stream, if you use a time zone in a time restriction, for example at then you must use the same time zone when specifying the other time restrictions, such as deadline and until. In a job stream definition you can set a time zone for the entire job stream and for the jobs it contains. These time zones can differ from each other, in which case the time zone set for the job is converted into the time zone set for the job stream. To manage all possible time zone settings, the time zone conversion that is performed when processing jobs and job streams across the Tivoli Workload Scheduler network is made respecting the following criteria: 1. If a time zone is not set for a job within a job stream, then that job inherits the time zone set on the workstation where the job is planned to run. 2. If a time zone is not set for a job stream, then the time zone set is the one set on the workstation where the job stream is planned to run. 3. If none of the mentioned time zones is set, then the time zone used is the one set on the master domain manager. Examples: This is the definition of e time zone of workstation sfran defined on workstation sfran on which is set the time zone America/New_York. The time zone set for job2 to run of workstation LA is defined as America/Los_Angeles.
173
job stream keywords - schedule

schedule sfran#sked8 tz America/New_York on fr at 1000 + 1 day: job1 LA#job2 at 1400 tz America/Los_Angeles end
174
job stream keywords - until
until
Depending on the object definition the until keyword belongs to, specifies the latest time a job stream must be completed or the latest time a job can be launched. Syntax: until time [timezone|tz tzname][+n day[s]] [onuntil action] Arguments: time Specifies the time of day. The possible values are 0000 through 2359.
tzname Specifies the time zone to be used when computing the time. See Chapter 12, Managing time zones, on page 461 for time zone names. The default is the time zone of the workstation on which the job or job stream is launched. Note: If an until time and an at or deadline time are specified, the time zones must be the same. n Specifies an offset, in days, from the scheduled date and time.
onuntil action Depending on the object definition the until keyword belongs to, specifies: v The action to be taken on a job whose until time has expired but the job has not yet started. v The action to be taken on a job stream whose until time has expired but the job stream is not yet completed in SUCC state. The following are the possible values of the action parameter: suppr The job or job stream and any dependent job or job stream do not run. This is he default behavior. Once the until time expired on a job stream, the status for the job stream is calculated following the usual rules; suppressed jobs are not considered in the calculation. In case the job stream contains at least one every job its status is HOLD. When the until time expires for a job, the job moves to HOLD status or keeps any previous status which is a final status cont The job or job stream runs when all necessary conditions are met and a notification message is written to the log when the until time elapses. A job or job stream is cancelled when the until time specified expires. When using onuntil canc on jobs, the cancel operation on the job is issued by the FTA on which the job runs. Any job or job stream that was dependent on the completion of a job or job stream that was cancelled, runs because the dependency no longer exists. Note: When using onuntil canc at job stream level, define as owner of the job stream the workstation highest in the hierarchy of the scheduling environment, among all workstations that own jobs contained in the job stream. Note: Both the keyword until and deadline can be used in the same definition but they must be expressed using the same time zone setting.
canc
175
job stream keywords - until

Examples: The following example prevents sked1 from launching after 5:00 p.m. on Tuesdays:
schedule sked1 on tu until 1700 :
The following example launches sked1 at 5:00 p.m., when its until time is reached:
schedule sked1 until 1700 onuntil cont
The following example launches job1 between 1:00 p.m. and 5:00 p.m. on weekdays:
schedule sked2 on weekdays : job1 at 1300 until 1700 end
The following example launches joba every 15 minutes between 10:30 p.m. and 11:30 p.m. on Mondays:
schedule sked3 on mo : joba at 2230 every 0015 until 2330 end
The following example launches job stream sked4 on Sundays between 8:00 a.m. and 1:00 p.m. The jobs are to be launched within this interval:
schedule sked4 on fr at 0800 + 2 days until 1300 + 2 days : job1 job2 at 0900 <<launched on sunday>> job3 follows job2 at 1200 <<launched on sunday>> end
The following example launches job stream sked8 on weekdays at 4:00 p.m. and should complete running by 5 p.m. If the job stream is not completed by 5 p.m., it is considered a late job stream. The jobs are to be launched as follows: job1 runs at 4 p.m., or at the latest, 4:20 p.m., at which time, if job1 has not yet started, a notification message is written to the log and it starts running. job2 runs at 4:30 p.m. or at the latest 4:50 p.m., at which time, if job2 has not yet started, it is cancelled.
schedule sked8 on weekdays at 1600 deadline 1700 : job1 at 1600 until 1620 onuntil cont job2 at 1630 until 1650 onuntil canc end
The following example launches job stream sked01. When the until event occurs, the job stream sked02 is run because the job stream sked01 is placed in SUCC state. The job stream sked03, instead, is not run because it has a punctual time dependency on job job01 and this dependency has not been released.
SCHEDULE sked01 on everyday: job01 until 2035 onuntil suppr end SCHEDULE sked02 on everyday follows sked01.@ : job02 end SCHEDULE sked03 on everyday follows sked01.job01 : job03 END
176
job stream keywords - validfrom
validfrom
You can set a validity time for a job stream, which is a time frame within which the job stream is included in the preproduction plan. The validity time is set using the validfrom key in the job stream definition. Syntax: validfrom date Arguments: validfrom date Defines from which date the job stream is active, that is it must be included in a production plan if the production plan duration includes that date. Comments: Different versions of the same job stream can be defined by creating different job streams with the same name and workstation, but having different validity intervals. The concept of versions of the same job stream sharing the same jobstreamname and the same workstationname are key when managing dependency on that job stream. In fact when you define an external follows dependencies on a job stream you identify the predecessor job stream using its jobstreamname and workstationname. The job stream identified as the dependency is the one whose validity interval is during the period the dependency is active. If you change the jobstreamname or the workstationname in one version of the job stream, the change is propagated in all its versions. If you lock a version of the job stream, all versions of that job stream are locked. If you change the name of a job defined in a job stream version then the new job name is propagated in all versions of the job stream. This means that, if you modify something, other than the jobstreamname or the workstationname, the internal and external job stream associations remain consistent. When defining a job stream version, you are only asked to enter the validfrom date, and the validto date is automatically set to the value of the validfrom date of the following version. The validto date is shown when issuing list and display command when MAESTROCOLUMNS is set to 120. Different versions of the same job stream continue to share the name and workstation fields after their creation. If you modify the name of a version or change the workstation on which it was defined, the change is applied to all versions of that job stream. Note: If the keywords used in the job stream definition are validfrom and validto, the corresponding filtering keywords used when issuing commands against object definitions stored in the database are valid from and valid to. For more information refer to Chapter 8, Managing objects in the database composer, on page 189.
177
Event rule definition

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

A scheduling event rule defines a set of actions that are to run upon the occurrence of specific event conditions. The definition of an event rule correlates events and triggers actions. An event rule definition is identified by a rule name and by a set of attributes that specify if the rule is in draft state or not, the time interval it is active, the time frame of its validity, and other information required to decide when actions are triggered. It includes information related to the specific events (eventCondition) that the rule must detect and the specific actions it is to trigger upon their detection or timeout (action). Complex rules may include multiple events and multiple actions. Refer to Chapter 6, Running event-driven workload automation, on page 89 for an overview of scheduling event rules.
Syntax
Unlike all other scheduling object definitions, you define event rules directly in XML language with the use of any XML editor. You can configure an environment variable on your computer to automatically open an XML editor of your choice to work with event rule definitions. See The composer editor on page 191 for details. The XML describing the event rule must match the rule language schemas defined in EventRules.xsd and in FilteringPredicate.xsd. The rule language schemas defined in eventRules.xsd and in FilteringPredicate.xsd are used to validate your rule definitions and, depending upon the XML editor you have, to provide syntactic help. The files are located in the schemas subdirectory of the Tivoli Workload Scheduler installation directory. The following is a list of all the language elements used for defining an event rule. Table 30 explains the meaning of the notation that follows each language element. n represents an unbounded number.
Table 30. Explanation of the notation defining the number of occurrences for a language element. Notation (0, 1) (0, n) Meaning 0 indicates that the language element is optional. 1 indicates that if coded, only 1 occurrence is allowed. 0 indicates that the language element is optional. n indicates that if coded, multiple occurrences are allowed. The first 1 indicates that the language element is required. The second 1 indicates that only 1 occurrence is allowed. 1 indicates that the language element is required. 2 indicates that 2 occurrences are required. 1 indicates that the language element is required. n indicates that multiple occurrences are allowed.
(1, 1)
(1, 2) (1, n)
v <eventRule name=" " ruleType=" " isDraft=" "> (1, 1) <description> (0, 1) <timeZone> (0, 1) <validity from=" " to=" "> (0, 1) <activeTime start=" " end=" "> (0, 1)
178

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | <timeInterval amount=" " unit=" "> (0, 1) <eventCondition eventProvider=" " eventType=" "> (1, n) - <scope> (0, 1) - <filteringPredicate> (0, 1) v <attributeFilter name=" " operator="eq"> (0, n) <value> (1, n) v <attributeFilter name=" " operator="ne"> (0, n) <value> (1, n) v <attributeFilter name=" " operator="le"> (0, n) <value> (1, 1) v <attributeFilter name=" " operator="ge"> (0, n) <value> (1, 1) v <attributeFilter name=" " operator="range"> (0, 1) <value> (1, 2) <correlationAttributes> (0, 1) - <attribute name=" "> (1, n) <action actionProvider=" " actionType=" " responseType=" "> (0, n) - <description> (0, 1) - <scope> (0, 1) - <parameter name=" ">(1, n) - <value> (1, 1) Event rule definitions are grouped into event rule sets. v <eventRuleSet> (1, 1) <eventRule> (1, n) Use the eventRuleSet language element also if you have to enclose a single rule definition. Note that none of the comments you might write in the XML, in the form , are saved in the database. The next time you open a rule definition, the comments you wrote the first time will be gone. Use the description attribute to write any additional information instead.
Arguments
The keywords describing an event rule are the following XML tags: eventRule The scheduling object that encloses the definition of multiple event conditions and multiple rule actions in addition to a set of attributes that define when the rule is activated. An eventRule element typically includes: v A number of required and optional rule attributes v One or more event conditions v One or more rule actions, although rules with no actions are also allowed The rule attributes are: v Required attributes: name The name of the event rule. It can be up to 40 alphanumeric characters in length, it must start with a letter, and cannot contain blanks. Underscore (_) and dash (-) characters are allowed.
ruleType The rule type is based on the number of events - and on their correlation - that the rule is defined to detect. It can be one of the following:
179

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | validity Specifies the rule validity period in terms of: from yy-mm-dd The validity period starts at midnight (of the rule time zone) of the specified day. to yy-mm-dd The validity period ends at midnight (of the rule time zone) of the specified day. activeTime Specifies the rule activity time window within each day of validity in terms of: isDraft Specifies if the rule definition is currently enabled. Values can be yes or no. The default is no. v Optional attributes: description A description of the rule. It can be of up to 120 characters. Remember to write any XML special characters you might use in the XML special notation, such as: & for & > for > < for < " for " and so on. timeZone Specifies a different time zone for the execution of the rule. The default time zone is the time zone defined on the workstation where the event processing server resides. The application of daylight saving time (DST) has an impact on the activeTime interval (described next) of event rules: On the day that DST is turned on (the clock is adjusted forward one hour) the rule operation times that fall within the hour absorbed by the application of DST are moved forward by one hour. For example, 2:10 becomes 3:10. On the day that DST is turned off (the clock is adjusted backward one hour) the rule operation times that fall within the hour duplicated by the application of DST are regarded without DST. filter The rule is activated upon the detection of a single specific event.
sequence The rule is activated when an ordered sequence of events arrives within a specific time interval. set The rule is activated when an unordered sequence of events arrives within a specific time interval.
Rules of type set and sequence can also be activated on timeout, when one or more events arrive but the complete sequence does not arrive within the specified time window.
180

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | start hh:mm:ss The beginning of the time window when the rule is active in hours, minutes, and seconds. end hh:mm:ss The end of the time window when the rule is active in hours, minutes, and seconds. If the time is earlier than in start hh:mm:ss, it refers to the next day. timeInterval Applies to rules that include timeout actions. Specifies the time interval within which all the events specified in the rule must have been received before a corrective timeout action is started. The time interval starts from the moment the first event specified in the rule is detected. Specify the time interval in terms of: amount The length of the time interval in time units. unit The time unit in one of the following: hours seconds milliseconds This attribute is mandatory when there are timeout actions in the event rule definition. eventCondition The event condition is made up by the following attributes: v Required attributes: eventProvider Identifies the event monitoring provider that can capture a type of event. The event providers supplied at installation time are: TWSObjectsMonitor Monitors the status of Tivoli Workload Scheduler plan objects. This event provider runs on every Tivoli Workload Scheduler agent and sends the events to the event processing server. FileMonitor Monitors events affecting files. eventType Specifies the type of event that is to be monitored. Every event can be referred to an event provider. The following tables list the event types by event provider. Click on the event types to see their properties. Table 31 lists the TWSObjectsMonitor events.
Table 31. TWSObjectsMonitor events. Event type JobStatusChanged JobUntil JobSubmit JobCancel This event is sent when... the status of a job changes the latest start time of a job has elapsed a job is submitted a job is cancelled
181

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 31. TWSObjectsMonitor events. (continued) Event type JobRestart JobLate JobStreamStatusChanged JobStreamCompleted JobStreamUntil JobStreamSubmit JobStreamCancel JobStreamLate WorkstationStatusChanged ApplicationServerStatusChanged ChildWorkstationLinkChanged This event is sent when... a job is restarted a job becomes late the status of a job stream changes a job stream has completed the latest start time of a job stream has elapsed a job stream is submitted a job stream is cancelled a job stream becomes late a workstation is started or stopped the embedded WebSphere Application Server has stopped or is restarting the workstation defined in the event rule links or unlinks from its parent workstation (the parent workstation sends the event) the parent workstation links or unlinks from the workstation defined in the event rule (the child workstation sends the event) a prompt is asked or replied
ParentWorkstationLinkChanged
PromptStatusChanged
Table 32 lists the FileMonitor events.

Table 32. FileMonitor events. Event type FileCreated FileDeleted ModificationCompleted This event is sent when... a file is created a file is deleted a file is modified (the event is sent only if two consecutive monitoring cycles have passed since the file was created or modified with no additional changes being detected) a specific string is found in a file (this event can be used to monitor application or system logs)
LoggedMessageWritten
v Optional attributes: scope One or more qualifying attributes that describe the event. It can be of up to 120 characters. The scope is automatically generated from what is defined in the XML. It cannot be specified by users.
filteringPredicate The filtering predicate sets the event conditions that are to be monitored for each event type. It is made up by: attributeFilter The attribute filter is a particular attribute of the event type that is to be monitored: Is defined by the following elements: name The attribute, or property name, of the event type that is to be monitored. Refer to Event
182

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | providers and definitions on page 509 for a list of property names for every event type. operator Can be: - eq (equal) - ne (not equal) - ge (equal or greater than) - le (equal or less than) - range (range) Includes one or more: value The value on which the operator must be matched.
Note that every event type has a number of mandatory attributes, or property names. Not all the mandatory property names have default values. All the mandatory property names without a default value must have a filtering predicate defined. correlationAttributes The correlation attributes provide a way to direct the rule to create a separate rule copy for each group of events that share common characteristics. Typically, each active rule has one rule copy that runs in the event processing server. However, sometimes the same rule is needed for different groups of events, which are often related to different groups of resources. Using one or more correlation attributes is a method for directing a rule to create a separate rule copy for each group of events with common characteristics. Use with set and sequence rule types. You can specify one or more attributes. Each is defined by: attribute name=" " The object attribute that you are correlating. action The action that is to be triggered if the event is detected. Event rule definitions with events but no actions are syntactically accepted, although they may have no practical significance. You may save such rules as draft and add actions later before they are deployed. v Is defined by the following required attributes: actionProvider The name of the action provider that can implement one or more configurable actions. The action providers available at installation time are: TECEventForwarder Forwards the event to an external TEC (Tivoli Enterprise Console) server (or any other application capable of listening to events in TEC format). MailSender Connects to an SMTP server to send an e-mail. MessageLogger Logs the occurrence of a situation in an internal auditing database. TWSAction Runs one of the following conman commands: submit job (sbj) submit job stream (sbs) submit command (sbd) reply to prompt (reply)
183

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | scope
GenericAction TWSAction
GenericAction Runs non-Tivoli Workload Scheduler commands. The commands are run on the same computer where the event processor runs. actionType Specifies the type of action that is to be triggered when a specified event is detected. Every action can be referred to an action provider. The following table lists the action types by action provider. Click on the action types to see their properties.
Table 33. Action types by action provider. Action provider TECEventForwarder MailSender MessageLogger Action types TECFWD SendMail PostOperatorMessage sbs (SubmitJobStream) sbj (SubmitJob) sbd (SubmitAdHocJob) reply (ReplyPrompt) RunCommand
responseType Specifies when the action is to run. Values can be: onDetection The action starts as soon as all the events defined in the rule have been detected. Applies to all rule types. See also Rule operation notes on page 102. onTimeOut The action starts after the time specified in timeInterval has expired but not all the events defined in the rule have been received. Applies to set and sequence rules only. Note that timeout actions are not run if you do not specify a time interval. The scheduler will however let you save event rules where timeout actions have been defined without specifying a time interval, because you could set the time interval at a later time. Until then, only actions with the onDetection response type are processed. v Includes the following optional attributes: description A description of the action. It can be of up to 120 characters. Remember to write any XML special characters you might use in the XML special notation, such as: & for & > for > < for < " for " and so on. One or more qualifying attributes that describe the action. It can be of up to 120 characters. The scope is automatically generated from what is defined in the XML. It cannot be specified by users.
184

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | v Includes a list of one or more parameters, or property names. All action types have at least one mandatory parameter. Every parameter is defined by: parameter name=" " See Action providers and definitions on page 537 for a list of parameters, or property names, available for every action type. value See Action providers and definitions on page 537 for a list of possible values or value types. You can use variable substitution. This means that when you define action parameters, you can use the property names of the events that trigger the event rule to replace the value of the action property name. To do this, write the value for the action parameter you intend to substitute in either of these two forms: ${event.property} Replaces the value as is. This is useful to pass the information to an action that works programmatically with that information, for example the schedTime of a job stream. %{event.property} Replaces the value formatted in human readable format. This is useful to pass the information to an action that forwards that information to a user, for example to format the schedTime of a job stream in the body of an e-mail. Where: event Is the name you set for the triggering eventCondition. property Is the attributeFilter name in the filtering predicate of the triggering event condition. The value taken by the attribute filter when the rule is triggered is replaced as a parameter value in the action definition before it is performed. Note that you can use variable substitution also if no attributeFilter was specified for an attribute and also if the attribute is read-only. For example, the task of an event rule is to detect when any of the jobs that have a name starting with job15 end in error and, when that happens, submit that job again. The eventCondition section of the rule is coded as follows:
<eventCondition name=event1 eventProvider=TWSObjectsMonitor eventType=JobStatusChanged> <filteringPredicate> <attributeFilter name=JobName operator=eq> <value>job15@</value> </attributeFilter> <attributeFilter name=Workstation operator=eq> <value>@</value> </attributeFilter> <attributeFilter name=Status operator=eq> <value>Error</value> </attributeFilter> </filteringPredicate> </eventCondition>
Wild cards are used to generalize the desired event condition to all the job instances whose name starts with job15 and to their associated
185

| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | workstation. Variable substitution is used in the action section to submit again the specific job that ended in error on the same workstation. The action section is:
<action actionProvider=TWSAction actionType=sbj responseType=onDetection> <description>Submit again the job that ended in error</description> <parameter name=JobDefinitionName> <value>${event1.JobName}</value> </parameter> <parameter name=JobDefinitionWorkstationName> <value>${event1.Workstation}</value> </parameter> </action>
Examples
JOB7 has a file dependency on DAILYOPS.XLS. As soon as the file is received, JOB7 must start to process the file. The following rule controls that JOB7 starts within one minute after the transfer of DAILYOPS.XLS is finished. If this does not happen, an e-mail is sent to the evening operator. This is accomplished by defining two sequential event conditions that have to monitored: 1. The first event that triggers the rule is the creation of file DAILYOPS.XLS on the workstation to which it is to be transferred. As soon as this event is detected, a rule instance is created and a one minute interval count is begun to detect the next event condition. 2. The second event is the submission of JOB7. If this event fails to be detected within the specified time interval, the rule times out and the SendMail action is started.
a?xml version=1.0 encoding=UTF-8?> aeventRuleSet xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns=http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules xsi:schemaLocation=http://www.ibm.com/xmlns/prod/tws/1.0/event-management/rules EventRules.xsd> <EventRule name=sample_rule ruleType=sequence isDraft=no> <description>An e-mail is sent if job JOB7 does not start within a minute after file DAILYOPS.XLS is created</description> <timeZone>America/Indianapolis</timeZone> <validity from=2007-01-01 to=2007-12-31 /> <activeTime start=20:00:00 end=22:00:00 /> <timeInterval amount=60 unit=seconds /> <eventCondition name=DAILYOPS_FTPed_event eventProvider=FileMonitor eventType=FileCreated> <filteringPredicate> <attributeFilter name=FileName operator=eq> <value>c:/dailybus/DAILYOPS.XLS</value> </attributeFilter> <attributeFilter name=Workstation operator=eq> <value>ACCREC03</value> </attributeFilter> <attributeFilter name=SampleInterval operator=eq> <value>300</value> </attributeFilter> </filteringPredicate> </eventCondition> <eventCondition name=job_JOB7_problem_event eventProvider=TWSObjectMonitor eventType=JobSubmit> <filteringPredicate> <attributeFilter name=JobStreamWorkstation operator=eq> <value>ACCREC03</value> </attributeFilter> <attributeFilter name=Workstation operator=eq> <value>ACCREC03</value> </attributeFilter> <attributeFilter name=JobStreamName operator=eq> <value>JSDAILY</value>
186

| | | | | | | | | | | | | | | | | | | |
</attributeFilter> <attributeFilter name=JobName operator=eq> <value>JOB7</value> </attributeFilter> </filteringPredicate> </eventCondition> <action actionProvider=MailSender actionType=SendMail responseType=onTimeOut> <description>Send email to evening operator stating job did not start</description> <parameter name=To> <value>eveoper@bigcorp.com</value> </parameter> <parameter name=Subject> <value>Job JOB7 failed to start within scheduled time on workstation ACCREC03.</value> </parameter> </action> </eventRule> </eventRuleSet>
Note that the scope does not show the first time the rule is defined. Go to Event rule examples on page 97 to find more event rule examples.
187
188
Chapter 8. Managing objects in the database - composer

This chapter describes how you use the composer command-line program to manage scheduling objects in the Tivoli Workload Scheduler database. It is divided into the following sections: v What is new in managing objects in the database v Using the composer command-line program on page 190 v Running commands from composer on page 194
What is new in managing objects in the database

| | | | | | | | | | | | The composer command line program of Version 8.4 is enhanced to include command line management of event rule definitions in the database. The following commands now include event rules as target objects: v create-extract v delete v display v list, print v lock v modify v new v rename v unlock
189
Using composer command-line program
Using the composer command-line program

The composer command line program manages scheduling objects in database. You must install the Tivoli Workload Scheduler Command Line Client feature on fault-tolerant agents and systems outside the Tivoli Workload Scheduler network to use the composer command-line program.
Setting up the composer environment

This section describes how you set up your composer environment.
Terminal output
The shell variables named MAESTROLINES and MAESTROCOLUMNS determine the output to your computer. If either variable is not set, the standard shell variables, LINES and COLUMNS, are used. At the end of each screen page, composer prompts to continue. If MAESTROLINES (or LINES) is set to zero or a negative number, composer does not pause at the end of a page.
Offline output
The ;offline option in composer commands is used to print the output of a command. When you include it, the following variables control the output: Windows variables: MAESTROLP Specifies the file into which a commands output is written. The default is stdout. MAESTROLPLINES Specifies the number of lines per page. The default is 60. MAESTROLPCOLUMNS Specifies the number of characters per line. The default is 132. UNIX variables: The ;offline option in composer commands is used to print the output of a command. When you include it, the following shell variables control the output: MAESTROLP Specifies the destination of a commands output. Set it to one of the following: > file Redirects output to a file, overwriting the contents of that file. If the file does not exist, it is created.
>> file Redirects output to a file, appending the output to the end of the file. If the file does not exist, it is created. | command Pipes output to a system command or process. The system command is run whether or not output is generated. || command Pipes output to a system command or process. The system command is not run if there is no output. The default value for MAESTROLP is | lp -tCONLIST which directs the command output to the printer and places the title CONLIST in the banner page of the printout.
190
Setting up composer environment

MAESTROLPLINES Specifies the number of lines per page. The default is 60. MAESTROLPCOLUMNS Specifies the number of characters per line. The default is 132. You must export the variables before you run composer.
The composer editor

Several composer commands automatically open a text editor. You can select which editor you want composer to use. Windows: In Windows, Notepad is used as the default editor. To change the editor, set the EDITOR environment variable to the path and name of the new editor before you run composer. UNIX: Several commands you can issue from composer automatically open a text editor. The type of editor is determined by the value of two shell variables. If the variable VISUAL is set, it defines the editor, otherwise the variable EDITOR defines the editor. If neither of the variables is set, a vi editor is opened. | | | | In addition, in both Windows and UNIX, you can set the XMLEDIT environment variable to point to an XML editor of your choice to edit event rule definitions. The XML editor opens automatically each time you run the composer add, new, or modify commands on an event rule.
Selecting the composer prompt on UNIX

The composer command prompt is defined in the TWS_home/localopts file. The default command prompt is a dash (-). To select a different prompt, edit the composer prompt option in the localopts file and change the dash. The prompt can be up to ten characters long, not including the required trailing pound sign (#):
#---------------------------------------------------------------------------# Custom format attributes # date format = 1 # The possible values are 0-ymd, 1-mdy, 2-dmy, 3-NLS. composer prompt = conman prompt = % switch sym prompt = <n>% #----------------------------------------------------------------------------
For additional information about localopts configuration file, refer to IBM Tivoli Workload Scheduler: Planning and Installation Guide.
Running the composer program

To configure your environment to use composer, set the PATH and TWS_TISDIR variables by running one of the following scripts: In UNIX: v . ./TWS_home/tws_env.sh for Bourne and Korn shells v . ./TWS_home/tws_env.csh for C shells In Windows: v TWS_home\tws_env.cmd Then use the following syntax to run commands from the composer user interface:
191
Running composer program

composer [-file filename][connection_parameters] [-defaultws twscpu] [command[&[command]][...]] where: -file filename Indicates an alternate custom properties file containing the settings for the connection parameters, used in place of the useropts and localopts files. connection_parameters Represents the set of parameters that rule the interaction between the product interface, composer running on the master domain manager in this case, and the WebSphere Application Server infrastructure using HTTP or HTTPS. Use the following syntax to specify the settings for the connection parameters: [-host hostname] [-port port_number] [-protocol protocol_name] [-proxy proxy_name] [-proxyport proxy_port_number] [-password user_password] [-timeout timeout] [-username username] where: hostname Is the hostname of the master domain manager. port_number Is the port number used when establishing the connection with the master domain manager. protocol_name Is the protocol used during the communication. It can be HTTP with basic authentication, or HTTPS with certificate authentication. proxy_name Is the proxy hostname used in the connection with HTTP protocol. proxy_port_number Is the proxy port number used in the connection with HTTP protocol. user_password Is the password of the user that is used to run composer. | | | | | timeout Is the maximum time, expressed in seconds, the connecting command line program can wait for the master domain manager response before considering communication request failed. username Is the username of the user running composer. Note: When accessing the composer command line the user with the username and password specified in the connection parameters must be defined as system user on the operating Note: On Windows workstations, when you specify a password that contains double quotation marks (") or other special characters, make sure that the character is escaped. For example, if your password is tws11"tws, write it as "tws11\"tws".
192

system where the master domain manager is installed and must have the authorization defined in the security file on the master domain manager. If any of these parameters is omitted when invoking composer, Tivoli Workload Scheduler searches for a value first in the useropts file and then in the localopts file. If no value is found then an error is displayed. Refer to Setting up options for using the user interfaces on page 29 for information on useropts and localopts files. -defaultws twscpu Indicates the default workstation composer uses for identifying the scheduling object when a specific workstation is not specified The composer command-line program is installed automatically when installing the master domain manager. It must be installed separately on top of a Tivoli Workload Scheduler agent workstation or stand-alone on a node outside the Tivoli Workload Scheduler network. The feature that installs the composer command-line program is named Command Line Client. For information on how to install the Command Line Client feature, refer to IBM Tivoli Workload Scheduler: Planning and Installation Guide. Once installed, you can use the composer command line both in batch and in interactive mode. When running composer in interactive mode, you first launch the composer command-line program and then, from the composer command line prompt, you run commands one at a time, for example:
composer username admin2 password admin2pwd add myjobs.txt create myjobs.txt from jobs=@
When running composer in batch mode, you launch the composer command-line program specifying as input parameter the command to be issued. When the command is processed, the composer command-line program exits, for example,
composer f c:\TWS\network\mylocalopts add myjobs.txt
Note: If you use the batch mode to issue more than one command from within the composer, make sure you manage the ; character in one of the following ways: v Using double-quotes, for example:
composer "delete dom=old_domain; noask"
v Using a space character, for example:

composer delete dom=old_domain noask
v Escaping the ; character, for example:

composer delete dom=old_domain \; noask
Other examples on how to use the command, assuming connection parameters are set in the local configuration scripts, are the following: v Runs print and version commands, and quits:
composer "p parms&v"
v Runs print and version commands, and then prompts for a command:
composer "p parms&v&"
v Reads commands from cmdfile:

193

composer < cmdfile
v Pipes commands from cmdfile to composer:

cat cmdfile | composer
Control characters
You can enter the following control characters in conversational mode to interrupt composer if your stty settings are configured to do so. Ctrl+c composer stops running the current command at the next step that can be interrupted and returns a command prompt. Ctrl+d composer quits after running the current command.
Running commands from composer

Composer commands consist of the following elements: commandname selection arguments where: commandname Specifies the command name. selection Specifies the object or set of objects to be acted upon. arguments Specifies the command arguments.
Filters and wild cards

In Tivoli Workload Scheduler composer you can use wild cards and filters when issuing some specific commands to filter scheduling objects defined in the database. The wild cards you can use from composer are: @ ? Replaces one or more alphanumeric characters. Replaces one alphanumeric character.
To search for occurrences with names that contain either @ or ?, make sure you use the backslash character \ before @ or ? to escape them so that they are not interpreted as wild cards. Similarly, the backslash character must be prefixed by another backslash character to be interpreted as an occurrence to be found. The following examples clarify these rules, which also apply when specifying search strings using the filter keyword. S@E S?E S\@E S\?E S\\E Search for all strings starting with S and ending with E, whatever is their length. Search for all strings starting with S and ending with E, and whose length is three characters. Search for an exact match with string S@E. Search for an exact match with string S?E. Search for an exact match with string S\E.
The commands you can issue from composer and that support filtering are: v display v create
194
Filters and wildcards

v v v v v v delete list lock modify print unlock
The syntax used to filter objects when issuing one of these commands is the following: command_name type_of_object=selection; [option;] [filter filter_keyword=selection [...]] Table 34 shows the scheduling objects you can filter when issuing the commands listed above, and for each object, which fields can be filtered (in italic) or which key (in bold) is used to filter its fields:
Table 34. Scheduling objects filtering criteria Scheduling object workstation Filter keywords Description or fields that can be filtered workstationname Applies the command to the workstations whose name satisfies the criteria. Example
list ws=p@
domain
Applies the command to the mod ws=@; filter workstations which belong to domain=dom1 a domain. Applies the command to the domains whose name satisfies the criteria. Applies the command to the domains whose parent domain satisfies the criteria. Applies the command to the global prompts whose name satisfies the criteria. display dom=dom?
domain
domainname
parent
list dom=@; filter parent=rome lock prompt=p@
prompt
promptname
Windows user resource
workstationname# Applies the command to the username users whose identifier satisfies the criteria. workstationname# Applies the command to the resourcename resources whose identifier satisfies the criteria. parametername Applies the command to the parameters whose name satisfies the criteria. Applies the command to the job definitions whose name satisfies the criteria. Applies the command to the jobs whose definition contains the specified recovery job definition.
list users=cpu1#operator?
print res=cpu?#operator?
parameter
delete parms=myparm@
job definition
jobname
mod jd=mycpu#myjob@
RecoveryJob
list jobdefinition=@; filter RecoveryJob=CPUA#job01
195
Filters and wildcards

Table 34. Scheduling objects filtering criteria (continued) Scheduling object job stream Filter keywords Description or fields that can be filtered workstationname# Applies the command to the jobstreamname job definitions whose name satisfies the criteria. Calendar or FreeCalendar Applies the command to the job streams that contains the calendar or Freeday calendar specified in the filter. Example
mod js=mycpu#myjs@
list js=@#@; filter Calendar=cal1
Jobdefinition
Applies the command to the list js=@#@; filter job streams that contains the jobdefinition=CPUA#job01 job definition specified in the filter. Applies the command to the job streams that refers to the resource specified in the filter. Applies the command to the job streams that refers to the prompt specified in the filter. list js=@#@; filter Resource=cpu1#disk1
Resource
Prompt
list js=@#@; filter Prompt=myprompt
| | | |
event rule
eventrulename
Applies the command to the list er=@; filter js=accrecjs5 event rules that include an action on a specific job or job stream.
You can combine more than one filter for the same object type as shown in the following example:
list js=@#@; filter Calendar=cal1 FreeCalendar=VACATIONS jobdefinition=CPUA#job01
The output of the command is a list of job streams using calendar cal1, freedays calendar VACATIONS, and containing a job with job definition CPUA#job01.
Delimeters and special characters

Table 35 lists characters have special meanings in composer commands.
Table 35. Delimeters and special characters for composer Character & ; = :! Description Command delimiter. See Running the composer program on page 191. Argument delimiter. For example: ;info;offline Value delimiter. For example: sched=sked5 Command prefixes that pass the command on to the system. These prefixes are optional; if composer does not recognize the command, it is passed automatically to the system. For example: !ls or :ls << >> Comment brackets. Comments can be placed on a single line anywhere in a job stream. For example: schedule foo <<comment>> on everyday
196
Delimeters and special characters

Table 35. Delimeters and special characters for composer (continued) Character * Description Comment prefix. When this prefix is the first character on a line, the entire line is a comment. When the prefix follows a command, the remainder of the line is a comment. For example: *comment or print& *comment > Redirects command output to a file, overwriting the contents of that file. If the file does not exist, it is created. For example: display parms > parmlist >> Redirects command output to a file and appends the output to the end of file. If the file does not exist, it is created. For example: display parms >> parmlist | Pipes command output to a system command or process. The system command is run whether or not output is generated. For example: display parms | grep alparm || Pipes command output to a system command or process. The system command is not run if there is no output. For example: display parms || grep alparm
Command descriptions
Table 36 lists the composer commands. Note: Command names and keywords can be entered in either uppercase or lowercase characters, and can be abbreviated to as few leading characters as are needed to uniquely distinguish them from each other. Some of the command names also have short forms. However there are some abbreviations, such as v, that point to a specific command, version in this case, even though they do not uniquely identify that command in the list. This happens when the abbreviation is hard coded in the product and so mismatches in invoking the wrong command are automatically bypassed.
Table 36. List of composer commands Command add Short Name Description a Adds scheduling objects. Changes the credentials of the user running composer. Ignores the next error. cr de di ed e Creates a text file for editing containing an object definition from the database. Deletes scheduling objects. Displays the details of the specified scheduling object. Edits a file. Exits composer. See page 203 205 206 207 210 213 217 218
authenticate au continue create delete display edit exit
197
Table 36. List of composer commands (continued) Command extract help list lock modify new print redo rename replace unlock validate version system command val v rn rep m n Short Name Description ex h l Extracts an object definition from the database and writes it in a text file. Invoke the help on line for a command. Lists scheduling objects. Locks the access to database objects. Modifies scheduling objects. Creates scheduling objects using a text file where the object definition is inserted on line. Prints scheduling objects. Edits and reruns the previous command. Changes the object name. Replaces scheduling objects. Releases lock on the scheduling object defined in the database. Validates the syntax, semantic, and data integrity of an object definition. Displays the composer command-line program banner. Invokes an operating system command. See page 207 219 220 224 227 231 213 232 234 236 238 241 242 237
Referential integrity check

Tivoli Workload Scheduler automatically performs referential checks to avoid lack of integrity in the object definitions in the database whenever you run commands that create, modify, or delete the definition of a referenced object. These are the checks performed by the product: v Every time you use a command that creates a new object in the database, Tivoli Workload Scheduler checks that: An object of the same type and with the same identifier does not already exist. The objects referenced by this object already exist in the database. v Every time you run a command that modifies an object definition in the database, Tivoli Workload Scheduler checks that: The object definition to be modified exists in the database. The objects referenced by this object exist in the database. To avoid integrity inconsistencies, the object definition does not appear in the definition of an object belonging to the chain of his ancestors. v Every time you run a command that deletes an object definition in the database, Tivoli Workload Scheduler checks that: The object definition to be deleted exists in the database. The object definition to be deleted is not referenced by other objects defined in the database. | Note that there is no referential integrity check for event rules.
198

Table 37 shows, for each object type, the identifiers that are used to uniquely identify the object in the database when creating or modifying object definitions:
Table 37. Object identifiers for each type of object defined in the database Object type domain workstation workstation class calendar job definition Windows user job stream job within a job stream resource prompt parameter Object identifiers domainname workstationname (checked across workstations and workstation classes) workstationclassname (checked across workstations and workstation classes) calendarname workstationname and jobname workstationname and username workstationname and jobstreamname and, if defined, validfrom workstationname and jobstreamname, jobname, and, if defined, validfrom workstationname and resourcename promptname parametername eventrulename
event rule
In general, referential integrity prevents the deletion of objects when they are referenced by other objects in the database. However, in some cases where the deletion of an object (for example a workstation) implies only the update of a referencing object (for example a workstation class that includes it), the deletion might be allowed. Table 38 shows all cases when a referenced object can be deleted even if other objects reference it:
Table 38. Object definition update upon deletion of referenced object Object Internetwork Dependency External Follows Depend References Workstation Job Stream Job Internal Dependency Workstation Class Job Workstation Upon deletion of the referenced object ... ... remove the dependency from the job or job stream ... remove the dependency from the job or job stream ... remove the dependency from the job or job stream ... remove the dependency from the job or job stream ... remove the workstation from the workstation class
Table 39 on page 200 describes how the product behaves when it is requested to delete an object referenced by another object with using a specific relationship:
199

Table 39. Referential integrity check when deleting an object from the database Object to be deleted domain A Referenced by object domain B workstation B workstation workstation A B job B job stream B windows user B job stream B Relationship domain A is parent of domain B workstation B belongs to domain A workstation A is host for workstation B job B is defined on workstation A job stream B is defined on workstation A windows user B is defined on workstation A workstation A works as network agent for internetwork dependencies set in job stream B job stream B has a file dependency from a file defined on workstation A workstation A works as network agent for internetwork dependencies set in job B job B has a file dependency from a file defined on workstation A resource B is defined on workstation A file B is defined on workstation A workstation A belongs to workstation class B job B contained in job stream B is defined on workstation A Delete rule An error specifying the existing relationship is displayed. An error specifying the existing relationship is displayed. An error specifying the existing relationship is displayed. An error specifying the existing relationship is displayed. An error specifying the existing relationship is displayed. An error specifying the existing relationship is displayed. Both workstation A and the internetwork dependency are deleted Both workstation A and the file dependency are deleted Both workstation A and the internetwork dependency are deleted Both workstation A and the file dependency are deleted An error specifying the existing relationship is displayed. An error specifying the existing relationship is displayed. Both workstation A and its entry in workstation class B are deleted. An error specifying the existing relationship is displayed.
job stream B
job B within job stream B
job B within job stream B resource B file B workstation class B job B within job stream B
200

Table 39. Referential integrity check when deleting an object from the database (continued) Object to be deleted job A Referenced by object job B job stream B job stream B Relationship job A is recovery job for job B job A is contained in job stream B job stream B follows job A Delete rule An error specifying the existing relationship is displayed. An error specifying the existing relationship is displayed. job A and the follows dependency in job stream B are deleted. job A and the follows dependency in job B are deleted. An error specifying the existing relationship is displayed.
job B within job stream B
job B follows job A job A is in the action definition of event rule B (and does not use variable substitution) job stream B uses calendar A job B is defined on workstation class A job stream B is defined on workstation class A resource B is defined on workstation class A file B is defined on workstation class A needs dependency defined in job stream B needs dependency defined in job B
| | | |
calendar A
event rule B
job stream B
An error specifying the existing relationship is displayed. An error specifying the existing relationship is displayed. An error specifying the existing relationship is displayed. An error specifying the existing relationship is displayed. An error specifying the existing relationship is displayed. An error specifying the existing relationship is displayed. An error specifying the existing relationship is displayed.
workstation job B class A job stream B resource B file B resource A job stream B job B within job stream B prompt A job stream B job B within job stream B
prompt dependency defined An error specifying the existing in job stream B relationship is displayed. prompt dependency defined An error specifying the existing in job B relationship is displayed.
201

Table 39. Referential integrity check when deleting an object from the database (continued) Object to be deleted parameter A Referenced by object job stream B Relationship parameter A is used in job stream B in: v in the text of an ad hoc prompt v or in the file name specified in a file dependency job B parameter A is used in job stream B in: v in the text of an ad hoc prompt v or in the file name specified in a file dependency v or in the value specified for streamlogon v or in the value specified for scriptname prompt B job stream A job stream B parameter A is used in the text of prompt B job stream B follows job stream A job B follows job stream A parameter A is deleted without checking job stream A and the follows dependency in job stream B are deleted. job stream A and the follows dependency in job B are deleted. parameter A is deleted without checking Delete rule parameter A is deleted without checking
job B within a job stream B
| | | |
event rule B
job stream A is in the action An error specifying the existing definition of event rule B relationship is displayed. (and does not use variable substitution)
202
add
add
Adds or updates scheduling objects to the database.
Authorization
You must have add access to add a new scheduling object. If the object already exists in the database you must have: v modify access to the object if the object is not locked. v modify and unlock access to the object if the object is locked by another user.
Syntax
add filename [;unlock]
Arguments
filename | | | | | ;unlock Indicates that the object definitions must be unlocked if locked by another user. Specifies the name of the text file that contains the object definitions. For event rules, filename specifies the name of the XML file containing the definitions of the event rules you wish to add (see Event rule definition on page 178 for XML reference and see The composer editor on page 191 for details on setting up an XML editor).
Comments
| | | | | The text file is validated at the client and, if correct, objects are inserted into the database on the master domain manager. Composer transforms object definitions into an XML definition used at the server; otherwise the command is interrupted and an error message is displayed. This does not apply to event rule definitions since they are provided directly in XML format. With the add command, if an object already exists, you are asked whether or not to replace it. This behavior does not affect existing job definitions inside job streams, and the job definitions are automatically updated without prompting any message. You can use the option unlock to update existing objects previously locked using only one command. For all new objects inserted, the option is ignored. If you change the name of an object, it is interpreted by composer as a new object and will be inserted. A rename command is recommended in this case. The add command checks for loop dependencies inside job streams. For example, if job1 follows job2, and job2 follows job1 there is a loop dependency. When a loop dependency inside a job stream is found, an error is displayed. The add command does not check for loop dependencies between job streams because, depending on the complexity of the scheduling activities, this check might be too time and CPU consuming.
Examples
To add the jobs from the file myjobs, run the following command:
add myjobs
To add the job streams from the file mysked, run the following command:
a mysked
203
add
To add the workstations, workstation classes, and domains from the file cpus.src, run the following command:
a cpus.src
To add the user definitions from the file users_nt, run the following command:
a users_nt
| |
To add the event rule definitions you edited in a file named newrules.xml, run:
a newrules.xml
See also
For the equivalent Job Scheduling Console task, see Managing database objects in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide. Event rule management is not supported by the Job Scheduling Console.
204
authenticate
authenticate
Switches to another user credentials while running composer.
Authorization
Any user authorized to run composer is authorized to issue this command.
Syntax
authenticate [username=username password=password]
Arguments
username=username The username of the user you want to switch to. password=password The password of the user you want to switch to.
Comments
A message is displayed communicating the authentication failure or success. This command is used only in interactive mode.
Examples
To switch to user tws_user1 with password mypasswd1 from within the composer command-line program, run the following command:
authenticate username=tws_user1 password=mypasswd1
205
continue
continue
Specifies that the next command error is to be ignored.
Authorization
Syntax
continue
Comments
This command is useful when multiple commands are entered on the command line or redirected from a file. It instructs composer to continue running commands even if the next command, following continue, results in an error. This command is not needed when you enter commands interactively because composer does not quit on an error.
Examples
If you want the composer to continue with the print command if the delete command results in an error, run the following command:
composer "continue&delete cpu=site4&print cpu=@"
206
create - extract
create - extract
Creates a text file containing object definitions extracted from the database. You can use this command to create a file containing parameter definitions to be imported into the parameter database defined locally on a workstation. For more information on how to import parameter definitions locally, refer to parms on page 400.
Authorization
You must have display access to the objects being copied and, if you want to use the ;lock keyword, also the modify access.
Syntax
| | | | | | | | | | | | | | | create | extract filename from {[calendars | {calendar | cal}=calname] | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [valid from date| valid to date |valid in date date] [full]] | [{users | user}=[workstationame#]username] | [{eventrule | erule | er}=eventrulename]} ;lock
Arguments
filename calendars calendar|cal Specifies the name of the file to contain the object definitions. Copies all calendar definitions into the file. Copies calendar definitions into the file. calname parms parm The name of the calendar. Wildcard characters are permitted.
Copies all parameter definitions into the file. Copies parameter definitions into the file. parmname The name of the parameter. Wildcard characters are permitted.
prompts prom
Copies all prompt definitions into the file. Copies prompt definitions into the file. promptname The name of the prompt. Wildcard characters are permitted.
resources resource|res
Copies all resource definitions into the file. Copies resource definitions into the file. resourcename The name of the resource. Wildcard characters are permitted.
cpu
Copies workstations, workstation classes, or domains into the file.
207
create - extract
workstation workstationclass The workstation class name specified in the job stream. Wildcard characters are permitted. domain The domain name specified in the job stream. Wildcard characters are permitted. The name of the workstation. Wildcard characters are permitted.
workstation|ws Copies workstation definitions into the file. workstationname The name of the workstation. Wildcard characters are permitted. domain|dom Copies domain definitions into the file. domainame The domain name specified in the job stream. Wildcard characters are permitted.
workstationclass|wscl Copies workstation class definitions into the file. workstationclassname The workstation class name specified in the job stream. Wildcard characters are permitted. jobs|jobdefinition|jd Copies job definitions into the file. workstation The name of the workstation on which the job runs. Wildcards are permitted. The default is the workstation on which composer is running. The name of the job. Wildcards are permitted.
jobname
sched|jobstream|js Copies job stream definitions into the file. workstation The name of the workstation on which the job stream runs. Wildcard characters are permitted. The default is the workstation on which composer is running. The name of the job stream. Wildcard characters are permitted. valid from date Restricts the selection to job streams that have a valid from date equal to the indicated value. The format is mm/dd/yy. date Restricts the selection to job streams that have a valid to date equal to the indicated value. The format is mm/dd/yy. date date The time frame during which the job stream can run. The format is mm/dd/yy - mm/dd/yy. One of the two dates can be represented by @.
jstream
valid to
valid in
208
create - extract
full users|user Copies also all job definitions contained in the job stream.
Copies the user definition into the file. The password field is not copied for security reasons. workstation The name of the workstation on which the user is defined. Wildcard characters are permitted. The default is the workstation on which composer is running. The user name. Wildcard characters are permitted.
username | | | | ;lock
eventrule|erule|er Copies event rule definitions into an XML file. eventrulename The name of the event rule definition. Wildcard characters are permitted.
Specifies to keep locked the selected object.
Note: You should regularly create a backup copy of the objects stored in the database.
Comments
The user can invoke the command with the old name create or the new name extract. Without lock option, database locking is not checked and all matching objects are extract to the file. After you create a file, you can use the edit command to make changes to the file and add or replace command to add or update the database The user can specify with the option lock, if the objects that respond to selected criteria, have to remain locked by the user in the database. If composer, during the extraction, find some of these objects already locked by someone else, these objects will not be present in the file and a message to stdout will be presented for each locked object.
Examples
To create a file named caltemp containing all calendars, run the following command:
create caltemp from calendars=@
To create a file named stemp containing all job streams, run the following command:
cr stemp from jobstream=@
To create a file named alljobs.txt containing all job definitions, run the following command:
extract alljobs.txt from jd=@#@
| | |
To create a file named allrules.xml containing all event rule definitions, run the following command:
create allrules.xml from erule=@
See also
For the equivalent Job Scheduling Console task, see Managing database objects in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide. Event rule management is not supported by the Job Scheduling Console.
209
delete
delete
Deletes object definitions in the database.
Authorization
You must have delete access to the objects being deleted.
Syntax
| | | | | | | | | | | | | | | delete {[calendars | {calendar | cal}=calname] | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched | jobstream | js}= [workstationame#]jstreamname [valid from date| valid to date |valid in date date] [full]] | [{users | user}=[workstationame#]username] | [{eventrule | erule | er}=eventrulename]} [;noask]
Arguments
calendars calendar|cal Deletes all calendar definitions. Deletes calendar definitions. calname parms parm The name of the calendar. Wildcard characters are permitted.
Deletes all parameter definitions. Deletes parameter definitions. parmname The name of the parameter. Wildcard characters are permitted.
prompts prom
Deletes all prompt definitions. Deletes prompt definitions. promptname The name of the prompt. Wildcard characters are permitted.
Deletes all resource definitions. Deletes resource definitions. resourcename The name of the resource. Wildcard characters are permitted.
cpu
Deletes workstations, workstation classes, or domains. workstation workstationclass The workstation class name specified in the job stream. Wildcard characters are permitted. The name of the workstation. Wildcard characters are permitted.
210
delete
domain The domain name specified in the job stream. Wildcard characters are permitted.
workstation|ws Deletes workstation definitions. workstationname The name of the workstation. Wildcard characters are permitted. domain|dom Deletes domain definitions. domainame The domain name specified in the job stream. Wildcard characters are permitted.
workstationclass|wscl Deletes workstation class definitions. workstationclassname The workstation class name specified in the job stream. Wildcard characters are permitted. jobs|jobdefinition|jd Deletes job definitions. workstation The name of the workstation on which the job runs. Wildcards are permitted. The default is the workstation on which composer is running. The name of the job. Wildcards are permitted.
jobname
sched|jobstream|js Deletes job stream definitions. workstation The name of the workstation on which the job stream runs. Wildcard characters are permitted. The default is the workstation on which composer is running. The name of the job stream. Wildcard characters are permitted. valid from date Restricts the selection to job streams that have a valid from date equal to the indicated value. The format is mm/dd/yy. date Restricts the selection to job streams that have a valid to date equal to the indicated value. The format is mm/dd/yy. date date The time frame during which the job stream can run. The format is mm/dd/yy - mm/dd/yy. One of the two dates can be represented by @.
jstream
valid to
valid in
users|user
Deletes the user definition. workstation The name of the workstation on which the user is defined. Wildcard characters are permitted. The default is the workstation on which composer is running.
211
delete
username | | | | noask The user name. Wildcard characters are permitted.
eventrule|erule|er Deletes event rule definitions. eventrulename The name of the event rule definition. Wildcard characters are permitted.
Specifies not to prompt for confirmation before taking action on each qualifying object.
Comments
If you use wildcard characters to specify a set of definitions, composer requires confirmation before deleting each matching definition. A confirmation is required before deleting each matching definition if noask option is not specified. To delete an object, it must not be locked. If some matching objects are locked during the command processing, an error message with the list of these objects is shown to the user and a confirmation is required to delete the unlocked objects.
Examples
To delete job3 that is launched on workstation site3, run the following command:
delete jobs=site3#job3
To delete all workstations with names starting with ux, run the following command:
de cpu=ux@
To delete all job streams with names starting with test on all workstations, run the following command:
de sched=@#test@
| | |
To delete all the event rules named from rulejs320 to rulejs329, run the following command:
de erule=rulejs32?
See also
For the equivalent Job Scheduling Console task, see Managing database objects in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide Event rule management is not supported by the Job Scheduling Console.
212
display
display
Displays the details of one or more object definitions of the same type stored in the database. The entire definition of the object is displayed.
Authorization
You must have display access to the object being displayed. If you want to use the full keyword you must have also the display access to the jobs contained in the job stream definition.
Syntax
| | | | | | | | | | | | | | | display {[calendars | {calendar | cal}=calname] | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [valid from date| valid to date |valid in date date] [full]] | [{users | user}=[workstationame#]username] | [{eventrule | erule | er}=eventrulename]} ;offline
Arguments
calendars calendar|cal Displays all calendar definitions. Displays calendar definitions. calname parms parm The name of the calendar. Wildcard characters are permitted.
Displays all parameter definitions. Displays parameter definitions. parmname The name of the parameter. Wildcard characters are permitted.
prompts prom
Displays all prompt definitions. Displays prompt definitions. promptname The name of the prompt. Wildcard characters are permitted.
resouces resource|res
Displays all resource definitions. Displays resource definitions. resourcename The name of the resource. Wildcard characters are permitted.
cpu
Displays workstations, workstation classes, or domains. workstation The name of the workstation. Wildcard characters are permitted.
213
display
workstationclass The workstation class name specified in the job stream. Wildcard characters are permitted. domain The domain name specified in the job stream. Wildcard characters are permitted.
workstation|ws Displays workstation definitions. workstationname The name of the workstation. Wildcard characters are permitted. domain|dom Displays domain definitions. domainame The domain name specified in the job stream. Wildcard characters are permitted.
workstationclass|wscl Displays workstation class definitions. workstationclassname The workstation class name specified in the job stream. Wildcard characters are permitted. jobs|jobdefinition|jd Displays job definitions. workstation The name of the workstation on which the job runs. Wildcards are permitted. The default is the workstation on which composer is running. The name of the job. Wildcards are permitted.
jobname
sched|jobstream|js Displays job stream definitions. workstation The name of the workstation on which the job stream runs. Wildcard characters are permitted. The default is the workstation on which composer is running. The name of the job stream. Wildcard characters are permitted. valid from date Restricts the selection to job streams that have a valid from date equal to the indicated value. The format is mm/dd/yy. date Restricts the selection to job streams that have a valid to date equal to the indicated value. The format is mm/dd/yy. date date The time frame during which the job stream can run. The format is mm/dd/yy - mm/dd/yy. One of the two dates can be represented by @.
jstream
valid to
valid in
users|user
Displays the user definition. workstation The name of the workstation on which the user is
214
display
defined. Wildcard characters are permitted. The default is the workstation on which composer is running. username | | | | ;offline The user name. Wildcard characters are permitted.
eventrule|erule|er Displays event rule definitions. eventrulename The name of the event rule definition. Wildcard characters are permitted.
Sends the output of the command to the composer output device. For information about this device, see UNIX variables on page 190.
Results
The display command returns you the following information about the object to be displayed: v a summary row containing information about the selected object v the selected object definition Depending on the value set for in the MAESTROCOLUMNS local variable the summary row shows different sets of information about the selected object. Table 40 shows an example of the output produced based on the value set for the MAESTROCOLUMNS variable.
Table 40. Output formats for displaying scheduling objects Object Type Calendar Domain Output format if MAESTROCOLUMNS=80 "CalendarName : UpdatedBy : UpdatedOn : LockedBy" "DomainName : ParentDomain : Master : UpdatedOn : LockedBy" "EventRuleName : Type : Draft : Status : UpdatedOn : LockedBy" "JobDefinitionName : Workstation : LockedBy" "JobstreamName : Workstation : Validfrom : UpdatedOn : LockedBy" "ParameterName : LockedBy" "PromptName : LockedBy " "ResourceName : Workstation : Quantity : LockedBy " "UserName : Workstation : LockedBy" "WorkstationName : Type : Domain : UpdatedOn : LockedBy" Output format if MAESTROCOLUMNS 120 "CalendarName : UpdatedBy : UpdatedOn : LockedBy : LockedOn" "DomainName : ParentDomain : Master : UpdatedBy : UpdatedOn : LockedBy" "EventRuleName : Type : Draft : Status : UpdatedOn : LockedBy" "JobDefinitionName : Workstation : TaskType : UpdatedBy : LockedBy" JobstreamName : Workstation : Draft : ValidFrom : ValidTo : UpdatedBy : UpdatedOn : LockedBy "ParameterName : LockedBy : UpdatedOn : LockedOn " "PromptName : LockedBy : UpdatedOn : LockedOn" "ResourceName : Workstation : Quantity : LockedBy : UpdatedOn : LockedOn " "UserName : Workstation : UpdatedBy : UpdatedOn : LockedBy" "WorkstationName : Type : Domain : OsType : Ignore : UpdatedBy : UpdatedOn : LockedBy"
| |
Event rule Job Job Stream
Parameter Prompt Resource
Windows User Workstation
215
display
Table 40. Output formats for displaying scheduling objects (continued) Object Type Workstation Class Output format if MAESTROCOLUMNS=80 "WorkstationClassName : Ignored : UpdatedOn : LockedBy" Output format if MAESTROCOLUMNS 120 "WorkstationClassName : Ignored : UpdatedBy : UpdatedOn : LockedBy"
See Offline output on page 190 for more information on how to set MAESTROCOLUMNS.
Examples
To display all calendars, run the following command:
display calendars=@
this is a sample output:

Calendar Name Updated By ---------------- -----------------------HOLIDAYS tws83 HOLIDAYS 01/01/2006 02/15/2006 05/31/2006 Calendar Name Updated By ---------------- -----------------------MONTHEND tws83 Updated On Locked By ---------- --------------------12/31/2005 tws83
Updated On Locked By ---------- --------------------01/01/2006 -
MONTHEND "Month end dates 1st half 2006" 01/31/2006 02/28/2006 03/31/2006 04/30/2006 05/31/2006 06/30/2006 Calendar Name Updated By ---------------- -----------------------PAYDAYS tws83 Updated On Locked By ---------- --------------------01/02/2006 -
PAYDAYS 01/15/2006 02/15/2006 03/15/2006 04/15/2006 05/14/2006 06/15/2006
To print the output of the display command on all job streams that are launched on workstation site2, run the following command:
di sched=site2#@;offline
See also
For the equivalent Job Scheduling Console task, see Working with Object Lists in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide. Event rule management is not available from the Job scheduling Console.
216
edit
edit
Edits a file.
Authorization
Syntax
edit filename
Arguments
filename The name of the file to be edited.
Comments
An editor is started and the specified file is opened for editing. See The composer editor on page 191 for more information.
Examples
To open the file mytemp for editing, run the following command:
edit mytemp
To open the file resfile for editing, run the following command:
ed resfile
See also
For the equivalent Job Scheduling Console task, see Managing database objects in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
217
exit
exit
Exits the composer command line program.
Authorization
Syntax
exit
Comments
When you are running the composer command line program in help mode, this command returns composer to command input mode.
Examples
To exit the composer command line program, run the following command:
exit
or:
e
218
help
help
Displays the on-line help for a command or displays the list of commands that can be issued from composer.
Authorization
Syntax
help [commandname]
Arguments
commandname The name of the composer command which you want to display on-line help about.
219
list, print
list, print
Lists, or prints summary information about objects defined in the Tivoli Workload Scheduler database. List provides you with the list of objects names with their attributes. Print sends the list of objects names with their attributes to the device or file specified in the MAESTROLP local variable. The print command can be used to send the output to a local printer, if the MAESTROLP variable is set accordingly.
Authorization
You must have display access to the object being listed, or printed if the enListSecChk option is set to yes on the master domain manager.
Syntax
| | | | | | | | | | | | | | | list | print {[calendars | {calendar | cal}=calname] | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [valid from date| valid to date |valid in date date] [full]] | [{users | user}=[workstationame#]username] | [{eventrule | erule | er}=eventrulename]} ;offline
Arguments
calendars calendar|cal Lists or prints all calendar definitions. Lists or prints calendar definitions. calname parms parm The name of the calendar. Wildcard characters are permitted.
Lists or prints all parameter definitions. Lists or prints parameter definitions. parmname The name of the parameter. Wildcard characters are permitted.
prompts prom
Lists or prints all prompt definitions. Lists or prints prompt definitions. promptname The name of the prompt. Wildcard characters are permitted.
Lists or prints all resource definitions. Lists or prints resource definitions. resourcename The name of the resource. Wildcard characters are permitted.
cpu
Lists or prints workstations, workstation classes, or domains. workstation The name of the workstation. Wildcard characters are permitted.
220
list, print
workstationclass The workstation class name specified in the job stream. Wildcard characters are permitted. domain The domain name specified in the job stream. Wildcard characters are permitted.
workstation|ws Lists or prints workstation definitions. workstationname The name of the workstation. Wildcard characters are permitted. domain|dom Lists or prints domain definitions. domainame The domain name specified in the job stream. Wildcard characters are permitted.
workstationclass|wscl Lists or prints workstation class definitions. workstationclassname The workstation class name specified in the job stream. Wildcard characters are permitted. jobs|jobdefinition|jd Lists or prints job definitions. workstation The name of the workstation on which the job runs. Wildcards are permitted. The default is the workstation on which composer is running. The name of the job. Wildcards are permitted.
jobname
sched|jobstream|js Lists or prints job stream definitions. workstation The name of the workstation on which the job stream runs. Wildcard characters are permitted. The default is the workstation on which composer is running. The name of the job stream. Wildcard characters are permitted. valid from date Restricts the selection to job streams that have a valid from date equal to the indicated value. The format is mm/dd/yy. date Restricts the selection to job streams that have a valid to date equal to the indicated value. The format is mm/dd/yy. date date The time frame during which the job stream can run. The format is mm/dd/yy - mm/dd/yy. One of the two dates can be represented by @.
jstream
valid to
valid in
users|user
Lists or prints the user definition. workstation The name of the workstation on which the user is
221
list, print
defined. Wildcard characters are permitted. The default is the workstation on which composer is running. username | | | | ;offline The user name. Wildcard characters are permitted.
eventrule|erule|er List or prints event rule definitions. eventrulename The name of the event rule definition. Wildcard characters are permitted.
Sends the output of the command to the composer output device. For information about this device, see UNIX variables on page 190. The list ..... ;offline command is equivalent to the print command.
Results
List provides you with the list of objects names with their attributes. Print sends the list of objects names with their attributes to the device or file set in the MAESTROLP local variable. The print command can be used to send the output to a local printer, if the MAESTROLP variable is set accordingly. Make sure the MAESTROLP is set in your environment before running the print command. Depending on the value set for in the MAESTROCOLUMNS local variable the different sets of information about the selected object can be shown. Table 41 shows an example of the output produced according to the value set for the MAESTROCOLUMNS variable.
Table 41. Output formats for printing scheduling objects Object Type Calendar Domain Output format if MAESTROCOLUMNS=80 "CalendarName : UpdatedBy : UpdatedOn : LockedBy" "DomainName : ParentDomain : Master : UpdatedOn : LockedBy "EventRuleName : Type : Draft : Status : UpdatedOn : LockedBy" "JobDefinitionName : Workstation : LockedBy" Output format if MAESTROCOLUMNS 120 "CalendarName : UpdatedBy : UpdatedOn : LockedBy : LockedOn" "DomainName : ParentDomain : Master : UpdatedBy : UpdatedOn : LockedBy" "EventRuleName : Type : Draft : Status : UpdatedOn : LockedBy" "JobDefinitionName : Workstation : TaskType : UpdatedBy : LockedBy"
| |
Event rule Job Job Stream
"JobstreamName : Workstation : "JobstreamName : Workstation : Draft Validfrom : UpdatedOn : LockedBy" : ValidFrom : ValidTo : UpdatedBy : UpdatedOn : LockedBy" "ParameterName : LockedBy" "PromptName : LockedBy " "ResourceName : Workstation : Quantity : LockedBy " "UserName : Workstation : LockedBy" "WorkstationName : Type : Domain : UpdatedOn : LockedBy" "ParameterName : LockedBy : UpdatedOn : LockedOn " "PromptName : LockedBy : UpdatedOn : LockedOn" "ResourceName : Workstation : Quantity : LockedBy : UpdatedOn : LockedOn " "UserName : Workstation : UpdatedBy : UpdatedOn : LockedBy" "WorkstationName : Type : Domain : OsType : Ignore : UpdatedBy : UpdatedOn : LockedBy"
Parameter Prompt Resource
Windows User Workstation
222
list, print
Table 41. Output formats for printing scheduling objects (continued) Object Type Workstation Class Output format if MAESTROCOLUMNS=80 "WorkstationClassName : Ignored : UpdatedOn : LockedBy" Output format if MAESTROCOLUMNS 120 "WorkstationClassName : Ignored : UpdatedBy : UpdatedOn : LockedBy"
See Offline output on page 190 for more information on how to set MAESTROLP.
Examples
v To list all calendars, run the following command:
list calendars=@
this is a sample output:

Calendar Name ---------------HOLIDAYS PAYDAYS MONTHEND AWSBIA291I Total list er=@ Updated By -----------------------tws83 tws83 tws83 objects: 3 Updated On ---------03/02/2006 03/02/2006 03/02/2006 Locked By ---------------------
v To list all your defined event rules, run the following command:
If MAESTROCOLUMNS=80, the output looks something like this:

Event Rule Name ---------------EVENT-MULTIPLE1 EVENT-MULTIPLE2 EVENT-MULTIPLE3 M_SUCC_12_S M_SUCC_12_S_A M_SUCC_12_S_B NEWEVENTRULE Type --------filter filter filter sequence filter filter filter Draft Status Updated On ----- --------- ---------active 06/06/2007 active 06/06/2007 active 06/06/2007 Y inactive 06/07/2007 active 06/07/2007 Y inactive 06/07/2007 active 06/01/2007 Locked By ------------administrator
If MAESTROCOLUMNS120, the output looks something like this:

Event Rule Name --------------------EVENT-MULTIPLE1 EVENT-MULTIPLE2 EVENT-MULTIPLE3 M_SUCC_12_S M_SUCC_12_S_A M_SUCC_12_S_B NEWEVENTRULE Type Draft Status Updated On Locked By --------- ----- -------- ---------- --------filter active 06/06/2007 filter active 06/06/2007 filter active 06/06/2007 sequence Y inactive 06/07/2007 filter active 06/07/2007 filter Y inactive 06/07/2007 filter active 06/01/2007 administrator
See also
For the equivalent Job Scheduling Console task, see Working with Object Lists in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide. Event rule management is not available form the Job Scheduling Console.
223
lock
lock
Locks the access to scheduling objects definitions in the database.
Authorization
You must have modify access to the object.
Syntax
| | | | | | | | | | | | | | lock {[calendars | {calendar | cal}=calname] | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [valid from date| valid to date |valid in date date] [full]] | [{users | user}=[workstationame#]username] | [{eventrule | erule | er}=eventrulename]}
Arguments
calendars calendar|cal Locks all calendar definitions. Locks calendar definitions. calname parms parm The name of the calendar. Wildcard characters are permitted.
Locks all parameter definitions. Locks parameter definitions. parmname The name of the parameter. Wildcard characters are permitted.
prompts prom
Locks all prompt definitions. Locks prompt definitions. promptname The name of the prompt. Wildcard characters are permitted.
Locks all resource definitions. Locks resource definitions. resourcename The name of the resource. Wildcard characters are permitted.
cpu
Locks workstations, workstation classes, or domains. workstation workstationclass The workstation class name specified in the job stream. Wildcard characters are permitted. domain The domain name specified in the job stream. Wildcard characters are permitted. The name of the workstation. Wildcard characters are permitted.
224
lock
workstation|ws Locks workstation definitions. workstationname The name of the workstation. Wildcard characters are permitted. domain|dom Locks domain definitions. domainame The domain name specified in the job stream. Wildcard characters are permitted.
workstationclass|wscl Locks workstation class definitions. workstationclassname The workstation class name specified in the job stream. Wildcard characters are permitted. jobs|jobdefinition|jd Locks job definitions. workstation The name of the workstation on which the job runs. Wildcards are permitted. The default is the workstation on which composer is running. The name of the job. Wildcards are permitted.
jobname
sched|jobstream|js Locks job stream definitions. workstation The name of the workstation on which the job stream runs. Wildcard characters are permitted. The default is the workstation on which composer is running. The name of the job stream. Wildcard characters are permitted. valid from date Restricts the selection to job streams that have a valid from date equal to the indicated value. The format is mm/dd/yy. date Restricts the selection to job streams that have a valid to date equal to the indicated value. The format is mm/dd/yy. date date The time frame during which the job stream can run. The format is mm/dd/yy - mm/dd/yy. One of the two dates can be represented by @.
jstream
valid to
valid in
users|user
Locks the user definition. workstation The name of the workstation on which the user is defined. Wildcard characters are permitted. The default is the workstation on which composer is running. The user name. Wildcard characters are permitted.
username
225
lock
| | | | eventrule|erule|er Locks event rule definitions. eventrulename The name of the event rule definition. Wildcard characters are permitted.
Comments
Objects are locked to make sure that definitions in the database are not overwritten by different users accessing concurrently to the same objects. With this command the user explicitly acquires locks of database objects. When one user has an object locked, any other user has read only access until the object is released or explicitly unlocked by the administrator. If one user tries to lock an object that is already locked by someone else (other user), an error message is returned. Locks on database objects are acquired by the user using username and session, where session is a string that can be set in the environment variable TWS_SESSION identifying that specific user work session. This means that, on a machine, the TWS_SESSION identifier is different for: v a user connected in two different shells to the composer command line program. v a user connected, disconnected and then connected again to the composer command line from the same shell. If no value is assigned to TWS_SESSION, then the default value identifying the session is set as follows: v If using composer in batch mode, the default value is the username used by the user when connecting to the master domain manager. v If using composer in interactive mode, the default value corresponds to an alphanumeric string automatically created by the product. Note: In the database the username of the user locking an object definition is saved in uppercase.
Examples
To lock calendar named Holiday run the command:
lock calendar=HOLIDAYS
See also
For the equivalent Job Scheduling Console task, see Managing database objects in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide. Event rule management is not available form the Job Scheduling Console.
226
modify
modify
Modifies or adds scheduling objects. When modifying objects, the modify command extracts only the objects that can be locked by the current user.
Authorization
You must have add access if you add a new scheduling object. If the object already exists in the database, you must have modify access to the object.
Syntax
| | | | | | | | | | | | | | modify {[calendars | {calendar | cal}=calname] | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [valid from date| valid to date |valid in date date] [full]] | [{users | user}=[workstationame#]username] | [{eventrule | erule | er}=eventrulename]}
Arguments
calendars calendar|cal Modifies all calendar definitions. Modifies calendar definitions. calname parms parm The name of the calendar. Wildcard characters are permitted.
Modifies all parameter definitions. Modifies parameter definitions. parmname The name of the parameter. Wildcard characters are permitted.
prompts prom
Modifies all prompt definitions. Modifies prompt definitions. promptname The name of the prompt. Wildcard characters are permitted.
Modifies all resource definitions. Modifies resource definitions. resourcename The name of the resource. Wildcard characters are permitted.
cpu
Modifies workstations, workstation classes, or domains. workstation workstationclass The workstation class name specified in the job stream. Wildcard characters are permitted.
The name of the workstation. Wildcard characters are permitted.
227
modify
workstation|ws Modifies workstation definitions. workstationname The name of the workstation. Wildcard characters are permitted. domain|dom Modifies domain definitions. domainame The domain name specified in the job stream. Wildcard characters are permitted.
workstationclass|wscl Modifies workstation class definitions. workstationclassname The workstation class name specified in the job stream. Wildcard characters are permitted. jobs|jobdefinition|jd Modifies job definitions. workstation The name of the workstation on which the job runs. Wildcards are permitted. The default is the workstation on which composer is running. The name of the job. Wildcards are permitted.
jobname
sched|jobstream|js Modifies job stream definitions. workstation The name of the workstation on which the job stream runs. Wildcard characters are permitted. The default is the workstation on which composer is running. The name of the job stream. Wildcard characters are permitted. valid from date Restricts the selection to job streams that have a valid from date equal to the indicated value. The format is mm/dd/yy. date Restricts the selection to job streams that have a valid to date equal to the indicated value. The format is mm/dd/yy. date date The time frame during which the job stream can run. The format is mm/dd/yy - mm/dd/yy. One of the two dates can be represented by @.
jstream
valid to
valid in
full users|user
Modifies all job definitions contained in the job stream.
Modifies the user definition. workstation The name of the workstation on which the user is
228
modify
defined. Wildcard characters are permitted. The default is the workstation on which composer is running. username | | | | The user name. Wildcard characters are permitted.
eventrule|erule|er Modifies or adds event rule definitions. eventrulename The name of the event rule definition. Wildcard characters are permitted.
Comments
The modify command performs the following sequence of actions: 1. Copies the objects definition into a temporary file. 2. Locks the objects in the database. 3. Edits the file. 4. Replaces the definition contained in the temporary file to the database. 5. If the modify command fails on a subset of the selected objects, composer asks do you want to re-edit? and the file saved before is reopened for editing and the next steps of the sequence are repeated. 6. Unlocks the objects in the database. | | | Event rule definitions are opened with an XML editor (see Event rule definition on page 178 for XML reference and see The composer editor on page 191 for details on setting up an XML editor). If you modify with the same modify command two or more objects linked together by any relationship, for example a successor job and its predecessor job, then it might be relevant for the successful result of the modify command the order in which the objects are listed in the temporary file. This happens because the modify command reads in sequence the objects contained in the temporary file; so, if the referencing object is displayed before the object being referenced, the modify command might fail on the referencing object. For example, if the command:
modify FTA1#@PROVA
produces the following temporary file:

SCHEDULE FTA1#PROVA VALIDFROM 08/31/2005 MATCHING SAMEDAY : FTA2#MY-JOB FOLLOWS FTA1#COPYOFPROVA.MY-JOB06 END SCHEDULE FTA1#COPYOFPROVA VALIDFROM 08/31/2005 MATCHING SAMEDAY : FTA1#MY-JOBO6 END
and you change the name of the predecessor job from FTA1#MY-JOB06 to FTA1#MY-JOB05 in both job streams FTA1#PROVA and FTA1#COPYOFPROVA, then the modify command:
229
modify
1. At first tries to change the definition of job stream FTA1#PROVA and it fails because it finds a follows dependency from a job FTA1#MY-JOB05 which is still unknown. 2. Then it tries to change the definition of FTA1#COPYOFPROVA and it succeeds. The second time you run modify to change the predecessor job from FTA1#MY-JOB06 to FTA1#MY-JOB05 in job stream FTA1#PROVA, the command is successfully performed since the predecessor job FTA1#MY-JOB05 now exists in the database. If job stream FTA1#COPYOFPROVA had been listed in the temporary file before FTA1#PROVA, then the modify command would have run successfully the first time because the name of the predecessor job would have been modified before changing the dependency definition in the successor job. For user definitions, if the password field keeps the "*******" value when you exit the editor, the old password is retained. To specify a null password use two consecutive double quotes (). The modify command checks for loop dependencies inside job streams. For example, if job1 follows job2, and job2 follows job1 there is a loop dependency. When a loop dependency inside a job stream is found an error is displayed. The modify command does not check for loop dependencies between job streams because, depending on the complexity of the scheduling activities, this check might be too time and CPU consuming.
Examples
To modify all calendars, run the following command:
modify calendars=@
To modify job stream sked9 that is launched on workstation site1, run the following command:
m sched=site1#sked9
| | |
To modify all the event rules that include an action with job DPJOB10, run:
mod er=@;filter job=DPJOB10
See also
For the equivalent Job Scheduling Console task, see Managing database objects in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide. Event rule management is not available form the Job Scheduling Console.
230
new
new
Adds a new scheduling object definition in the database.
Authorization
You must have add access if you add a new scheduling object. If the object already exists in the database you must have modify access to the object.
Syntax
| | | | | | | | | | | | | | | | | | | | | | new [calendar | domain | eventrule | job | jobstream | parameter | prompt | resource | user | workstation | workstation_class]
Arguments
The object you want to define: a calendar, a domain, an event rule, a job, a job stream, a parameter, a prompt, a resource, a user, a workstation, or a workstation class.
Comments
The command opens a predefined template that helps you edit the object definition and adds it in the database when you save it. The object templates are located in the templates subfolder in the Tivoli Workload Scheduler installation directory. They can be customized to fit your preferences. Event rule definitions are opened with an XML editor (see Event rule definition on page 178 for XML reference and see The composer editor on page 191 for details on setting up an XML editor).
Examples
To create a new user definition, run:
new user
To create a new prompt definition, run:

new prompt
To create a new event rule definition, run:

new erule
231
redo
redo
Edits and runs the previous command again. Note: If the previous command was authenticate, redo does not display the password specified.
Authorization
Syntax
redo
Context
When you run the redo command, composer displays the previous command, so that it can be edited and run again. Use the spacebar to move the cursor under the character to be modified, and enter the following directives. Directives d[dir] itext rtext Deletes the character above the d. This can be followed by other directives. Inserts text before the character above the i. Replaces one or more characters with text, beginning with the character above the r. Replace is implied if no other directive is entered. Appends text to the end of the line.
>text
>d[dir | text] Deletes characters at the end of the line. This can be followed by another directive or text. >rtext Replaces characters at the end of the line with text.
Directive Examples ddd iabc rabc abc d diabc Deletes the character above the first d, skips one character, deletes the character above the second d, and inserts abc in its place. >abc >ddabc Deletes the last two characters in the line, and inserts abc in their place. >rabc Replaces the last three characters in the line with abc. Appends abc to the end of the line. Deletes the three characters above the ds. Inserts abc before the character above the i. Replaces the three characters, starting with the one above the r, with abc. Replaces the three characters above abc with abc.
232
redo
Examples
To insert a character, run the following command:
redo dislay site1#sa@ ip display site1#sa@
To replace three characters, for example change site into serv by replacing ite with erv, run the following command:
redo display site1#sa@ rerv display serv1#sa@
233
rename
rename
Renames a scheduling object already existing in the database. The new name must not identify an object already defined in the database.
Authorization
You must have modify access to the object with the old name and add access to the object with the new name.
Syntax
| | | | | | | | | | | | | | rename {calendars|calendar|cal | parms|parm | prompts|prom | resorces|resource|res | workstation|ws | workstationclass|wscl | domain|dom | jobs|jobdefinition|jd | jobsched|jb | eventrule|erule|er sched|jobstream|js | users|user } old_object_identifier new_object_identifier
Arguments
old_object_identifier Specifies the old external key identifying the scheduling object, for example calendar name cal1 as identifier for a defined calendar object to be renamed. new_object_identifier Specifies the new external key identifying the scheduling object, for example calendar name cal2 as new identifier to be assigned to calendar object previously named cal1. For what concerns jobs, job streams, resources and Windows users both the old_object_identifier and new_object_identifier have the following formats: [workstationame#]jobname The command applies to this job definition. This format is used with the jobs|jobdefinition|jd key. [workstationame#]jstreamname The command applies to all versions of this job stream. This format is used with the sched|jobstream|js key. [workstationame#]jstreamname+valid from date The command applies only to this version of this job stream. This format is used with the sched|jobstream|js key. [workstationame#]jstreamname.jobname The command applies to this job instance defined in this job stream. See the js keyword in the Job stream definition on page 133 syntax for additional details. This format is used with the jobsched|jb key. [workstationame#]resourcename The command applies to this resource definition. This format is used with the resources|resource|res key.
234
rename
[workstationame#][domain\]username The command applies to this Windows user definition. This format is used with the users|user key.
Comments
To be renamed the object must be unlocked or locked by the user who issues the rename command. If an object named as specified in the old_object_identifier field does not exist in the database an error message is displayed. The use of wild cards is not allowed with this command. When workstationame is not specified for objects that have the workstation name as part of their object identifier (for example, job or job stream definitions), the scheduler uses one of the following for workstationame: v The default workstation specified in the localopts file v The master domain manager if the composer command line program is running on a node outside the Tivoli Workload Scheduler network. In this case, in fact, the default workstation set in the localopts file is the master domain manager. The rename command is used to assign new names to objects already existing in the database. The new name assigned to an object becomes immediately effective in the database, while it becomes effective in the plan after the JnextPlan script is run again. This can lead to incongruences when submitting ad-hoc jobs before generating again the production plan.
Examples
To rename domain object DOMAIN1 to DOMAIN2 , run the following command:
rename dom=DOMAIN1 DOMAIN2
To rename job stream LABJST1 to LABJST2 on workstation CPU1, run the following command:
rename js=CPU1#LABJST1 CPU1#LABJST2
See also
235
replace
replace
Replaces scheduling object definitions in the database.
Authorization
You must have add access if you add a new scheduling object. If the object already exists in the database you must have: v modify access to the object if the object is not locked. v modify and unlock accesses to the object if you want to use the ;unlock option against objects locked by other users.
Syntax
replace filename;unlock
Arguments
filename Specifies the name of a file containing the object definitions to replace. The file can contain all types of scheduling objects definition. unlock Updates existing objects previously locked and unlocks them. An error is displayed if the objects are not previously locked. For all new objects inserted, this option, if specified, is ignored.
Comments
The replace command is similar to the add command, except that there is no confirmation prompt to replace existing objects. For more information, refer to add on page 203. The replace command checks for loop dependencies inside job streams. For example, if job1 follows job2, and job2 follows job1 there is a loop dependency. When a loop dependency inside a job stream is found an error is displayed. The replace command does not check for loop dependencies between job streams because, depending on the complexity of the scheduling activities, this check might be too time and CPU consuming.
Examples
To replace the jobs from the file myjobs, run the following command:
replace myjobs
To replace all resources with those contained in the file myres, run the following command:
rep myres
| | | | |
You want to change some existing event rule definitions in the database. You also want to add some new ones as well. You use this command in the following way: 1. You write the entire definitions in an XML file you name 2Q07rules.xml. 2. You run:
rep 2Q07rules.xml
See also
236
system command
system command
Runs a system command.
Syntax
[: | !] sys-command
Arguments
sys-command Specifies any valid system command. The prefix of colon (:) or exclamation mark (!) is required only when the command is spelled the same as a composer command.
Examples
To run a ps command on UNIX, run the following command:
ps -ef
To run a dir command on Windows, run the following command:

dir \bin
237
unlock
unlock
Releases access locks on scheduling objects defined in the database. By default to unlock an object, the object must have been locked using the same user and session.
Authorization
You must have the unlock access to unlock objects locked by other users.
Syntax
| | | | | | | | | | | | | | | unlock {[calendars | {calendar | cal}=calname] | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [valid from date| valid to date |valid in date date] [full]] | [{users | user}=[workstationame#]username] | [{eventrule | erule | er}=eventrulename]} [;forced]
Arguments
calendars calendar|cal Unlocks all calendar definitions. Unlocks calendar definitions. calname parms parm The name of the calendar. Wildcard characters are permitted.
Unlocks all parameter definitions. Unlocks parameter definitions. parmname The name of the parameter. Wildcard characters are permitted.
prompts prom
Unlocks all prompt definitions. Unlocks prompt definitions. promptname The name of the prompt. Wildcard characters are permitted.
Unlocks all resource definitions. Unlocks resource definitions. resourcename The name of the resource. Wildcard characters are permitted.
cpu
Unlocks workstations, workstation classes, or domains. workstation workstationclass The workstation class name specified in the job stream. Wildcard characters are permitted. The name of the workstation. Wildcard characters are permitted.
238
unlock
workstation|ws Unlocks workstation definitions. workstationname The name of the workstation. Wildcard characters are permitted. domain|dom Unlocks domain definitions. domainame The domain name specified in the job stream. Wildcard characters are permitted.
workstationclass|wscl Unlocks workstation class definitions. workstationclassname The workstation class name specified in the job stream. Wildcard characters are permitted. jobs|jobdefinition|jd Unlocks job definitions. workstation The name of the workstation on which the job runs. Wildcards are permitted. The default is the workstation on which composer is running. The name of the job. Wildcards are permitted.
jobname
sched|jobstream|js Unlocks job stream definitions. workstation The name of the workstation on which the job stream runs. Wildcard characters are permitted. The default is the workstation on which composer is running. The name of the job stream. Wildcard characters are permitted. valid from date Restricts the selection to job streams that have a valid from date equal to the indicated value. The format is mm/dd/yy. date Restricts the selection to job streams that have a valid to date equal to the indicated value. The format is mm/dd/yy. date date The time frame during which the job stream can run. The format is mm/dd/yy - mm/dd/yy. One of the two dates can be represented by @.
jstream
valid to
valid in
users|user
Unlocks the user definition. workstation The name of the workstation on which the user is defined. Wildcard characters are permitted. The default is the workstation on which composer is running.
239
unlock
username | | | | forced The user name. Wildcard characters are permitted.
eventrule|erule|er Unlocks event rule definitions. eventrulename The name of the event rule definition. Wildcard characters are permitted.
If specified, allows the user who locked the object to unlock it regardless of the session. If this option is used by the superuser, then the unlock command can operate regardless to the user and the session used to lock the object.
Comments
If a user, other than the superuser, tries to unlock an object that is locked by another user, an error message is returned. If the object is not locked when the unlock command is issued against it, a warning message is returned.
Examples
To unlock job definition JOBDEF1, run the following command:
unlock jd=@#JOBDEF1
| |
To unlock event rule definition ERJS21, run the following command:

unlock erule=ERJS21
See also
240
validate
validate
Performs the validation of the object definitions contained in a user file.
Authorization
You do not need any specific authorization to objects to run this command.
Syntax
validate filename [;syntax]
Arguments
filename | | | | | Specifies the name of a file that contains calendars, workstations, workstation classes, domains, jobs, parameters, prompts, resources, job streams, or event rules. For event rule definitions the file must be in the XML language. See Event rule definition on page 178 for details on writing event rule definitions. syntax Checks the file for syntax errors.
Comments
For job streams, if the syntax option is omitted, validation and reporting include the following: v Verify job names against the master job file. v Examine dependencies to ensure that the objects exist. Dependencies on nonexistent objects are reported. The output of the validate command can be redirected to a file as follows:
composer "validate filename" > outfile
To include error messages in the output file, use the following:

composer "validate filename" > outfile 2>&1
Examples
To check the syntax of a file containing workstation definitions, run the following command:
validate mycpus;syntax
To validate all job streams, run the following command:

create allskeds from sched=@#@ validate allskeds
You can do this to verify the integrity of references to other scheduling objects after changes have been made.
241
version
version
Displays the composer command line program banner.
Authorization
Syntax
version
Examples
To display the composer command line program banner, run the following command:
version
or:
v
242
Chapter 9. Managing objects in the plan - conman

The Tivoli Workload Scheduler production plan environment is managed using the conman command-line program. The conman program is used to start and stop processing, alter and display the Symphony production plan, and control workstation linking in a network. It can be used from the master domain manager and from any fault-tolerant agent in the Tivoli Workload Scheduler network. This chapter is divided into the following sections: v What is new in managing objects in production v Using the conman command line program v Running commands from conman on page 247 v v v v | | | | | | | | | | | | | | | | Selecting jobs in commands on page 249 Selecting job streams in commands on page 257 Managing jobs and job streams from back-level agents on page 263 Command descriptions on page 264
What is new in managing objects in production

This section gives a quick reference to the enhancements to managing objects in the plan included in Tivoli Workload Scheduler version 8.4. The enhancements are provided by new commands that you can use to: v Download the latest monitoring configuration for the event monitoring engine on the workstation. See deployconf on page 285 for details. v Start and stop the WebSphere Application Server process. See startappserver on page 345 and stopappserver on page 352 for details. v Manage (start, stop, switch) the new event processing server used in event-driven workload automation. See starteventprocessor on page 346, stopeventprocessor on page 353, and switcheventprocessor on page 366 for details. v Manage the new monitoring agent used in event-driven workload automation. See startmon on page 347 and stopmon on page 354 for details. The showcpus command is enhanced with the new getmon keyword that returns a list of event rules defined for the monitor running on a workstation.
Using the conman command line program

The conman command-line program manages the production plan environment. You can use the conman program from the master domain manager and from any fault-tolerant agent workstation in the Tivoli Workload Scheduler network.
Setting up the conman environment

This section gives you the information about the setup you can choose for your conman environment. Note: On Windows systems, before running conman ensure the code-page and fonts are correctly set in the DOS shell to avoid bad character conversion.
243

For additional information on the required settings refer to the Internationalization notes section in the IBM Tivoli Workload Scheduler: Release Notes.
Terminal output
The output to your computer is determined by the shell variables named MAESTROLINES and MAESTROCOLUMNS. If either is not set, the standard shell variables, LINES and COLUMNS, are used. The variables can be set as follows: MAESTROLINES Specifies the number of lines per screen. The default is 24. At the end of each screen page, conman prompts to continue. If MAESTROLINES (or LINES) is set to zero or a negative number, conman does not pause at the end of a page. MAESTROCOLUMNS Specifies the number of characters per line. The default is 80. MAESTRO_OUTPUT_STYLE Specifies how object names are displayed. If set to LONG, full names are displayed. If not set, or set to any value other than LONG, long names are truncated to eight characters followed by a plus sign (+).
Offline output
The ;offline option in conman commands is generally used to print the output of a command. When you include it, the following shell variables control the output: MAESTROLP Specifies the destination of a commands output. Set it to one of the following: > file Redirects output to a file and overwrites the contents of that file. If the file does not exist, it is created.
>> file Redirects output to a file and appends the output to the end of that file. If the file does not exist, it is created. | command Pipes output to a system command or process. The system command is run whether or not output is generated. || command Pipes output to a system command or process. The system command is not run if there is no output. The default value for MAESTROLP is | lp -tCONLIST which pipes the command output to the printer and places the title CONLIST in the printouts banner page. MAESTROLPLINES Specifies the number of lines per page. The default is 60. MAESTROLPCOLUMNS Specifies the number of characters per line. The default is 132. The variables must be exported before running conman.
Selecting the conman prompt on UNIX

The conman command prompt is, by default, a percent sign (%). This is defined in the TWS_home/localopts file. The default command prompt is a dash (-). To select a
244

different prompt, edit the conman prompt option in the localopts file and change the dash. The prompt can be up to 10 characters long, not including the required trailing pound sign (#).
#---------------------------------------------------------------------------# Custom format attributes # date format = 1 # The possible values are 0-ymd, 1-mdy, 2-dmy, 3-NLS. composer prompt = conman prompt = % switch sym prompt = <n>% #----------------------------------------------------------------------------
Running conman
To configure the environment for using conman set the PATH and TWS_TISDIR variables by running one of the following scripts: In UNIX: v . ./TWS_home/tws_env.sh for Bourne and Korn shells v . ./TWS_home/tws_env.csh for C shells In Windows: v TWS_home\tws_env.cmd Then use the following syntax to run commands from the conman user interface: conman [connection_parameters] [command[&[command]...] [&]] where: connection_parameters Represents the set of parameters that rule the interaction between the product interface, conman running on the master domain manager in this case, and the WebSphere Application Server infrastructure using HTTP or HTTPS. Use this syntax to specify the settings for the connection parameters: [-host hostname] [-port port_number] [-protocol protocol_name] [-proxy proxy_name] [-proxyport proxy_port_number] [-password user_password] [-timeout timeout] [-username username] where: hostname Is the hostname of the master domain manager. port_number Is the port number used when establishing the connection with the master domain manager. protocol_name Is the protocol used during the communication. It can be HTTP with basic authentication or HTTPS with certificate authentication. proxy_name Is the proxy hostname used in the connection with HTTP. proxy_port_number Is the proxy port number used in the connection with HTTP.
245
Running conman
user_password Is the password of the user that is used to run conman. | | | | | timeout Is the maximum time, expressed in seconds, the connecting command-line program can wait for the master domain manager response before considering the communication request as failed. username Is the user ID of the user running conman. This user name must be authorized to run the specific conman commands in the security file both on the connecting workstation and on the master domain manager, where the command actually runs. If any of these parameters is omitted when invoking conman, Tivoli Workload Scheduler searches for the value first in the useropts file and then in the localopts file. If a setting for the parameter is not specified either in the connection parameters when invoking the command or inside the useropts and localopts files then an error is displayed. Refer toSetting up options for using the user interfaces on page 29 for information on useropts and localopts files. You can invoke the conman command-line both in batch and in interactive mode. When running conman in interactive mode, you at first launch the conman command-line program and then, from the conman command-line prompt you run commands a time, for example:
conman username admin2 password admin2pwd ss @+state=hold;deps dds sked5;needs=2 tapes
Note: On Windows workstations, when you specify a password that contains double quotation marks (") or other special characters, make sure that the character is escaped. For example, if your password is tws11"tws, write it as "tws11\"tws".
When running conman in batch mode, you first launch the conman command-line program specifying as input parameter the command to be issued. Once the command is processed, the conman command-line program exits, for example
conman"sj&sp"
When issuing commands from conman in batch mode make sure you enclose the commands between double quotes. The following are examples of using batch mode to issue more than one command from within conman: v conman runs the sj and sp commands, and then quits:
conman "sj&sp"
v conman runs the sj and sp commands, and then prompts for a command:
conman "sj&sp&"
v conman reads commands from the file cfile:

conman < cfile
v commands from the file cfile are piped to conman:

cat cfile | conman
Control characters
You can enter the following control characters to interrupt conman.
246
Running conman
Control+c conman stops running the current command at the next step that can be interrupted, and returns a command prompt. Control+d conman quits after running the current command, on UNIX workstations only.
Running system commands

When you enter a system command using a pipe or a system command prefix (: or !), it is run by a child process. The child processs effective user ID is set to the ID of the user running conman to prevent security breaches.
User prompting
When you use wildcard characters to select the objects to be acted upon by a command, conman prompts for confirmation after finding each matching object. Responding with yes allows the action to be taken, and no skips the object without taking the action. When you run conman interactively, the confirmation prompts are issued at your computer. Pressing the Return key in response to a prompt is interpreted as a no response. Prompting can be disabled by including the ;noask option in a command. Although no confirmation prompts are issued when conman is not running in interactive mode, it acts as though the response had been no in each case, and no objects are acted on. It is important, therefore, to include the ;noask option on commands when conman is not run in interactive mode.
Running commands from conman

conman commands consist of the following elements: commandname selection arguments where: commandname Specifies the command name. selection Specifies the object or set of objects to be acted upon. arguments Specifies the command arguments. The following is an example of a conman command:
sj sked1(1100 03/05/2006).@+state=hold~priority=0;info;offline
where: sj The abbreviated form of the showjobs command.
sked1(1100 03/05/2006).@+state=hold~priority=0 Selects all jobs in the job stream sked1(1100 03/05/2006) that are in the HOLD state with a priority other than zero. ;info;offline Arguments for the showjobs command.
247
Wildcards
Wildcards
The following wildcard characters are permitted: @ ? % Replaces one or more alphanumeric characters. Replaces one alphanumeric character. Replaces one numeric character.
Delimiters and special characters

Table 42 lists characters have special meanings in conman commands:
Table 42. Delimeters and special characters for conman Char. & + Description Command delimiter. See Using the conman command line program on page 243. A delimiter used to select objects for commands. It adds an attribute the object must have. For example: sked1(1100 03/05/2006).@~priority=0 A delimiter used to select objects for commands. It adds an attribute the object must not have. For example: sked1(1100 03/05/2006).@~priority=0 ; , = :! Argument delimiter. For example: ;info;offline Repetition and range delimiter. For example: state=hold,sked,pend Value delimiter. For example: state=hold Command prefixes that pass the command on to the system. These prefixes are optional; if conman does not recognize the command, it is passed automatically to the system. For example: !ls or :ls * Comment prefix. The prefix must be the first character on a command line or following a command delimiter. For example: *comment or sj& *comment > Redirects command output to a file and overwrites the contents of that file. If the file does not exist, it is created. For example: sj> joblist >> Redirects command output to a file and appends the output to the end of that file. If the file does not exist, it is created. For example: sj >> joblist | Pipes command output to a system command or process. The system command is run whether or not output is generated. For example: sj| grep ABEND || Pipes command output to a system command or process. The system command is not run if there is no output. For example: sj || grep ABEND
248
Conman commands processing
Conman commands processing

The conman program performs the commands that change the status of objects, such as start or stop for a workstation, and the commands that modify objects in the plan in an asynchronous way. This means that you might notice a delay between the time you submit the command and the time the information stored in the Symphony file is updated with the result of the command. This occurs because the conman program does not update the information stored in the Symphony file; conman submits the commands to batchman which is the only process which can access and update the information contained in the Symphony file. For this reason you need to wait for batchman to process the request of modifying the object issued by conman and then to update the information about the object stored in the Symphony file before seeing the updated information in the output of the showobj command. For example, if you request to delete a dependency using the conman deldep command, conman submits the deldep command by posting an event in the Mailman.msg mailbox. The mailman process gets the information about the deletion request from Mailman.msg and puts it in the Intercom.msg mailbox on the workstation that owns the resource you delete the dependency from. On each workstation, batchman receives the events in its Intercom.msg mailbox and processes them in the same order as they were received. If batchman is busy for any reason, events carrying requests to perform conman commands continue being queued in the Intercom.msg file waiting to be read and processed by batchman. In addition, when batchman processes the event, the operator is not notified. As a result, you could delete a dependency and it might appear that it had not been deleted because batchman was too busy to immediately perform the requested operation. If you run the command again, the deletion might have already been successful, even though a message saying that the command has been successfully forwarded to batchman is displayed in the conman prompt.
Selecting jobs in commands

For commands that operate on jobs, the target jobs are selected by means of attributes and qualifiers. The job selection syntax is shown below, and described on the following pages.
Syntax
[workstation#] {jobstreamname(hhmm[ date]) job | jobnumber} [{+ | ~}jobqualifier[...]] or [workstation#]jobstream_id.job [{+ | ~]jobqualifier[...]];schedid or: netagent::[workstation#] {jobstream(hhmm[ date]).job | jobstream_id.job;schedid}
Arguments
workstation When used with jobstream.job, this specifies the name of the workstation on which the job stream runs. When used with jobnumber, it specifies the workstation on which the job runs. Wildcard characters are permitted.
249

jobstreamname Specifies the name of the job stream in which the job runs. Wildcard characters are permitted. (hhmm [date]) Indicates the time and date the job stream instance is located in the preproduction plan. The value hhmm corresponds to the value assigned to the schedtime keyword in the job stream definition if no at time constraint was set. After the job stream instance started processing, the value of hhmm [date] is set to the time the job stream started. The use of wildcards in this field is not allowed. When issuing inline conman commands from the shell prompt enclose the conman command in double quotes " ". For example, run this command as follows:
conman "sj my_workstation#my_js(2101 02/23).@"
jobstream_id Specifies the unique job stream identifier. See page 257 for more information on job stream identifier. schedid Indicates that the job stream identifier is used in selecting the job stream. jobname Specifies the name of the job. Wildcard characters are permitted. jobnumber Specifies the job number. jobqualifier See the following section, Job qualifiers. netagent Specifies the name of the Tivoli Workload Scheduler network agent that interfaces with the remote Tivoli Workload Scheduler network containing the target job. The two colons (::) are a required delimiter. Wildcard characters are permitted. For more information refer to Chapter 15, Managing internetwork dependencies, on page 499. Note: Tivoli Workload Scheduler helps you to identify the correct job stream instance when the job stream selection provides an ambiguous result if more than one instance satisfy your selection criteria. For example when more than one instances of WK1#J1 are included in the production plan and so the job stream selection provides an ambiguous result the following prompt is automatically generated to allow you to choose the correct instance:
Process WK1#J1[(0600 03/04/06),(0AAAAAAAAAAAABTB)] (enter "y" for yes, "n" for no)?y Command forwarded to batchman for WK1#J1[(0600 03/04/06),(0AAAAAAAAAAAABTB)] Process WK1#J1[(1010 03/04/06),(0AAAAAAAAAAAABTC)] (enter "y" for yes, "n" for no)?n
In the output only the job stream instance scheduled on (0600 03/04/06) and with identifier 0AAAAAAAAAAAABTB is selected to run the command.
Job qualifiers
Job qualifiers specify the attributes of jobs to be acted on by a command. They can be prefixed by + or ~. If a job qualifier is preceded by + then the jobs containing that specific attribute are selected for running the command. If a job qualifier is preceded by ~ then the jobs containing that specific attribute are excluded from running the command.
250

Job qualifier keywords can be abbreviated to as few leading characters as needed to uniquely distinguish them from each other. at[=time | lowtime, | ,hightime | lowtime,hightime ] Selects or excludes jobs based on the time specified in the at dependency. time Specifies the time as follows: hhmm[+n days | date] [timezone|tz tzname] where: hhmm The hour and minute.
+n days The next occurrence of hhmm in n number of days. date The next occurrence of hhmm on date, expressed as mm/dd[/yy].
timezone|tz tzname The name of the time zone of the job. See Chapter 12, Managing time zones, on page 461 for valid names. time conforms to the following rules: v When hhmm is earlier than the current time, the start time is tomorrow; when hhmm is later than the current time, the start time is today. v When hhmm is greater than 2400, it is divided by 2400. Of the division result, the whole part represents the number of + days, while the decimal part represents the time. lowtime Specifies the lower limit of a time range, expressed in the same format as time. Jobs are selected that are scheduled to start after this time. hightime Specifies the upper limit of a time range, expressed in the same format as time. Jobs are selected that are scheduled to start before this time. If at is used alone and it is preceded by + then the jobs selected are those containing an at dependency. If at is used alone and it is preceded by ~ then the jobs selected are those not containing an at dependency. confirmed Selects or excludes jobs that were scheduled using the confirm keyword. deadline[=time | lowtime, | ,hightime | lowtime,hightime] Specifies the time within which a job must complete. hhmm[+n days | date] [timezone|tz tzname] hhmm The hour and minute.
+n days An offset in days from the scheduled deadline time. date The next occurrence of hhmm on date, expressed as mm/dd[/yy].
251

timezone|tz tzname Specifies the time zone to be used when computing the deadline. See Chapter 12, Managing time zones, on page 461 for time zone names. The default is the time zone of the workstation on which the job or job stream is launched. lowtime Specifies the lower limit of a time range, expressed in the same format as time. Selected jobs have a scheduled deadline not earlier than this time. hightime Specifies the upper limit of a time range, expressed in the same format as time. Selected jobs have a scheduled deadline not later than this time. every[=rate | lowrate, | ,highrate | lowrate,highrate] Selects or excludes jobs based on whether or not they have a repetition rate. rate Specifies the scheduled run rate, expressed as hours and minutes (hhmm).
lowrate Specifies the lower limit of a rate range, expressed in the same format as rate. Jobs are selected that have repetition rates equal to or greater than this rate. highrate Specifies the upper limit of a rate range, expressed in the same format as rate. Jobs are selected that have repetition rates less than or equal to this rate. If every is used alone and it is preceded by + then the jobs selected are those containing any repetition rate. If every is used alone and it is preceded by ~ then the jobs selected are those not containing any repetition rate. finished[=time | lowtime, | ,hightime | lowtime,hightime] Selects or excludes jobs based on whether or not they have finished. time Specifies the exact time the job finished, expressed as follows: hhmm [date] [timezone|tz tzname] hhmm date The hour and minute. The next occurrence of hhmm on date, expressed as mm/dd[/yy].
timezone|tz tzname The name of the time zone of the job. See Chapter 12, Managing time zones, on page 461 for valid names. lowtime Specifies the lower limit of a time range, expressed in the same format as time. Jobs are selected that finished at or after this time. hightime Specifies the upper limit of a time range, expressed in the same format as time. Jobs are selected that finished at or before this time. If finished is used alone and it is preceded by + then the jobs selected are the jobs that have finished running.
252

If finished is used alone and it is preceded by ~ then the jobs selected are the jobs that have not finished running. follows=[netagent::][workstation#]{jobstreamname(hhmm [mm/dd[/yy]])[.job | @] | jobstream_id.job;schedid}| job[;nocheck][,...] Selects or excludes jobs based on whether or not they have a follows dependency. netagent Specifies the name of the Tivoli Workload Scheduler network agent that interfaces with the remote Tivoli Workload Scheduler network containing the prerequisite job. Wildcard characters are permitted. For more information refer to Chapter 15, Managing internetwork dependencies, on page 499. workstation Specifies the name of the workstation on which the prerequisite job runs. Wildcard characters are permitted. jobstreamname Specifies the name of the job stream in which the prerequisite job runs. Wildcard characters are permitted. If you enter jobstreamname.@, you specify that the target job follows all jobs in the job stream. jobname Specifies the name of the prerequisite job. When entered without a jobstreamname, it means that the prerequisite job is in the same job stream as the target job. Do not specify the job name using wildcard characters for a follows dependency. jobstream_id Specifies the unique job stream identifier. See page 257 for more information on job stream identifier. schedid This keyword, if present, applies to all the job streams identifiers specified in the clause and indicates that for all the job streams specified you are using the jobstream_ids and not the jobstreamnames. If you want to select some job streams using the jobstream_id and some job streams using the jobstreamname, you must use two different follows clauses, one containing the job streams identified by the jobstreamname without the schedid keywords, and the other containing the job streams identified by the jobstream_id with the schedid keyword. nocheck Is valid only for the submission commands and used in conjunction with theschedid keyword. The nocheck keyword indicates that conman does not have to check for the existence of the prerequisite job jobstream_id.job in the Symphony file. It is assumed that jobstream_id.job exists, in case it does not exist batchman prints a warning message in the stdlist. If follows is used alone and it is preceded by + then the jobs are selected if they contain follows dependencies. If follows is used alone and it is preceded by ~ then the jobs are selected if they contain no follows dependency.
253

logon=username Select jobs based on the user names under which they run. If username contains special characters it must be enclosed in quotes (). Wildcard characters are permitted. needs[=[workstation#]resourcename] Selects or excludes jobs based on whether or not they have a resource dependency. workstation Specifies the name of the workstation on which the resource is defined. Wildcard characters are permitted. resourcename Specifies the name of the resource. Wildcard characters are permitted. If needs is used alone and it is preceded by + then the jobs are selected if they contain resource dependencies. If needs is used alone and it is preceded by ~ then the jobs are selected if they contain no resource dependency. opens[=[workstation#]filename[(qualifier)]] Select jobs based on whether or not they have a file dependency. A file dependency occurs when a job or job stream is dependent on the existence of one or more files before it can begin running. workstation Specifies the name of the workstation on which the file exists. Wildcard characters are permitted. filename Specifies the name of the file. The name must be enclosed in quotes () if it contains special characters other than the following: alphanumerics, dashes (-), slashes (/), backslashes (\), and underscores (_). Wildcard characters are permitted. qualifier A valid test condition. If omitted, jobs are selected or excluded without regard to a qualifier. If opens is used alone and it is preceded by + then the jobs are selected if they contain file dependencies. If opens is used alone and it is preceded by ~ then the jobs are selected if they contain no file dependency. priority=pri | lowpri, | ,highpri | lowpri,highpri Selects or excludes jobs based on their priorities. pri Specifies the priority value. You can enter 0 through 99, hi or go.
lowpri Specifies the lower limit of a priority range. Jobs are selected with priorities equal to or greater than this value. highpri Specifies the upper limit of a priority range. Jobs are selected with priorities less than or equal to this value. prompt[=promptname | msgnum] Selects or excludes jobs based on whether or not they have a prompt dependency.
254

promptname Specifies the name of a global prompt. Wildcard characters are permitted. msgnum Specifies the message number of a local prompt. If prompt is used alone and it is preceded by + then the jobs are selected if they contain prompt dependencies. If prompt is used alone and it is preceded by ~ then the jobs are selected if they contain no prompt dependency. recovery=recv-option Selects or excludes jobs based on their recovery options. recv-option Specifies the job recovery option as stop, continue, or rerun. scriptname=filename Selects or excludes jobs based on their executable file names. filename Specifies the name of an executable file. The name must be enclosed in quotes () if it contains special characters other than the following: alphanumerics, dashes (-), slashes (/), backslashes (\), and underscores (_). Wildcard characters are permitted. started[=time | lowtime, | ,hightime | lowtime,hightime] Selects or excludes jobs based on whether or not they have started. time Specifies the exact time the job started, expressed as follows: hhmm [date] [timezone|tz tzname] hhmm date The hour and minute. The next occurrence of hhmm on date, expressed as mm/dd[/yy].
timezone|tz tzname The name of the time zone of the job. See Chapter 12, Managing time zones, on page 461 for valid names. lowtime Specifies the lower limit of a time range, expressed in the same format as time. Jobs are selected that started at or after this time. hightime Specifies the upper limit of a time range, expressed in the same format as time. Jobs are selected that started at or before this time. If started is used alone and it is preceded by + then the jobs selected are the jobs that have started running. If started is used alone and it is preceded by ~ then the jobs selected are the jobs that have not started running. state=state[,...] Selects or excludes jobs based on their states. state Specifies the current state of the job. Valid job states are as follows: ABEND The job ended with a nonzero exit code.
255

ABENP An abend confirmation was received, but the job has not completed. ADD DONE The job completed in an unknown state. ERROR For internetwork dependencies only, an error occurred while checking for the remote status. EXEC The job is running. EXEC+ A transitory state when the job is launched by the local batchman process. EXTRN For internetwork dependencies only, the status is unknown. An error occurred, a rerun action was just performed on the job in the EXTERNAL job stream, or the remote job or job stream does not exist. FAIL FENCE The jobs priority value is below the fence. HOLD The job is awaiting dependency resolution. INTRO The job is introduced for launching by the system. INTRO+ A transitory state when the job is introduced by the local batchman process. PEND The job completed, and is awaiting confirmation. READY The job is ready to launch, and all dependencies are resolved. SCHED The jobs at time has not arrived. SUCC The job completed with an exit code of zero. SUCCP A succ confirmation was received, but the job has not completed. WAIT The job is in the WAIT state (extended agent only). until[=time | lowtime, | ,hightime | lowtime,hightime ] Selects or excludes jobs based on their scheduled end time. time Specifies the scheduled end time expressed as follows: hhmm[+n days | date] [timezone|tz tzname] hhmm The hour and minute. Unable to launch the job. The job is being submitted.
256

timezone|tz tzname The name of the time zone of the job. See Chapter 12, Managing time zones, on page 461 for valid names. lowtime Specifies the lower limit of a time range, expressed in the same format as time. Jobs are selected that have scheduled end times on or after this time. hightime Specifies the upper limit of a time range, expressed in the same format as time. Jobs are selected that have scheduled end times on or before this time. If until is used alone and it is preceded by + then the jobs are selected if they have an until time specified. If until is used alone and it is preceded by ~ then the jobs are selected if they have no until time specified.
Selecting job streams in commands

For commands that operate on job streams, the target job streams are selected by specifying attributes and qualifiers. Because scheddateandtime is specified in minutes, the combination of the jobstreamname and the scheddateandtime time might not be unique. For this reason the jobstream_id has been made available to the user, either for display purposes or to perform actions against a specific instance of a job stream. The job stream selection syntax is shown below, and described on the following pages. You can choose one of the two syntaxes described.
Syntax
[workstation#]jobstreamname(hhmm[ date]) [{+ | ~}jobstreamqualifier[...]] [workstation#]jobstream_id ;schedid
Arguments
workstation Specifies the name of the workstation on which the job stream runs. Wildcard characters are permitted. jobstreamname Specifies the name of the job stream. Wildcard characters are permitted. (hhmm [date]) Indicates the time and date the job stream instance is located in the preproduction plan. This value corresponds to the value assigned to the schedtime keyword in the job stream definition if no at time constraint was set. After the job stream instance started processing the value of hhmm [date] is set to the time the job stream started. The use of wildcards in this field is not allowed. When issuing in line conman commands from the
257

shell prompt enclose the conman command in double quotes " ". For example, run this command as follows:
conman "ss my_workstation#my_js(2101 02/23)"
jobstreamqualifier See Job Stream Qualifiers below. jobstream_id Specifies the unique alphanumerical job stream identifier automatically generated by the planner and assigned to that job stream. It is mainly used by internal processes to identify that instance of the job stream within the production plan, but it can often be used also when managing the job stream from the conman command-line program by specifying the ;schedid option. schedid Indicates that the job stream identifier is used in selecting the job stream. Note: Tivoli Workload Scheduler helps you to identify the correct job stream instance when the job stream selection provides an ambiguous result if more than one instance satisfy your selection criteria. For example when more than one instances of WK1#J1 are included in the production plan and so the job stream selection provides an ambiguous result the following prompt is automatically generated to allow you to choose the correct instance:
Process WK1#J1[(0600 03/04/06),(0AAAAAAAAAAAABTB)] (enter "y" for yes, "n" for no)?y Command forwarded to batchman for WK1#J1[(0600 03/04/06),(0AAAAAAAAAAAABTB)] Process WK1#J1[(1010 03/04/06),(0AAAAAAAAAAAABTC)] (enter "y" for yes, "n" for no)?n
In the output only the job stream instance scheduled on (0600 03/04/06) and with identifier 0AAAAAAAAAAAABTB is selected to run the command.
Job stream qualifiers

at[=time | lowtime, | ,hightime | lowtime,hightime ] Selects or excludes job streams based on the scheduled start time. time Specifies the scheduled start time expressed as follows: hhmm[+n days | date] [timezone|tz tzname] hhmm The hour and minute.
timezone|tz tzname The name of the time zone of the job stream. See Chapter 12, Managing time zones, on page 461 for valid names. lowtime Specifies the lower limit of a time range, expressed in the same format as time. Job streams are selected that have scheduled start times on or after this time.
258

hightime Specifies the upper limit of a time range, expressed in the same format as time. Job streams are selected that have scheduled start times at or before this time. If at is used alone and it is preceded by + then the job streams selected are those containing an at dependency. If at is used alone and it is preceded by ~ then the job streams selected are those not containing an at dependency. carriedforward Selects job streams that were carried forward if preceded by +, excludes job streams that were carried forward if preceded by ~. carryforward If preceded by + selects job streams that were scheduled using the carryforward keyword; if preceded by ~ excludes job streams that were scheduled using the carryforward keyword. finished[=time | lowtime, | ,hightime | lowtime,hightime] Selects or excludes job streams based on whether or not they have finished. time Specifies the exact time the job streams finished, expressed as follows: hhmm [date] [timezone|tz tzname] hhmm date The hour and minute. The next occurrence of hhmm on date, expressed as mm/dd[/yy].
timezone|tz tzname The name of the time zone of the job stream. See Chapter 12, Managing time zones, on page 461 for valid names. lowtime Specifies the lower limit of a time range, expressed in the same format as time. Job streams are selected that finished at or after this time. hightime Specifies the upper limit of a time range, expressed in the same format as time. Job streams are selected that finished at or before this time. If finished is used alone and it is preceded by + then the jobs streams selected are the jobs that have finished running. If finished is used alone and it is preceded by ~ then the jobs streams selected are the jobs that have not finished running. follows=[netagent::][workstation#]{jobstreamname(hhmm [mm/dd[/yy]])[.job | @] | jobstream_id.job;schedid}| job[;nocheck] [,...] Selects or excludes job streams based on whether or not they have a follows dependency. netagent Specifies the name of the network agent that interfaces with the remote Tivoli Workload Scheduler network containing the prerequisite job or job stream. Wildcard characters are permitted.
259

For more information about network agents, refer to Chapter 15, Managing internetwork dependencies, on page 499. workstation Specifies the name of the workstation on which the prerequisite job or job stream runs. Wildcard characters are permitted. jobstreamname Specifies the name of the prerequisite job stream. Wildcard characters are permitted. jobname Specifies the name of the prerequisite job. Wildcard characters are permitted. jobstream_id Specifies the unique job stream identifier. See page 257 for more information on job stream identifier. schedid This keyword, if present, applies to all the job streams identifiers specified in the clause and indicates that for all the job streams specified you are using the jobstream_ids and not the jobstreamnames. If you want to select some job streams using the jobstream_id and some job streams using the jobstreamname, you must use two different follows clauses, one containing the job streams identified by the jobstreamname without the schedid keywords, and the other containing the job streams identified by the jobstream_id with the schedid keyword. nocheck Is valid only for the submission commands and used in conjunction with theschedid keyword. The nocheck keyword indicates that conman does not have to check for the existence of the prerequisite job jobstream_id.job in the Symphony file. It is assumed that jobstream_id.job exists, in case it does not exist batchman prints a warning message in the stdlist. If follows is used alone and it is preceded by + then the jobs streams are selected if they contain follows dependencies. If follows is used alone and it is preceded by ~ then the jobs streams are selected if they contain no follows dependency. limit[=limit | lowlimit, | ,highlimit | lowlimit,highlimit] Selects or excludes job streams based on whether or not they have a job limit. limit lowlimit Specifies the lower limit of range. Job streams are selected that have job limits equal to or greater than this limit. highlimit Specifies the upper limit of a range. Job streams are selected that have job limits less than or equal to this limit. If limit is used alone and it is preceded by + then the jobs streams are selected if they have any job limit. If limit is used alone and it is preceded by ~ then the jobs streams are selected if they have no job limit. Specifies the exact job limit value.
260

needs[=[workstation#]resourcename] Selects or excludes job streams based on whether or not they have a resource dependency. workstation Specifies the name of the workstation on which the resource is defined. Wildcard characters are permitted. resourcename Specifies the name of the resource. Wildcard characters are permitted. If needs is used alone and it is preceded by + then the jobs streams are selected if they contain resource dependencies. If needs is used alone and it is preceded by ~ then the jobs streams are selected if they contain no resource dependency. opens[=[workstation#]filename[(qualifier)]] Selects or excludes job streams based on whether or not they have a file dependency. A file dependency occurs when a job or job stream is dependent on the existence of one or more files before it can begin running. workstation Specifies the name of the workstation on which the file exists. Wildcard characters are permitted. filename Specifies the name of the file. The name must be enclosed in quotes () if it contains special characters other than the following: alphanumerics, dashes (-), slashes (/), backslashes (\), and underscores (_). Wildcard characters are permitted. qualifier A valid test condition. If omitted, job streams are selected or excluded without regard to a qualifier. If opens is used alone and it is preceded by + then the jobs streams are selected if they contain file dependencies. If opens is used alone and it is preceded by ~ then the jobs streams are selected if they contain no file dependency. priority=pri | lowpri, | ,highpri | lowpri,highpri Selects or excludes job streams based on their priorities. pri Specifies the priority value. You can enter 0 through 99, hi or go.
lowpri Specifies the lower limit of a priority range. Job streams are selected with priorities equal to or greater than this value. highpri Specifies the upper limit of a priority range. Job streams are selected with priorities less than or equal to this value. prompt[=promptname | msgnum] Selects or excludes job streams based on whether or not they have a prompt dependency. promptname Specifies the name of a global prompt. Wildcard characters are permitted.
261

msgnum Specifies the message number of a local prompt. If prompt is used alone and it is preceded by + then the jobs streams are selected if they contain prompt dependencies. If prompt is used alone and it is preceded by ~ then the jobs streams are selected if they contain no prompt dependency. started[=time | lowtime, | ,hightime | lowtime,hightime] Selects or excludes job streams based on whether or not they have started. time Specifies the exact time the job stream started, expressed as follows: hhmm [date] [timezone|tz tzname] hhmm date The hour and minute. The next occurrence of hhmm on date, expressed as mm/dd[/yy].
timezone|tz tzname The name of the time zone of the job stream. See Chapter 12, Managing time zones, on page 461 for valid names. lowtime Specifies the lower limit of a time range, expressed in the same format as time. Job streams are selected that started at or after this time. hightime Specifies the upper limit of a time range, expressed in the same format as time. Job streams are selected that started at or before this time. If started is used alone and it is preceded by + then the jobs streams selected are the jobs that have started running. If started is used alone and it is preceded by ~ then the jobs streams selected are the jobs that have not started running. state=state[,...] Selects or excludes job streams based on their states. state Specifies the current state of the job stream. Valid job stream states are as follows: ABEND The job stream ended abnormally. ADD The job stream has just been submitted.
EXEC The job stream is running. HOLD The job stream is awaiting dependency resolution. READY The job stream is ready to launch, and all dependencies are resolved. STUCK Execution is interrupted. No jobs are launched without operator intervention.
262

SUCC The job stream completed successfully. until[=time | lowtime, | ,hightime | lowtime,hightime ] Selects or excludes job streams based on the scheduled end time. time Specifies the scheduled end time expressed as follows: hhmm[+n days | date] [timezone|tz tzname] hhmm The hour and minute.
timezone|tz tzname The name of the time zone of the job stream. See Chapter 12, Managing time zones, on page 461 for valid names. lowtime Specifies the lower limit of a time range, expressed in the same format as time. Job streams are selected that have scheduled end times on or after this time. hightime Specifies the upper limit of a time range, expressed in the same format as time. Job streams are selected that have scheduled end times on or before this time. If until is used alone and it is preceded by + then the jobs streams selected are those containing any scheduled end time. If until is used alone and it is preceded by ~ then the jobs streams selected are those not containing any scheduled end time.
Managing jobs and job streams from back-level agents

The change in the job stream instance naming convention introduced with Tivoli Workload Scheduler version 8.3 requires you to apply the following workaround when issuing command-line commands against a plan generated on a Tivoli Workload Scheduler version 8.3 (or later) master domain manager from Tivoli Workload Scheduler version 8.1, 8.2, or 8.2.1 agents: v You must use the @ symbol as the first character for the job stream instance identifier. For example the job stream running on CPU1 workstation with identifier 0AAAAAAAAAAAAY3 must be identified in the conman command line as follows:
CPU1#@AAAAAAAAAAAAY3
v You cannot use the follows keyword when adding a dependency to a job or a job stream or when submitting as a job a command or a file. v You cannot use the into keyword to specify the job stream where the job must be added when submitting as a job a command or a file. For example, to display the information about the job job2 contained in the job stream instance with identifier 0AAAAAAAAAAAAT1 running on CPU1 workstation, run the following command on Tivoli Workload Scheduler version 8.1, 8.2, or 8.2.1 agents:
sj CPU1#@AAAAAAAAAAAAT1.job2
263
Managing jobs and job streams from back-level agents

These changes will also be seen in reports and logs, and any other places where job stream names are printed or displayed.
Table 43 lists the conman commands. Note: Command names and keywords can be entered in either uppercase or lowercase characters, and can be abbreviated to as few leading characters as are needed to uniquely distinguish them from each other. Some of the command names also have short forms.
Table 43. List of conman commands Command adddep altpass altpri ap bulk Short Form adj | ads Description Adds job or job stream dependencies. Type1 F Page 267, 269 271 272 273
Alters a user object definition password. F Alters job or job stream priorities. F
| | |
bulk_discovery
Performs a bulk discovery. For use with F IBM Tivoli Monitoring 6.1 (Tivoli Enterprise Portal). Cancels a job or a job stream. Confirms job completion. Assigns the Tivoli Workload Scheduler console. Ignores the next error. F F F,S F,S F
cancel confirm console continue deldep
cj | cs
281, 276 278 279 280 302, 283 285
ddj | dds deploy
Deletes job or job stream dependencies.
| | |
deployconf
Gets the latest monitoring configuration F,S for the event monitoring engine on the workstation. Displays files, jobs, and job streams. Exits conman. Sets Tivoli Workload Scheduler job fence. Displays command information. Stops an executing job. F,S2 F,S F F,S F
display exit fence help4 kill limit link listsym recall redo release reply rerun resource setsym
df | dj | ds
286 289 290 291 292 293, 294 295 297 299 300 274, 304 306 307 310 311 312
lc | ls lk
Changes a workstation or job stream job F limit. Opens workstation links. Displays a list of Symphony log files. F,S F F F,S
rc
Displays prompt messages. Edits the previous command.
rj | rs
Releases job or job stream dependencies. F Replies to prompt message. F F F F F,S
rr
Reruns a job. Changes the number of resource units. Selects a Symphony log file.
| |
showcpus
sc
Displays workstation and link information.
264
Table 43. List of conman commands (continued) Command showdomain showfiles showjobs showprompts showresources showschedules shutdown start sf sj sp sr ss shut Short Form Description Displays domain information. Displays information about files. Displays information about jobs. Displays information about prompts. Displays information about resources. Displays information about job streams. Stops Tivoli Workload Scheduler production processes. Starts Tivoli Workload Scheduler production processes. Starts the embedded WebSphere Application Server process startevtp startm Starts the event processing server. Starts the monman process that turns on the event monitoring engine on the agent. Displays Tivoli Workload Scheduler production status. Stops Tivoli Workload Scheduler production processes. Stops Tivoli Workload Scheduler production processes hierarchically. Stops the embedded WebSphere Application Server process stopevtp stopm sbd | sbf | sbj | sbs switchevtp Stops the event processing server. Stops the event monitoring engine on the agent. Submits a command, file, job, or job stream. F,S M5 F,S F,S3 Type1 F,S F F F F F F,S F,S F,S M5 F,S Page 317 319 321 332 335 337 341 342 startappserver on page 345 346 347
| | | | | |
startappserver starteventprocessor startmon
status stop stop ;progressive
F,S F,S
348 349 351 stopappserver on page 352 353 354 355, 358, 361, 363 366
| | | | |
stopappserver stopeventprocessor stopmon submit
| | |
switcheventprocessor
Switches the event processing server from master domain managers to backup masters or vice versa. Switches the domain manager. Sends a command to the system.
switchmgr sys-command tellop unlink version v to
F F,S F,S F,S F,S
367 368 369 370 372
Sends a message to the console. Closes workstation links. Displays conmans command line program banner.
| |
1. Workstation types: master domain managers and backup masters (M), domain managers and fault-tolerant agents (F), standard agents (S). 2. You can only display files on a standard agent.
265
3. You can use submit job (sbj) and submit sched (sbs) on a standard agent by using the connection parameters or specifying the settings in the useropts file when invoking the conman command line. 4. Not available on supported Windows operating system. 5. Includes workstations installed as backup masters but used as ordinary fault-tolerant agents. Note: In the commands, the terms sched and schedule refer to job streams, and the term CPU refers to workstation.
| |
266
adddep job
adddep job
Adds dependencies to a job. You must have adddep access to the job. To include needs and prompt dependencies, you must have use access to the resources and global prompts.
Syntax
adj jobselect [;dependency[;...]] [;noask]
Arguments
jobselect See Selecting jobs in commands on page 249. dependency The type of dependency. Specify one of the following. Wildcard characters are not permitted. at=hhmm[timezone | tz tzname][+n days | mm/dd[/yy]] | [absolute | abs] confirmed deadline=time [timezone|tz tzname][+n day[s | mm/dd[/yy]] every=rate follows=[netagent::][workstation#]{jobstreamname[hhmm [mm/dd[/yy]]][.job | @] | jobstream_id.job;schedid}| job[,...] needs=[num] [workstation#]resource[,...] opens=[workstation#]filename[(qualifier)][,...] priority[=pri | hi | go] prompt=[: | !]text | promptname[,...] until time [timezone|tz tzname][+n day[s]] | [absolute | abs] [;onuntil action] noask Specifies not to prompt for confirmation before taking action on each qualifying job. Notes: 1. If you add twice a dependency on a job stream to a job, both dependencies are considered.. 2. When using the deadline keyword, ensure the bm check deadline variable is set to a value higher than 0 in the localopts configuration file on the target workstations for the job or job stream. For information, refer to IBM Tivoli Workload Scheduler Planning and Installation Guide.
Comments
If you do not specify a value for priority, the job reverts to its original scheduled priority. If you do not specify a workstation in follows, needs, or opens, the default is the workstation on which the job runs. You cannot use this command to add a resource or a prompt as dependencies unless they are already referenced by a job or a job stream in the Symphony file.
Examples
To add a resource dependency to job job3 in job stream sked9(0900 02/19/06), run the following command:
267
adddep job
adj sked9(0900 02/19/06).job3 ; needs=2 tapes
To add an external follows dependency from to job JOB022 in job stream MLN#SCHED_02(0600 02/24) to JOBA in job stream MLN#NEW_TEST(0900 02/19/06), run the following command:
adj MLN#NEW_TEST(0900 02/19/06).JOBA ; follows MLN#SCHED_02(0600 02/24/06).JOB022
To add a file dependency, and an until time to job j6 in job stream JS2(0900 02/19/06), run the following command:
adj WK1#JS2(0900 02/19/06).j6 ; opens="/usr/lib/prdata/file5"(-s %p) ; until=2330
See also
For the equivalent Job Scheduling Console task, see Creating Dependencies between Jobs and Adding External Dependencies to a Job Stream in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
268
adddep sched
adddep sched
Adds dependencies to a job stream. You must have adddep access to the job stream. To include needs and prompt dependencies, you must have use access to the resources and global prompts.
Syntax
ads jstreamselect [;dependency[;...]] [;noask]
Arguments
jstreamselect See Selecting job streams in commands on page 257. dependency The type of dependency. Specify one of the following. Wildcard characters are not permitted. at=hhmm[timezone | tz tzname][+n days | mm/dd[/yy]] | [absolute | abs] carryforward deadline=time [timezone|tz tzname][+n day[s | mm/dd[/yy]] follows=[netagent::][workstation#]{jobstreamname[hhmm [mm/dd[/yy]]][.job | @] | jobstream_id.job;schedid}| job[,...] limit=limit needs=[num] [workstation#]resource[,...] opens=[workstation#]filename[(qualifier)][,...] priority[=pri | hi | go] prompt=[: | !]text | promptname[,...] until time [timezone|tz tzname][+n day[s] | [absolute | abs]] [;onuntil action] noask Specifies not to prompt for confirmation before taking action on each qualifying job stream. Notes: 1. If you add twice a dependency on a job stream to another job stream, only one dependency is considered. 2. When using the deadline keyword, ensure the bm check deadline variable is set to a value higher than 0 in the localopts configuration file on the target workstations for the job or job stream. For information, refer to IBM Tivoli Workload Scheduler Planning and Installation Guide.
Comments
v If you do not specify a value for priority, the job stream reverts to its original scheduled priority. v If you do not specify a value for limit, the value defaults to 0. v If you do not specify a workstation in follows, needs, or opens, the default is the workstation on which the job stream runs. v You cannot use this command to add a resource or a prompt as dependencies unless they already exists in the production plan. To see which resource and prompts exist in the plan refer to showresources on page 335 and showprompts on page 332.
269
adddep sched
Examples
To add a prompt dependency to job stream sked9(0900 02/19/06), run the following command:
ads sked9(0900 02/19/06) ; prompt=msg103
To add an external follows dependency from to job JOBB in job stream CPUA#SCHED_02(0600 02/24/06) and a job limit to job stream CPUA#TEST(0900 02/19/06), run the following command:
ads CPUA#TEST(0900 02/19/06) ; follows CPUA#SCHED_02(0600 02/24/06).JOBB; limit=2
See also
For the equivalent Job Scheduling Console task, see Creating Dependencies within a Job Stream and Creating Dependencies between Job Streams in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
270
altpass
altpass
Alters the password of a user object in the current production plan. You must have altpass access to the user object.
Syntax
altpass [workstation#] username [;password]
Arguments
workstation Specifies the workstation on which the user is defined. Use the upper case for this field even though you used the mixed case when specifying the workstation in the Windows user definition. For more information refer to Windows user definition on page 125. Do not specify this field if the user belongs to a active directory managed Windows domain. The default is the workstation on which you are running conman. Specifies the name of a user. Use the upper case for this field even though you used the mixed case when specifying the [domain\]username in the Windows user definition. For more information. refer to Windows user definition on page 125. Specifies the new password. It must be enclosed in double quotes. To indicate no password for the user, use two consecutive double quotes ().
username
password
Comments
If you do not specify a password, conman prompts for a password and a confirmation. The password is not displayed as it is entered and should not be enclosed in quotes. Note that the change is made only in the current production plan, and is therefore temporary. To make a permanent change see Windows user definition on page 125.
Examples
To change the password of user Jim on workstation mis5 to mynewpw, run the following command:
altpass MIS5#JIM;mynewpw
To change the password of user jim on workstation Mis5 to mynewpw without displaying the password, run the following command:
altpass MIS5#JIM password: xxxxxxxx confirm: xxxxxxxx
To change the password of user Jim, defined in an active directory managed Windows domain named twsDom, to mynewpw, run the following command:
altpass TWSDOM\JIM;mynewpw
See also
For the equivalent Job Scheduling Console task, see Changing Windows User Passwords in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
271
altpri
altpri
Alters the priority of a job or job stream. You must have altpri access to the job or job stream.
Syntax
ap jobselect | jstreamselect [;pri] [;noask]
Arguments
jobselect jstreamselect pri noask See Selecting jobs in commands on page 249. See Selecting job streams in commands on page 257. Specifies the priority level. You can enter a value of 0 through 99, hi, or go. Specifies not to prompt for confirmation before taking action on each qualifying job or job stream.
Examples
To change the priority of the balance job in job stream glmonth(0900 02/19/06), run the following command:
ap glmonth(0900 02/19/06).balance;55
To change the priority of job stream glmonth(0900 02/19/06), run the following command:
ap glmonth(0900 02/19/06);10
272
bulk_discovery
bulk_discovery
| | | Requests a bulk discovery to update the current status of monitored objects. It is used for the integration with IBM Tivoli Monitoring 6.1 (Tivoli Enterprise Portal). You must have display access to the file object.
Syntax
bulk
Comments
When the integration with IBM Tivoli Monitoring 6.1 is enabled, the bulk_discovery command checks the status of all monitored jobs and job streams within the plan and writes the corresponding events in the event log file. By default, events are written in the event.log file. Messages indicating the start and end of the bulk discovery activity are logged in the twsmerge.logfile.
273
cancel job
cancel job
Cancels a job. You must have cancel access to the job.
Syntax
cj jobselect [;pend] [;noask]
Arguments
jobselect pend noask See Selecting jobs in commands on page 249. Cancels the job only after its dependencies are resolved. Specifies not to prompt for confirmation before taking action on each qualifying job.
Comments
If you cancel a job before it is launched, it does not launch. If you cancel a job after it is launched, it continues to run. If you cancel a job that is running and it completes in the ABEND state, no automatic job recovery steps are attempted. If you do not use the ;pend option, jobs and job streams that are dependent on the cancelled job are released immediately from the dependency. If you include the ;pend option, and the job has not been launched, cancellation is deferred until all of the dependencies, including an at time, are resolved. Once all the dependencies are resolved, the job is cancelled and any jobs or job streams that are dependent on the cancelled job are released from the dependency. During the period the cancel is deferred, the notation [Cancel Pend] is listed in the Dependencies column of the job in a showjobs display. If you include the ;pend option and the job has already been launched, the option is ignored, and any jobs or job streams that are dependent on the cancelled job are immediately released from the dependency. You can use the rerun command to rerun jobs that have been cancelled, or that are marked [Cancel Pend]. You can also add and delete dependencies on jobs that are marked [Cancel Pend]. To immediately cancel a job that is marked [Cancel Pend], you can either enter a release command for the job or enter another cancel command without the ;pend option. For jobs with expired until times, the notation [Until] is listed in the Dependencies column in a showjobs display, and their dependencies are no longer evaluated. If such a job is also marked [Cancel Pend], it is not cancelled until you release or delete the until time, or enter another cancel command without the ;pend option. To stop evaluating dependencies, set the priority of a job to zero with the altpri command. To resume dependency evaluation, set the priority to a value greater than zero. Note: In the case of internetwork dependencies, cancelling a job in the EXTERNAL job stream releases all local jobs and job streams from the dependency. Jobs
274
cancel job
in the EXTERNAL job stream represent jobs and job streams that have been specified as internetwork dependencies. The status of an internetwork dependency is not checked after a cancel is performed. For more information see Managing internetwork dependencies on page 504.
Examples
To cancel job report in job stream apwkly(0900 02/19/06) on workstation site3, run the following command:
cj site3#apwkly(0900 02/19/06).report
To cancel job setup in job stream mis5(1100 02/10/06), if it is not in the ABEND state, run the following command:
cj mis5(1100 02/10/06).setup~state=abend
To cancel job job3 in job stream sked3(0900 02/19/03) only after its dependencies are resolved, run the following command:
cj sked3(0900 02/19/06).job3;pend
See also
For the equivalent Job Scheduling Console task, see Deleting a Job from a Job Stream in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
275
cancel sched
cancel sched
Cancels a job stream. You must have cancel access to the job stream.
Syntax
cs jstreamselect [;pend] [;noask]
Arguments
jstreamselect pend noask See Selecting job streams in commands on page 257. Cancels the job stream only after its dependencies are resolved. Specifies not to prompt for confirmation before taking action on each qualifying job stream.
Comments
If you cancel a job stream before it is launched, it does not launch. If you cancel a job stream after it is launched, the jobs that have started complete, but no other jobs are launched. If you do not use the ;pend option, jobs and job streams that are dependent on the cancelled job stream are released immediately from the dependency. If you use the ;pend option and the job stream has not been launched, cancellation is deferred until all of its dependencies, including an at time, are resolved. Once all dependencies are resolved, the job stream is cancelled and any dependent jobs or job streams are released from the dependency. During the period the cancel is deferred, the notation [Cancel Pend] is listed in the Dependencies column of a showschedules display. If you include the ;pend option and the job stream has already been launched, any remaining jobs in the job stream are cancelled, and any dependent jobs and job streams are released from the dependency. To immediately cancel a job stream marked [Cancel Pend], either enter a release command for the job stream or enter another cancel command without the ;pend option. For job streams with expired until times, the notation [Until] appears in the Dependencies column of the showschedules display and their dependencies are no longer evaluated. If such a job stream is also marked [Cancel Pend], it is not cancelled until you release or delete the until time or enter another cancel command without the ;pend option. To stop evaluating dependencies, set the job streams priority to zero with the altpri command. To resume dependency evaluation, set the priority to a value greater than zero.
Examples
To cancel job stream sked1(1200 02/17/06) on workstation site2, run the following command:
cs site2#sked1(1200 02/17)
276
cancel sched
To cancel job stream mis2(0900 02/19/06) if it is in the STUCK state, run the following command:
cs mis2(0900 02/19)+state=stuck
See also
For the equivalent Job Scheduling Console task, see Deleting Job Streams in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
277
confirm
confirm
Confirms the completion of a job that was scheduled with the confirmed keyword. You must have confirm access to the job.
Syntax
confirm jobselect ;{succ | abend} [;noask]
Arguments
jobselect succ abend noask See Selecting jobs in commands on page 249. Confirms that the job ended successfully. Confirms that the job ended unsuccessfully. Specifies not to prompt for confirmation before taking action on each qualifying job.
Comments
Changing the state of a job from ABEND to SUCC does not require that the confirmed keyword be used to schedule the job. For more information about job confirmation, see confirmed on page 141. For more information about EXTERNAL jobs, see Managing internetwork dependencies on page 504. Table 44 shows the effect of the confirm command on the various states of jobs:
Table 44. State change after confirm command Initial Job State READY HOLD EXEC ABENP SUCCP PEND DONE SUCC ABEND FAIL SCHED any job in the EXTERNAL job stream State after confirm ;succ no effect no effect SUCCP SUCCP no effect SUCC SUCC no effect SUCC no effect no effect SUCC State after confirm ;abend no effect no effect ABENP no effect no effect ABEND ABEND no effect no effect no effect no effect ABEND
Examples
To issue a succ confirmation for job job3 in job stream misdly(1200 02/17/06), run the following command:
confirm misdly(1200 02/17/06).job3;succ
To issue an abend confirmation for job number 234, run the following command:
confirm 234;abend
278
console
console
Assigns the Tivoli Workload Scheduler console and sets the message level. You must have console access to the workstation.
Syntax
console [sess | sys] [;level=msglevel]
Arguments
sess sys Sends Tivoli Workload Scheduler console messages and prompts to standard output. Stops sending Tivoli Workload Scheduler console messages and prompts to standard output. This occurs automatically when you exit conman. The level of Tivoli Workload Scheduler messages that are sent to the console. Specify one of the following levels: 0 1 2 3 4 No messages. This is the default on fault-tolerant agents. Exception messages such as operator prompts and job abends. Level 1, plus job stream successful messages. Level 2, plus job successful messages. This is the default on the master domain manager. Level 3, plus job launched messages.
msglevel
Comments
If you enter a console command with no options, the current state of the console is displayed. By default, Tivoli Workload Scheduler control processes write console messages and prompts to standard list files. In UNIX, you can also have them sent to the syslog daemon.
Examples
To begin writing console messages and prompts to standard output and change the message level to 1, run the following command:
console sess;level=1
To stop writing console messages and prompts to standard output and change the message level to 4, run the following command:
cons sys;l=4
To display the current state of the console, run the following command:
cons Console is #J675, level 2, session
675 is the process ID of the users shell.
279
continue
continue
Ignores the next command error.
Syntax
continue
Comments
This command is useful when commands are entered non-interactively. It instructs conman to continue running commands even if the next command, following continue, results in an error.
Examples
To have conman continue with the rerun command even if the cancel command fails, run the following command:
conman "continue&cancel=176&rerun job=sked5(1200 02/17/06).job3"
280
deldep job
deldep job
Deletes dependencies from a job. You must have deldep access to the job.
Syntax
ddj jobselect ;dependency[;...] [;noask]
Arguments
jobselect See Selecting jobs in commands on page 249. dependency The type of dependency. Specify at least one of the following. You can use wildcard characters in workstation, jstream, job, resource, filename, and promptname. at[=time | lowtime | hightime | lowtime,hightime] confirmed deadline[=time[timezone | tz tzname][+n days | mm/dd[/yy]]] every follows=[netagent::][workstation#]{jobstreamname(hhmm [mm/dd[/yy]]) [.job | @] | jobstream_id.job;schedid}| job[,...] needs[=[num] [workstation#]resource[,...]] opens[=[workstation#]filename[(qualifier)][,...]] priority prompt[=[: | !]text | promptname[,...]] until[=time [timezone|tz tzname][+n day[s]] [;onuntil action]] noask Specifies not to prompt for confirmation before taking action on each qualifying job.
Comments
If you delete priority, the job reverts to its original scheduled priority. When you delete an opens dependency, you can include only the base file name and conman performs a case-insensitive search for matching files, ignoring the directory names. Dependencies on all matching files are deleted. Deleted dependencies no longer remain in effect when running the rerun command.
Examples
To delete a resource dependency from job job3 in job stream sked9(0900 02/19/06), run the following command:
ddj sked9(0900 02/19/06).job3 ; needs=2 tapes
To delete all external follows dependency from job stream CPUA#TEST(0900 02/19/06), run the following command:
ddj CPUA#TEST(0900 02/19/06).JOBA ; follows
281
deldep job
See also
For the equivalent Job Scheduling Console task, see Managing Jobs in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
282
deldep sched
deldep sched
Deletes dependencies from a job stream. You must have deldep access to the job stream.
Syntax
dds jstreamselect ;dependency[;...] [;noask]
Arguments
jstreamselect See Selecting jobs in commands on page 249. dependency The type of dependency. Specify at least one of the following. You can use wildcard characters in workstation, jstreamname, jobname, resource, filename, and promptname. at[=time | lowtime | hightime | lowtime,hightime] carryforward deadline[=time[timezone | tz tzname][+n days | mm/dd[/yy]]] follows=[netagent::][workstation#]{jobstreamname[hhmm [mm/dd[/yy]]][.job | @] | jobstream_id.job;schedid}| job[,...] limit needs[=[num] [workstation#]resource[,...]] opens[=[workstation#]filename[(qualifier)][,...]] priority prompt[=[: | !]text | promptname[,...]] until[=time [timezone|tz tzname][+n day[s]] [;onuntil action]] noask Specifies not to prompt for confirmation before taking action on each qualifying job stream.
Comments
If you delete priority , the job reverts to its original scheduled priority. When you delete an opens dependency, you can include only the base file name, and conman performs a case-insensitive search for matching files, ignoring the directory names. Dependencies on all matching files are deleted. Deleted dependencies no longer remain in effect when running the rerun command.
Examples
To delete a resource dependency from job stream sked5(0900 02/19/06), run the following command:
dds sked5(0900 02/19/06);needs=2 tapes
To delete all follows dependencies from job stream sked3(1000 04/19/06), run the following command:
dds sked3(1000 04/19/06);follows
283
deldep sched
See also
For the equivalent Job Scheduling Console task, see Managing Job Streams in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
284
deployconf
| | | | | | | | | | | | | | | | | | | | | | | | workstation
deployconf
Gets the latest monitoring configuration for the event monitoring engine on the workstation.
Syntax
deployconf [domain!]workstation
Arguments
domain Specifies the name of the destination domain for the operation. Wildcard characters are permitted. This argument is useful when deploying to more than one workstation in a domain. For example, to deploy the latest monitoring configuration to all the agents in the AURORABU domain , use the following command:
deploy AURORABU!@
The domain is not needed if you do not include wildcard characters in workstation. If you do not include domain, and you include wildcard characters in workstation, the default domain is the one in which conman is running. Specifies the name of the workstation where the monitoring engine runs. Wildcard characters are not permitted.
Comments
If the existing configuration is already up-to-date, the command has no effect. Permission to start actions on cpu objects is required in the security file to be enabled to run this command.
285
display
display
Displays a job file or a job stream definition. If you specify a file by name, you must have read access to the file. For job files and job stream definitions, you must have display access to the job or job stream.
Syntax
df filename [;offline] dj jobselect [;offline] ds jstreamselect [valid {at date | in date date} [;offline]
Arguments
filename Specifies the name of the file, usually a job script file. The name must be enclosed in quotes () if it contains characters other than the following: alphanumeric characters, dashes (-), slashes (/), backslashes (\), and underscores (_). Wildcard characters are permitted. The file must be accessible from your login workstation. Use this option is you want to show only the content of the job script file. The job whose job file is displayed. See Selecting jobs in commands on page 249. The job file must be accessible from your login workstation. This keyword applies only to path and filename of the script file of jobs defined with the scriptname option. The job stream whose definition is displayed. See Selecting job streams in commands on page 257. Specifies the day or the interval of days during which the job stream instances to be displayed must be active. This means that the validity interval of those job stream instances must contain the time frame specified in valid argument. The format used for date depends on the value assigned to the date format variable specified in the localopts file. If not specified the selected instance is the one valid today. Sends the output of the command to the conman output device. For information about this device, see Offline output on page 244.
jobselect
jstreamselect valid
offline
Examples
To display the file c:\maestro\jclfiles\arjob3, run the following command:
df c:\apps\maestro\jclfiles\arjob3
To display the script file for job createpostreports in job stream final offline, run the following command:
dj FINAL(0559 03/06/06).CREATEPOSTREPORTS
This is a sample output of this command:

M235062_99#FINAL(0559 03/06/06).CREATEPOSTREPORTS /home/tws83/CreatePostReports #!/bin/sh #################################################################### # Licensed Materials - Property of IBM # ?Restricted Materials of IBM?
286
display
# 5698-WSH # (C) Copyright IBM Corp. 1998, 2006 All Rights Reserved. # US Government Users Restricted Rights - Use, duplication or # disclosure restricted by GSA ADP Schedule Contract with IBM Corp. ################################################################### #@(#) $Id: CreatePostReports.sh,v 1.0 ## ## CreatePostReports message catalog definitions. ## ## ## message set id ## MAE_CREATEPOSTREPORTS_SET=226 MAE_COPYRIGHT_SET=234 ## .... ... .... # # End #
To display the job stream definition for job stream mod, run the following command:
ds mod
This is a sample output of this command:

Job Stream Name Workstation Valid From Updated On Locked By ---------------- ---------------- ---------- ---------- ---------------MOD M235062_99 06/30/2007 03/04/2006 SCHEDULE M235062_99#MOD VALIDFROM 06/30/2007 ON RUNCYCLE SCHED1_PREDSIMPLE VALIDFROM 07/18/2007 "FREQ=DAILY;INTERVAL=1" ( AT 1111 ) CARRYFORWARD FOLLOWS M235062_99#SCHED_FIRST1.@ FOLLOWS M235062_99#SCHED_FIRST.JOB_FTA PRIORITY 66 : M235062_99#JOBMDM SCRIPTNAME "/usr/acct/scripts/gl1" STREAMLOGON root DESCRIPTION "general ledger job1" TASKTYPE UNIX RECOVERY STOP PRIORITY 30 NEEDS 16 M235062_99#JOBSLOTS PROMPT PRMT3 B236153_00#JOB_FTA FOLLOWS M235062_99#SCHED_FIRST1.@ FOLLOWS M235062_99#SCHED_FIRST.JOB_FTA PRIORITY 66 : M235062_99#JOBMDM SCRIPTNAME "/usr/acct/scripts/gl1" STREAMLOGON root DESCRIPTION "general ledger job1" TASKTYPE UNIX RECOVERY STOP PRIORITY 30 NEEDS 16 M235062_99#JOBSLOTS PROMPT PRMT3
287
display
B236153_00#JOB_FTA DOCOMMAND "echo pippo" STREAMLOGON root DESCRIPTION "general ledger job1" TASKTYPE UNIX RECOVERY STOP FOLLOWS JOBMDM END
See also
For the equivalent Job Scheduling Console task, see Managing Jobs and Managing Job Streams in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
288
exit
exit
Exits the conman command line program.
Syntax
e
Comments
When you are in help mode in UNIX, this command returns conman to command-input mode.
Examples
To exit the conman command-line program, run the following command:
exit
or
e
289
fence
fence
Changes the job fence on a workstation. Jobs are not launched on the workstation if their priorities are less than or equal to the job fence. You must have fence access to the workstation.
Syntax
fence workstation ;pri [;noask]
Arguments
workstation pri noask Specifies the workstation name. The default is your login workstation. Specifies the priority level. You can enter 0 through 99, hi, go, or system. Entering system sets the job fence to zero. Specifies not to prompt for confirmation before taking action on each qualifying workstation.
Comments
The job fence prevents low priority jobs from being launched, regardless of the priorities of their job streams. It is possible, therefore, to hold back low priority jobs in high priority job streams, while allowing high priority jobs in low priority job streams to be launched. When you first start Tivoli Workload Scheduler following installation, the job fence is set to zero. When you change the job fence, it is carried forward during pre-production processing to the next days production plan. To display the current setting of the job fence, use the status command.
Examples
To change the job fence on workstation site4, run the following command:
fence site4;20
To change the job fence on the workstation on which you are running conman, run the following command:
f ;40
To prevent all jobs from being launched by the Tivoli Workload Scheduler on workstation tx3, run the following command:
f tx3;go
To change the job fence to zero on the workstation on which you are running conman, run the following command:
f ;system
See also
For the equivalent Job Scheduling Console task, see Viewing and Modifying Workstation Properties in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
290
help
help
Displays help information about commands. Not available in Windows.
Syntax
help command
Arguments
command Specifies the name of a conman or system command. For conman commands, enter the full command name; abbreviations and short forms are not supported. For commands consisting of two words, enter the first word, and help for all versions of the command is displayed. For example, entering help display displays information about the display file, display job, and display sched commands. You can also enter the following keywords: commands Lists all conman commands. jobselect Lists information about selecting jobs for commands. jobstates Lists information about job states. schedselect Lists information about selecting job streams for commands. schedstates Lists information about job stream states.
Examples
To display a list of all conman commands, run the following command:
help commands
To display information about the fence command, run the following command:
help fence
To display information about the altpri job and altpri sched commands, run the following command:
h altpri
291
kill
kill
Stops a job that is running. In UNIX, this is accomplished with a UNIX kill command. You must have kill access to the job.
Syntax
kill jobselect [;noask]
Arguments
jobselect noask See Selecting jobs in commands on page 249. Specifies not to prompt for confirmation before taking action on each qualifying job.
Comments
The kill operation is not performed by conman; it is run by a Tivoli Workload Scheduler production process, so there might be a short delay. Killed jobs end in the ABEND state. Any jobs or job streams that are dependent on a killed job are not released. Killed jobs can be rerun.
Examples
To kill the job report in job stream apwkly(0600 03/05/06) on workstation site3, run the following command:
kill site3#apwkly(0600 03/05/06).report
To kill job number 456, run the following command:

k 456
292
limit cpu
limit cpu
Changes the limit of jobs that can run simultaneously on a workstation. You must have limit access to the workstation.
Syntax
lc workstation ;limit [;noask]
Arguments
workstation limit Specifies the name of the workstation. Wildcard characters are permitted. The default is your login workstation. Specifies the job limit. You can enter 0 through 1024. Entering system sets the job limit to zero. Note: If you set lc to zero, no jobs, other than hi and go priority jobs contained in a job stream in READY state, are launched on the workstation. noask Specifies not to prompt for confirmation before taking action on each qualifying workstation.
Comments
To display the current job limit on your login workstation, use the status command. When you first start Tivoli Workload Scheduler following installation, the workstation job limit is set to zero, and must be increased before any jobs are launched. When you change the limit, it is carried forward during pre-production processing to the next days production plan. Tivoli Workload Scheduler attempts to launch as many jobs as possible within the job limit. There is a practical limit to the number of processes that can be started on a workstation. If this limit is reached, the system responds with a message indicating that system resources are not available. When a job cannot be launched for this reason, it enters the fail state. Lowering the job limit can prevent this from occurring.
Examples
To change the job limit on the workstation on which you are running conman, run the following command:
lc ;12
To change the job limit on workstation rx12, run the following command:
lc rx12;6
To set to 10 the job limit on all the workstations belonging to the domain and to child domains, run the following command:
lc @!@;10
See also
For the equivalent Job Scheduling Console task, see Viewing and Modifying Workstation Properties in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
293
limit sched
limit sched
Changes the limit set in the definition of a job stream. For additional information on setting a limit in a job stream definition, refer to limit on page 158. You must have limit access to the job stream.
Syntax
ls jstreamselect ;limit [;noask]
Arguments
jstreamselect limit See Selecting job streams in commands on page 257. Specifies the job limit. You can enter 0 through 1024. Note: If you specify a limit of 0, no further jobs, even those with priority set to GO, are launched from the job stream. noask Specifies not to prompt for confirmation before taking action on each qualifying job stream.
Examples
To change the job limit on all job streams that include sales in their name, run the following command:
ls sales@;4
To change the job limit on job stream CPUA#Job1, run the following command:
ls CPUA#apwkly;6
See also
For the equivalent Job Scheduling Console task, see Managing Job Streams in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
294
link
link
Opens communication links between workstations. In a Tivoli Workload Scheduler network, fault-tolerant and standard agents are linked to their domain managers, and domain managers are linked to their parent domain managers. Extended agents are not linked; they communicate through a host. You must have link access to the target workstation.
Syntax
lk [domain!]workstation [;noask]
Arguments
domain Specifies the name of the domain in which links are opened. Wildcard characters are permitted. This argument is useful when linking more than one workstation in a domain. For example, to link all the agents in domain stlouis, use the following command:
lk stlouis!@
The domain is not needed if you do not include wildcard characters in workstation. If you do not include domain, and you include wildcard characters in workstation, the default domain is the one in which conman is running. workstation noask Specifies the name of the workstation to be linked. Wildcard characters are permitted. Specifies not to prompt for confirmation before taking action on each qualifying workstation.
Comments
If the autolink option is set to on in a workstation definition, its link is opened automatically each time Tivoli Workload Scheduler is started. If autolink is set to off, you must use link and unlink commands to control linking. For information about autolink see Workstation definition on page 108. Assuming that a user has link access to the workstations being linked, the following rules apply: v A user running conman on the master domain manager can link any workstation in the network. v A user running conman on a domain manager other than the master can link any workstation in its own domain and subordinate domains. The user cannot link workstations in peer domains. v A user running conman on an agent can link any workstation in its local domain provided that the workstation is a domain manager or host. A peer agent in the local domain cannot be linked. v To link a subordinate domain while running conman in a higher domain, it is not necessary that the intervening links be open.
Examples
Figure 10 on page 296 and Table 45 on page 296 show the links opened by link commands run by users in various locations in the network.
295
link
A11 DM1
A12
Domain1 User1
User3 DM2 A21 A22 Domain2 User2 A31 DM3 A32 Domain3
DM4 Domain4 A41 A42
Figure 10. Network links
DMn are domain managers and Ann are agents.

Table 45. Opened links Command link @!@ Links Opened by User1 All links are opened. Links Opened by User2 DM1-DM2 DM2-A21 DM2-A22 DM2-DM4 DM4-A41 DM4-A42 DM1-DM2 DM2-A21 DM2-A22 DM2-DM4 Not allowed. DM4-A41 DM4-A42 Not applicable. DM4-A42 Not allowed. Links Opened by User3 DM2-A21
link @
DM1-A11 DM1-A12 DM1-DM2 DM1-DM3 DM3-A31 DM3-A32 DM4-A41 DM4-A42 DM1-DM2 DM4-A42 DM3-A31
DM2-A21
link DOMAIN3!@ link DOMAIN4!@ link DM2 link A42 link A31
Not allowed. Not allowed. DM2-A21 Not allowed. Not allowed.
296
listsym
listsym
Lists the production plan (Symphony files) already processed.
Syntax
listsym [trial | forecast] [;offline]
Arguments
trial forecast offline Lists trial plans. Lists forecast plans. Sends the output of the command to the conman output device. For information about this device, see Offline output on page 244.
Results
Schedule Date The date used to select the job streams to run. Actual Date The date batchman began running the Symphony file. Start Time The time batchman began running the Symphony file. Log Date The date the plan (Symphony file) was logged by the stageman command. Run Num The run number assigned to the plan (Symphony file). This is used internally for Tivoli Workload Scheduler network synchronization. Size The number of records contained in the Symphony file.
Log Num The log number indicating the chronological order of log files. This number can be used in a setsym command to switch to a specific log file. Filename The name of the log file assigned by the stageman command.
Examples
To list the production plan files, run the following command:
listsym
this is a sample output for the command:

Job Stream Date 03/05/06 03/04/06 03/04/06 03/04/06 03/04/06 03/04/06 03/04/06 03/04/06 03/04/06 Actual Date 03/05/06 03/04/06 03/04/06 03/04/06 03/04/06 03/04/06 03/04/06 03/04/06 03/04/06 Start Time 21:06 15:59 15:51 14:31 14:26 14:24 14:19 14:17 14:17 Log Date 03/05/06 03/05/06 03/04/06 03/04/06 03/04/06 03/04/06 03/04/06 03/04/06 03/04/06 Run Num 42 41 40 39 38 37 36 35 34 Size 534 463 362 460 436 436 436 436 364 Log Num 1 2 3 4 5 6 7 8 9 Filename M200603052111 M200603052106 M200603041559 M200603041551 M200603041431 M200603041426 M200603041424 M200603041419 M200603041417
Exp Exp Exp Exp Exp Exp Exp Exp Exp
To list files containing trial plans, run the following command:

listsym trial
297
listsym
this is a sample output for the command:
Job Stream Date 03/03/06 03/03/06 03/03/06 Actual Start Date Time Log Date 03/03/06 03/03/06 03/03/06 Run Num 0 0 0 Size 126 1850 1838 Log Num Filename 1 Tpippo 2 Tangelo2 3 Tangelo1
Exp Exp Exp
To list the files containing the forecast plans, run the following command:
listsym forecast
This is a sample output for the command:

Job Stream Date 03/03/06 Actual Start Date Time Log Date 03/03/06 Run Num 0 Size 62 Log Num Filename 1 Fpluto
Exp
298
recall
recall
Displays prompts that are waiting for a response. You must have display access to the prompts.
Syntax
rc [workstation] [;offline]
Arguments
workstation Specifies the name of the workstation on which the prompt was issued. If you do not specify a workstation, only prompts for the login workstation and global prompts are displayed. Sends the output of the command to the conman output device. For information about this device, see Offline output on page 244.
offline
Results
State The state of the prompt. The state of pending prompts is always ASKED. Message or Prompt For named prompts, the message number, the name of the prompt, and the message text. For unnamed prompts, the message number, the name of the job or job stream, and the message text.
Examples
To display pending prompts issued on the workstation on which you are running conman, run the following command:
recall
or:
rc
To display pending prompts on workstation site3, run the following command:

rc site3
To display pending prompts on all workstations and have the output sent to conmans offline device, run the following command:
rc @;offline
299
redo
redo
Edits and reruns the previous command.
Syntax
redo
Context
When you run the redo command, conman displays the previous command, so that it can be edited and rerun. Use the spacebar to move the cursor under the character to be modified, and enter the following directives. Directives d[dir] itext rtext Deletes the character above the d. This can be followed by other directives. Inserts text before the character above the i. Replaces one or more characters with text, beginning with the character above the r. Replace is implied if no other directive is entered. Appends text to the end of the line.
>text
>d[dir | text] Deletes characters at the end of the line. This can be followed by another directive or text. >rtext Replaces characters at the end of the line with text.
Directive Examples ddd iabc rabc abc d diabc Deletes the character above the first d, skips one character, deletes the character above the second d, and inserts abc in its place. >abc >ddabc Deletes the last two characters in the line, and inserts abc in their place. >rabc Replaces the last three characters in the line with abc. Appends abc to the end of the line. Deletes the three characters above the ds. Inserts abc before the character above the i. Replaces the three characters, starting with the one above the r, with abc. Replaces the three characters above abc with abc.
Examples
To insert a character, run the following command:
redo setsm 4 iy setsym 4
To replace a character, run the following command:
300
redo
redo setsym 4 5 setsym 5
301
release job
release job
Releases jobs from dependencies. You must have release access to the job.
Syntax
rj jobselect [;dependency[;...]] [;noask]
Arguments
jobselect Specifies the job or jobs to be released. See Selecting jobs in commands on page 249. dependency The type of dependency. You can specify one of the following. You can use wildcard characters in workstation, jstreamname, jobname, resource, filename, and promptname. at[=time | lowtime | hightime | lowtime,hightime] confirmed deadline[=time[timezone | tz tzname][+n days | mm/dd[/yy]]] every follows=[netagent::][workstation#]{jobstreamname[hhmm [mm/dd[/yy]]][.job | @] | jobstream_id.job;schedid}| job[,...] needs[=[num] [workstation#]resource[,...]] opens[=[workstation#]filename[(qualifier)][,...]] priority prompt[=[: | !]text | promptname[,...]] until[=time [timezone|tz tzname][+n day[s]] [;onuntil action]] noask Specifies not to prompt for confirmation before taking action on each qualifying job.
Comments
When you release an opens dependency, you can include only the base file name, and conman performs a case-insensitive search for matching files, ignoring the directory names. Dependencies on all matching files are released. For needs dependencies, the released job is given the required number of units of the resource, even though they might not be available. This can cause the available units in a showresources to display a negative number. When you release a job from a priority dependency, the job reverts to its original scheduled priority. Released dependencies remain in effect when running the rerun command.
Examples
To release job job3 in job stream ap(1000 03/05/06) from all of its dependencies, run the following command:
302
release job
rj ap(1000 03/05/06).job3
To release all jobs on workstation site4 from their dependencies on a prompt named glprmt, run the following command:
rj site4#@.@;prompt=glprmt
See also
For the equivalent Job Scheduling Console task, see Releasing a Job Instance from Dependencies in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
303
release sched
release sched
Releases job streams from dependencies. You must have release access to the job stream.
Syntax
rs jstreamselect [;dependency[;...]] [;noask]
Arguments
jstreamselect See Selecting job streams in commands on page 257. dependency The type of dependency. Specify one of the following. You can use wildcard characters in workstation, jstream, job, resource, filename, and promptname. at[=time | lowtime | hightime | lowtime,hightime] carryforward deadline[=time[timezone | tz tzname][+n days | mm/dd[/yy]]] follows=[netagent::][workstation#]{jobstreamname[hhmm [mm/dd[/yy]]][.job | @] | jobstream_id.job;schedid}| job[,...] limit needs[=[num] [workstation#]resource[,...]] opens[=[workstation#]filename[(qualifier)][,...]] priority prompt[=[: | !]text | promptname[,...]] until[=time [timezone|tz tzname][+n day[s]] [;onuntil action]] noask Specifies not to prompt for confirmation before taking action on each qualifying job stream.
Comments
When deleting an opens dependency, you can include only the base file name, and conman performs a case-insensitive search for matching files, ignoring the directory names. Dependencies on all matching files are released. For needs dependencies, the released job stream is given the required number of units of the resource, even though they might not be available. This can cause the available units in a showresources to display a negative number. When you release a job stream from a priority dependency, the job stream reverts to its original priority. In certain circumstances, when you have submitted a deldep command, the command might have succeeded even though it is again forwarded to batchman. For more information, see Conman commands processing on page 249.
304
release sched
Examples
To release job stream instance with jobstream_id 0AAAAAAAAAAAABSE from all of its dependencies, run the following command:
rs 0AAAAAAAAAAAABSE; schedid
To release job stream sked5(1105 03/07/06) from all of its opens dependencies, run the following command:
rs sked5(1105 03/07/06);opens
To release all job streams on workstation site3 from their dependencies on job stream main#sked23, run the following command:
rs site3#@;follows=main#sked23
See also
For the equivalent Job Scheduling Console task, see Releasing a Job Stream Instance from Dependencies in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
305
reply
reply
Replies to a job or job stream prompt. You must have reply access to the named or global prompt. To reply to an unnamed prompt, you must have reply access to prompts, and reply access to the associated job or job stream.
Syntax
reply { promptname | [workstation#]msgnum} ;reply [;noask]
Arguments
promptname workstation msgnum Specifies the name of a global prompt. Wildcard characters are permitted. Specifies the name of the workstation on which an unnamed prompt was issued. Specifies the message number of an unnamed prompt. You can display message numbers with the recall and showprompts commands. Specifies the reply, either Y for yes or N for no. Specifies not to prompt for confirmation before taking action on each qualifying prompt.
reply noask
Comments
If the reply is Y, dependencies on the prompt are satisfied. If the reply is N, the dependencies are not satisfied and the prompt is not reissued. Prompts can be replied to before they are issued. You can use the showprompts command to display all prompts, whether or not they have been issued.
Examples
To reply Y to the global prompt arpmt, run the following command:
reply arprmt;y
To reply N to message number 24 on workstation site4, run the following command:

rep site4#24;n
306
rerun
rerun
Reruns a job. You must have rerun access to the job.
Syntax
rr jobselect [;from=[wkstat#]job[ ;at=time] [;pri=pri]] [;noask] rr jobselect [;step=step] [;noask]
Arguments
jobselect Specifies the name of one or more jobs. Wildcard characters are permitted. from=[wkstat#]job Specifies the name of a job defined in the database whose job file or command will be run in place of the job specified by jobselect. wkstat# Specifies the name of the workstation on which the from job runs. The default is the workstation on which conman is running. job Specifies the name of the from job definition The following types of job names are not permitted: v The names of jobs submitted using the submit file and submit docommand commands. v The alias names of jobs submitted using the submit job command.
To use the from argument, you must have access to the database from the computer on which you are running conman at=time Specifies the rerun jobs start time, expressed as follows: hhmm [timezone|tz tzname] [+n days | date] where: hhmm The hour and minute.
timezone|tz tzname The name of the time zone of the job. See Chapter 12, Managing time zones, on page 461 for valid names. pri=pri Specifies the priority to be assigned to the rerun job. If you do not specify a priority, the job is given the same priority as the original job.
307
rerun
step=step Specifies that the job is rerun using this name in place of the original job name. See Usage Notes for more information. noask Specifies not to prompt for confirmation before taking action on each qualifying job.
Comments
You can rerun jobs that are in the SUCC, FAIL, or ABEND state. A rerun job is placed in the same job stream as the original job, and inherits the original jobs dependencies. If you rerun a repetitive (every) job, the rerun job is scheduled to run at the same rate as the original job. Note: You can issue rerun for jobs in the EXTERNAL job stream that are in the ERROR state. Jobs in the EXTERNAL job stream represent jobs and job streams that have been specified as internetwork dependencies. The job state is initially set to extrn immediately after a rerun is run, and conman begins checking the state. When ;from is used, the name of the rerun job depends on the value of the Global Option retain rerun job names. If the option is set to Y, rerun jobs retain the original job names. If the option is set to N, rerun jobs are given the from job names. For more information, refer to the IBM Tivoli Workload Scheduler Planning and Installation Guide. In conman displays, rerun jobs are displayed with the notation >>rerun as. To refer to a rerun job in another command, such as altpri, you must use the original job name. When a job is rerun with the ;step option, the job runs with step in place of its original name. Within a job script, you can use the jobinfo command to return the job name and to run the script differently for each iteration. For example, in the following UNIX script, the jobinfo command is used to set a variable named STEP to the name that was used to run the job. The STEP variable is then used to determine how the script is run.
... MPATH=`maestro` STEP=`$MPATH/bin/jobinfo job_name` if [$STEP = JOB3] then ... STEP=JSTEP1 fi if [$STEP = JSTEP1] then ... STEP=JSTEP2 fi if [$STEP = JSTEP2] then ... fi ...
In conman displays, jobs rerun with the ;step option are displayed with the notation >>rerun step. For information about jobinfo, see jobinfo on page 390.
308
rerun
Examples
To rerun job job4 in job stream sked1 on workstation main, run the following command:
rr main#sked1.job4
To rerun job job5 in job stream sked2 using the job definition for job jobx where the jobs at time is set to 6:30 p.m. and its priority is set to 25, run the following command:
rr sked2.job5;from=jobx;at=1830;pri=25
To rerun job job3 in job stream sked4 using the job name jstep2, run the following command:
rr sked4.job3;step=jstep2
See also
For the equivalent Job Scheduling Console task, see Rerunning a Job Instance in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
309
resource
resource
Changes the number of total units of a resource. You must have resource access to the resource.
Syntax
resource [workstation#] resource;num [;noask]
Arguments
workstation Specifies the name of the workstation on which the resource is defined. The default is the workstation on which conman is running. Specifies the name of the resource. Specifies the total number of resource units. Valid values are 0 through 1024. Specifies not to prompt for confirmation before taking action on each qualifying resource.
resource num noask
Examples
To change the number of units of resource tapes to 5, run the following command:
resource tapes;5
To change the number of units of resource jobslots on workstation site2 to 23, run the following command:
res site2#jobslots;23
See also
For the equivalent Job Scheduling Console task, see Managing Resources in the Database in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
310
setsym
setsym
Selects a production plan archive file. Subsequent display commands show the contents of the archived production plan. You cannot modify the information in a production plan archive file.
Syntax
setsym [trial | forecast] [filenum]
Arguments
trial forecast filenum Lists trial plans. Lists forecast plans. Specifies the number of the production plan archive file. If you do not specify a log file number, the pointer returns to zero, the current production plan (Symphony). Use the listsym command to list archive file numbers.
Examples
To select production plan archive file 5, run the following command:
setsym 5
To select the current production plan (Symphony file), run the following command:
set
311
showcpus
showcpus
Displays information about workstations and links. | | | | The displayed information is updated only as long as Tivoli Workload Scheduler (batchman) is running on the workstations. Whether batchman is up or down is confirmed on screen by the Batchman LIVES or Batchman down message when you issue the conman start command. You must have list access to the object being shown if the enListSecChk option was set to yes on the master domain manager when the production plan was created or extended.
Syntax
sc [[domain!]workstation] [;info|;link] [;offline] | sc [[domain!]workstation] [;getmon]
Arguments
domain workstation Specifies the name of a domain. The default is the domain in which the command is run. Specifies the name of a workstation. The default is the workstation where the command is run. When no domain and no workstation are specified, the output can be the following: v The following command displays all the workstations that are in the domain of the workstation where the command was run, plus all the connected domain managers if the workstation is a domain manager.
conman "sc"
v The following command displays all the workstations that are in the domain of the workstation where the command was run, without the connected domain managers.
conman "sc @"
info link offline
Displays information in the info format. Displays information in the link format. Sends the output of the command to the conman output device. For information about this device, see Offline output on page 244. Returns the list of event rules defined for the monitor running on the specified workstation in the following format:
<rule_name>::<eventProvider>#<eventType>:<scope>
| | | | | | | |
getmon
The rule scope is automatically generated information about rule attributes, such as the workstations where it is deployed, a job or file name, etc.. The header of the output contains also the time stamp of when the rule configuration package was last generated.
312
showcpus
Results
| | | When the getmon parameter is not used, the output of the command is produced in three formats, standard, info, and link. When the getmon parameter is used, the list of rules is provided as separate output. Standard format: CPUID The name of the workstation to which this information applies. RUN NODE The node type and workstation type. Node types are as follows: v UNIX v WNT v OTHER Workstation types are as follows: v MASTER v MANAGER v FTA v S-AGENT v X-AGENT LIMIT The Tivoli Workload Scheduler job limit. FENCE The Tivoli Workload Scheduler job fence. DATE TIME The date and time Tivoli Workload Scheduler started running the current production plan (Symphony file). STATE | | | | | | | | | | | | | | | | | | | | | Displays the following information: v The state of the workstations links. Up to five characters are displayed as follows:
[L] [T|H|X] [I] [J] [W|H|X] [F]
The run number of the Symphony file .
where: L The primary link is open (linked) to its domain/upper manager. T This flag is displayed if the fault-tolerant agent is directly linked to the domain manager from where you run the command. H The workstation is linked through its host. X The workstation is linked as an extended agent (x-agent). I The jobman program has completed startup initialization. J The jobman program is running. W The writer process is active on the workstation. F The workstation is fully linked through primary and all secondary connections. This flag appears only if the enSwfaultTol global option is set to YES using the optman command line on the master domain manager and it indicates that the workstation is directly linked to its domain manager and to all its full backup domain managers. For information on how to use the optman command line, refer to IBM Tivoli Workload Scheduler: Planning and Installation Guide.
313
showcpus
| | | | | | | | | | | | | | | | | | | | | | | | | Note: If the workstation running conman is the extended agents host, the state of the extended agent is
LXI JX
If the workstation running conman is not the extended agents host, the state of the extended agent is
LHI JH
v The state of the monitoring agent. Up to three characters are displayed as follows:
[M] [E|e] [D]
where: M The monman process is running. E The event processing server is installed and running on the workstation. e The event processing server is installed on the workstation but is not running. D The workstation is using an up-to-date package monitoring configuration.. v The state of the WebSphere Application Server. A one-character flag is displayed, if the application server is installed:
[A|R]
where: A The WebSphere Application Server was started.
R The WebSphere Application Server is restarting. The flag is blank if the application server is down or if it was not installed. METHOD The name of the access method specified in the workstation definition. For extended agents only. DOMAIN The name of the domain in which the workstation is a member. Info format: CPUID The name of the workstation to which this information applies. VERSION The version of the Tivoli Workload Scheduler jobman program. TIMEZONE The time zone of the workstation. It is the same as the value of the TZ environment variable. For an extended agent, this is the time zone of its host. INFO The operating system version and hardware model. For extended agents, no information is listed. Link format: CPUID The name of the workstation to which this information applies. HOST The name of the workstation acting as the host to a standard agent or
314
showcpus
extended agent. For domain managers and fault-tolerant agents, this is the same as CPUID. For standard agent workstations, this is the name of the domain manager. For extended agents, this is the name of the host workstation. FLAGS The state of the workstations links. Up to five characters are displayed as follows:
[A] [B] [F] [s] [T]
A B F s T ADDR
Autolink is turned on in the workstation definition. This flag is used only in end-to-end environment and it indicates if the deactivate job launching flag is disabled. Full Status mode is turned on in the workstation definition. The ID of mailman server for the workstation. The link is defined as TCP/IP.
The TCP/IP port number for the workstation. NODE The node name of the workstation.
Examples
1. To display information about the workstation on which you are running conman in the info format, run the following command:
showcpus ;info
a sample output for this command is:

CPUID MASTER FTA1 FTA2 sc @!@;link VERSION 8.4 8.4 8.4 TIME ZONE US/Pacific INFO Linux 2.6.5-7.191-s390 #1 SM Linux 2.4.9-e.24 #1 Tue May HP-UX B.11.11 U 9000/785
2. To display link information for all workstations, run the following command:
a sample output is the following:

CPUID MASTER FTA1 FTA2 showcpus HOST MASTER FTA1 FTA2 FLAGS AF T AF T AF T ADDR 51099 51000 51000 NODE 9.132.239.65 CPU235019 9.132.235.42
3. To display information about the workstation, run the following command: If you run this command in an environment when the primary connection of the workstation with its domain or upper manager is not active, you receive the following output: | | | | | | | | | | |
CPUID MASTER FTA1 FTA2 FTA3 FTA4 FTA5 SA1 XA_FTA4 FTA6 FTA7 RUN NODE LIMIT FENCE DATE TIME STATE METHOD 360 *WNT MASTER 10 0 06/04/2007 1348 I J E 360 WNT FTA 10 0 06/04/2007 1348 FTI JW M U A 360 WNT FTA 10 0 06/04/2007 1348 FTI JW M U A 360 WNT MANAGER 10 0 06/04/2007 1348 LTI JW M U A 360 WNT FTA 10 0 06/04/2007 1348 F I J M U A 360 WNT FTA 10 0 06/04/2007 1348 I J M U A 360 WNT S-AGENT 10 0 06/04/2007 1348 F I J M U A 360 OTHR X-AGENT 10 0 06/04/2007 1348 L I J M U A 360 WNT MANAGER 10 0 06/04/2007 1348 F I J M U A 360 WNT FTA 10 0 06/04/2007 1349 F I J M U A DOMAIN MASTERDM MASTERDM MASTERDM DOMAIN1 DOMAIN1 DOMAIN1 DOMAIN1 DOMAIN1 DOMAIN2 DOMAIN2
315
showcpus
| If you run this command in an environment when the primary connection of the workstation with its domain or upper manager is active and at least one secondary connection is not active, you receive the following output:
CPUID MASTER FTA1 FTA2 FTA3 FTA4 FTA5 SA1 XA_FTA4 FTA6 FTA7 RUN NODE LIMIT FENCE DATE TIME STATE METHOD DOMAIN 360 *WNT MASTER 10 0 06/04/2007 1348 I J E MASTERDM 360 WNT FTA 10 0 06/04/2007 1348 FTI JW M U A MASTERDM 360 WNT FTA 10 0 06/04/2007 1348 FTI JW M U A MASTERDM 360 WNT MANAGER 10 0 06/04/2007 1348 FTI JW M U A DOMAIN1 360 WNT FTA 10 0 06/04/2007 1348 F I J M U A DOMAIN1 360 WNT FTA 10 0 06/04/2007 1348 L I M U A DOMAIN1 360 WNT S-AGENT 10 0 06/04/2007 1348 F I J M U A DOMAIN1 360 OTHR X-AGENT 10 0 06/04/2007 1348 L I J M U A DOMAIN1 360 WNT MANAGER 10 0 06/04/2007 1348 F I J M U A DOMAIN2 360 WNT FTA 10 0 06/04/2007 1349 F I J M U A DOMAIN2
| | | | | | | | | | | |
If you run this command in an environment when the primary connection of the workstation with its domain or upper manager and all secondary connections are active, you receive the following output:
CPUID MASTER FTA1 FTA2 FTA3 FTA4 FTA5 SA1 XA_FTA4 FTA6 FTA7 RUN NODE LIMIT FENCE DATE TIME STATE METHOD DOMAIN 360 *WNT MASTER 10 0 06/04/2007 1348 I J E MASTERDM 360 WNT FTA 10 0 06/04/2007 1348 FTI JW M U A MASTERDM 360 WNT FTA 10 0 06/04/2007 1348 FTI JW M U A MASTERDM 360 WNT MANAGER 10 0 06/04/2007 1348 FTI JW M U A DOMAIN1 360 WNT FTA 10 0 06/04/2007 1348 F I J M U A DOMAIN1 360 WNT FTA 10 0 06/04/2007 1348 F I M U A DOMAIN1 360 WNT S-AGENT 10 0 06/04/2007 1348 F I J M U A DOMAIN1 360 OTHR X-AGENT 10 0 06/04/2007 1348 L I J M U A DOMAIN1 360 WNT MANAGER 10 0 06/04/2007 1348 F I J M U A DOMAIN2 360 WNT FTA 10 0 06/04/2007 1349 F I J M U A DOMAIN2
| | | | | | | | | | | | | | | | | | | | | | | |
4. To get a list of active rule monitors on the workstation named CPU1, run this command:
sc CPU1 getmon
You get the following output:

Monitoring configuration for CPU1: ******************************************* *** Package Date : 04/22/2007 12:00 GMT *** ******************************************* Rule1::FileMonitor#FileCreated:Workstation=CPU1,CPU2;File=\tmp\filename Rule2::FileMonitor#ModificationCompleted:Workstation=CPU1,CPU3;File=\staging\orders Rule3::TWSObjectsMonitor#JobSubmit:JobKey=CPU1#JS1.Job1 Rule5::TWSObjectsMonitor#JobLate:JobKey=CPU1#JS1.Job1
See also
For the equivalent Job Scheduling Console task, see Working with Object Lists in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
316
showdomain
showdomain
Displays domain information. | | | | The displayed information is updated only as long as Tivoli Workload Scheduler (batchman) is running. Whether batchman is up or down is confirmed on screen by the Batchman LIVES or Batchman down message when you issue the conman start command. You must have list access to the object being shown if the enListSecChk option was set to yes on the master domain manager when the production plan was created or extended.
Syntax
showdomain [domain] [;info] [;offline]
Arguments
domain info offline Specifies the name of the domain. The default is the domain in which conman is running. Wildcard characters are permitted. Displays information in the info format. Sends the output of the command to the conman output device. For information about this device, see Offline output on page 244.
Results
The output of the command is produced in two formats, standard, and info. Standard format: DOMAIN The name of the domain to which this information applies. MANAGER The name of the domain manager. PARENT The name of the parent domain. Info format: DOMAIN The name of the domain to which this information applies. MEMBER-CPUS The names of the workstations in the domain. CPU-TYPE The type of each workstation: MASTER, MANAGER, fault-tolerant agent, S-AGENT, or X-AGENT.
Examples
To display information about the domain masterdm, run the following command:
showdomain masterdm
A sample output is the following:
317
showdomain
DOMAIN *MASTERDM MANAGER *MASTER PARENT
To display the member workstations in all domains in the info format, run the following command:
showdomain @;info

DOMAIN MASTERDM DOM1 DOM2 MEMBER-CPUs *MASTER FTA1 FTA2 CPU-Type MASTER MANAGER MANAGER
See also
For the equivalent Job Scheduling Console task, see Displaying and Modifying Domain Properties in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
318
showfiles
showfiles
Displays information about file dependencies. A file dependency occurs when a job or job stream is dependent on the existence of one or more files before it can begin running. | | | | The displayed information is updated only as long as Tivoli Workload Scheduler (batchman) is running. Whether batchman is up or down is confirmed on screen by the Batchman LIVES or Batchman down message when you issue the conman start command.
Syntax
sf [[workstation#]file] [;state[;...]] [;keys] [;offline] sf [[workstation#]file] [;state[;...]] [;deps[;keys | info | logon]] [;offline]
Arguments
workstation Specifies the name of the workstation on which the file exists. The default is the workstation on which conman is running. Wildcard characters are permitted. Specifies the name of the file. The name must be enclosed in quotes () if it contains characters other than the following: alphanumerics, dashes (-), slashes (/), backslashes (\), and underscores (_). The default is to display all file dependencies. Wildcard characters are permitted. Specifies the state of the file dependencies to be displayed. The default is to display file dependencies in all states. The states are as follows: yes no ? File exists and is available. File is unavailable, or does not exist. Availability is being checked.
file
state
<blank> The file has not yet been checked, or the file was available and used to satisfy a job or job stream dependency. keys deps offline Displays a single column list of the objects selected by the command. Displays information in the deps format. Use keys, info, or logon to modify the display. Sends the output of the command to the conman output device. For information about this device, see Offline output on page 244.
Results
The output of the command is produced in three formats: standard, keys, and deps. The arguments keys, info, and logon modify the deps display.
319
showfiles
Standard format: Exists The state of the file dependency. File Name The name of the file. Keys format: Files are listed with one file on each line. Directory names are not included. Each file is listed in the following format:
workstation#file
Deps format: Files are listed followed by the dependent jobs and job streams. Jobs are listed in the standard showjobs format. Job streams are listed in the standard showschedules format. Deps;keys format: Jobs and job streams that have file dependencies are listed with one on each line, in the following format:
workstation#jstream[.job]
Deps;info format: Files are listed, followed by the dependent jobs and job streams. Jobs are listed in the showjobs;info format. Job streams are listed in the standard showschedules format. Deps;logon format: Files are listed followed by the dependent jobs and job streams. Jobs are listed in the showjobs;logon format. Job streams are listed in the standard showschedules format.
Examples
To display the status of a file dependency for d:\apps\mis\lib\data4, run the following command:
showfiles d:\apps\mis\lib\data4
To display offline the status of all file dependencies on all workstations in the deps format, run the following command:
sf @#@;deps;offline
To display the status of all file dependencies on all workstations in the deps format, run the following command:
sf @#@;deps

Workstation Job Stream SchedTime Job (Est) (Est) State Pr Start Elapse ReturnCode Dependencies
MASTER#/test/^LFILEJOB^ Dependencies are: MASTER #LFILEJOB 0600 11/26 ******** READY 10 LFILEJOB HOLD 10 (11/26)
^LFILEJOB^
MASTER#/usr/home/me10_99/`/usr/home/me10_99/bin/parms FILE_JS1` Dependencies are: MASTER #FILE_JS1 0600 11/26 ******** HOLD 10 (11/26) parms FILE_JS1` FILE_JS1 HOLD 10 (11/26) MASTER#/usr/home/me10_99/`/usr/home/me10_99/bin/parms FILE_JOB1` Dependencies are: MASTER #FILE_JOB1 0600 11/26 ******** READY 10 FILE_JB1 HOLD 10 (11/26) parms FILE_JB1`
320
showjobs
showjobs
Displays information about jobs. | | | | The displayed information is updated only as long as Tivoli Workload Scheduler (batchman) is running. Whether batchman is up or down is confirmed on screen by the Batchman LIVES or Batchman down message when you issue the conman start command. You must have list access to the object being shown if the enListSecChk option was set to yes on the master domain manager when the production plan was created or extended.
Syntax
sj [jobselect] [;keys | info | step | logon | keys retcod] [;short | single] [;offline] [;showid] sj [jobselect] [;deps[;keys | info | logon]] [;short | single] [;offline] [;showid] sj [jobselect | [workstation#]jobnumber.hhmm] [;stdlist[;keys]] [;short | single] [;offline] [;showid]
Arguments
jobselect workstation jobnumber hhmm keys info step logon retcod See Selecting jobs in commands on page 249. The name of the workstation on which the job runs. Wildcard characters are permitted. The job number. The time the job started. Use this, together with the stdlist and single arguments, to display a specific instance of the job. Displays a single column list of the objects selected by the command. Displays information in the info format. Displays information in the step format. Displays information in the logon format. Displays the return code for the job. This argument must be used in conjunction with the keys argument, for example:
%sj @; keys retcod
stdlist
Displays information in the stdlist format. Use the keys argument to modify the display.
321
showjobs
deps short Displays information in the deps format. Use keys, info, or logon to modify the display. Shortens the display for every and rerun jobs to include only the following: v The first iteration v Jobs in different states v Exactly matched jobs Selects only the parent job in a chain that can include reruns, repetitions, and recovery jobs. The job must be identified by job number in jobselect. This is useful with the stdlist option. Sends the output of the command to the conman output device. For information about this device, see Offline output on page 244. Displays for each job stream the job stream identifier.
single
offline
showid
Results
The output of the showjobs command is produced in seven formats: standard, keys, info, step, logon, deps, and stdlist. The arguments keys, info, and logon modify the displays. Standard format: CPU The workstation on which the job runs.
Schedule The name of the job stream. Job The name of the job. The following notation may precede a job name: >> rerun as A job that was rerun with the rerun command, or as a result of automatic recovery. >> rerun step A job that was rerun with the rerun ;step command. >> every run The second and subsequent runs of an every job. >> recovery The run of a recovery job. State The state of the job or job stream. Job states are as follows: ABEND The job ended with a non-zero exit code. ABENP An abend confirmation was received, but the job is not completed. ADD DONE The job completed in an unknown state. ERROR For internetwork dependencies only, an error occurred while checking for the remote status. EXEC The job is running. The job is being submitted.
322
showjobs
EXTRN For internetwork dependencies only, the status is unknown. An error occurred, a rerun action was just performed on the job in the EXTERNAL job stream, or the remote job or job stream does not exist. FAIL FENCE The priority of the job is below the fence. HOLD The job is awaiting dependency resolution. INTRO The job is introduced for launching by the system. PEND The job completed, and is awaiting confirmation. READY The job is ready to launch, and all dependencies are resolved. SCHED The at time set for the job has not been reached. SUCC The job completed with an exit code of zero. SUCCP A SUCC confirmation was received, but the job is not completed. WAIT The job is in the WAIT state (extended agent). Job stream states are as follows: ABEND The job stream ended with a nonzero exit code. ADD The job stream was added with operator intervention. Unable to launch the job.
CANCL The job stream was cancelled. CANCELP The job stream is pending cancellation. Cancellation is deferred until all of the dependencies, including an at time, are resolved. ERROR For internetwork dependencies only, an error occurred while checking for the remote status. EXEC The job stream is running. EXTRN For internetwork dependencies only, the job stream is in a remote Tivoli Workload Scheduler network and its state is unknown. An error occurred, a rerun action was just performed on the EXTERNAL job stream, or the INET job or job stream does not exist. HOLD The job stream is awaiting dependency resolution. READY The job stream is ready to launch and all dependencies are resolved.
323
showjobs
STUCK Execution of the job stream was interrupted. No jobs are launched without operator intervention. SUCC The job stream completed successfully. Pr The priority of the job stream or job. A plus sign (+) preceding the priority means the job has been launched.
(Est)Start The start time of the job stream or job. Parentheses indicate an estimate of the start time. If the start time is more than 24 hours in the past or future, the date is listed instead of the time. (Est)Elapse The run time of the job stream or job. Parentheses indicate an estimate based on logged statistics. dependencies A list of job dependencies and comments. Any combination of the following can be listed: v For a follows dependency, a job stream or job name is displayed. In case of an orphaned dependency an [O] is displayed. For more information on orphaned dependencies refer to Managing external follows dependencies for jobs and job streams on page 59. v For an opens dependency, the file name is displayed. If the file resides on an extended agent and its name is longer than 25 characters, only the last 25 characters are displayed. v For a needs dependency, a resource name enclosed in hyphens (-) is displayed. If the number of units requested is greater than one, the number is displayed before the first hyphen. v For a deadline time, the time preceded by an angle bracket (<) is displayed. v For an every rate, the repetition rate preceded by an ampersand (&) is displayed. v For an until time, the time preceded by an angle bracket (<) is displayed. v For a prompt dependency, the prompt number is displayed in the format #num. For global prompts, the prompt name follows in parentheses. v For running jobs, the process identification number (PID) is displayed in the format #Jnnnnn. v Jobs submitted on UNIX using the Tivoli Workload Scheduler at and batch commands are labeled [Userjcl]. v When reporting time dependencies the showjobs command shows in the Start column: Only the time hh:mm if the day when the time dependencies is set matches with the day when the showjobs command is run. Only the date MM/DD if the day when the time dependencies is set does not match with the day when the showjobs command is run. v Cancelled jobs are labeled [Cancelled]. v Jobs cancelled with ;pend option are labeled [Cancel Pend]. v Jobs with expired until times, including jobs cancelled with ;pend option, are labeled [Until]. v [Recovery] means that operation intervention is required.
324
showjobs
v [Confirm] means that confirmation is required because the job was scheduled using the confirm keyword. v [Script] applies to end-to-end networks only; it means that this job has a centralized script and that Tivoli Workload Scheduler for z/OS has not yet downloaded it to the agent. Keys format: Job names are listed one on each line in the following format:
workstation#jstream hhmm mm/dd.job
for example:
CPU Schedule SchedTime Job State Pr Start Elapse RetCode Deps [03/04/06]; #33 #1(PRMT3);-16 JOBSLOTS[03/04/06]; #34 #1(PRMT3);-16 JOBSLOTS-
MYCPU+#SCHED_F+ 0600 03/04 ******* HOLD 55(03/04) (M235062+#)JOBMDM HOLD 30(03/04) MYCPU+#SCHED_F+ 1010 03/04 ******* HOLD 55(03/04) (M235062+#)JOBMDM HOLD 30(03/04)
325
showjobs
Info format: CPU The workstation on which the job runs.
Schedule The name of the job stream. Job The name of the job. The following notation might precede a job name: >> rerun as A job that was rerun with the rerun command, or as a result of automatic recovery. >> rerun step A job that was rerun with the rerun ;step command. >> every run The second and subsequent runs of an every job. >> recovery The run of a recovery job. Job File The name of the script or executable file of the job. Long file names might wrap, causing incorrect paging. To avoid this, pipe the output to more. Opt Job Prompt The number of the recovery prompt, if any. For example:
conman "sj;info | more
The job recovery option, if any. The recovery options are RE for rerun, CO for continue, and ST for stop. The name of the recovery job, if any.
produces a sample output like the following:

-------- Restart --------CPU Schedule SchedTime Job M235062+#SCHED_22 1010 03/06 JOBMDM (B236153+#)JOB_FTA M235062+#SCHED_22 0600 03/07 JOBMDM (B236153+#)JOB_FTA M235062+#FINAL 0559 03/07 MAKEPLAN SWITCHP+ CREATEP+ UPDATES+ M235062+#SCHED12 1010 03/06 JOBMDM (B236153+#)JOB_FTA JobFile /usr/acct/scripts/gl1 echo pippo /usr/acct/scripts/gl1 echo pippo /home/tws83/MakePlan TWSRCMAP:(RC=0) OR (RC=4) /home/tws83/SwitchPlan /home/tws83/CreatePostReports /home/tws83/UpdateStats /usr/acct/scripts/gl1 echo pippo Opt Job Prompt
Step format: This format is not supported in Windows. CPU The workstation on which the job runs.
Schedule The name of the job stream. Job The name of the job. The following notation might precede a job name:
326
showjobs
>> rerun as A job that was rerun with the rerun command, or as a result of automatic recovery. >> repeated as The second and subsequent runs of an every job. State The state of the job or job stream. See Standard Format for information about state.
Return code The return code of the job. Job# Step The process identification number displayed as #Jnnnnn. A list of descendant processes that are associated with the job. For extended agent jobs, only host processes are listed.
Logon format: CPU The workstation on which the job runs.
Schedule The name of the job stream. Job The name of the job. The following notation might precede a job name: >> rerun as A job that was rerun with the rerun command, or as a result of automatic recovery. >> repeated as The second and subsequent runs of an every job. State The state of the job or job stream. See Standard Format for information about state.
Return code The return code of the job. Job# The process identification number displayed as #Jnnnnn.
Logon The user name under which the job runs. Stdlist format: A standard list file is created automatically by jobmon in Windows or jobman in UNIX, for each job that jobmon and jobman launches. You can display the contents of the standard list files using conman. A standard list file contains: v Header and trailer banners. v Echoed commands. v The stdout output of the job. v The stderr output of the job. To specify a particular date format to be used in the standard list files, change the IBM Tivoli Workload Scheduler date format before creating the standard list files. You do this by modifying the date locale format. Depending on your environment, change the date locale format by performing the steps listed below: v In UNIX, set the LANG variable in the environment when netman starts. If the LANG variable is not set, the operating system locale is set by default to C. v In Windows, perform the following steps:
327
showjobs
1. Go to Control PanelRegional Options and set your locale (location). 2. Right-click on My Computer, go to Properties, click on Advanced, go to Environment Variables and set the LANG variable as a system variable. 3. Shut down and restart the system. The standard list files for the selected jobs are displayed. Stdlist;keys format: The names of the standard list files for the selected jobs are listed, one on each line. Deps format: Jobs used in follows dependencies are listed followed by the dependent jobs and job streams. Jobs are listed in the standard showjobs format. Job streams are listed in the standard showschedules format. Deps;keys format: Jobs and job streams that have follows dependencies are listed, one on each line. Deps;info format: Jobs used in follows dependencies are listed, followed by the dependent jobs and job streams. Jobs are listed in the showjobs;info format. Job streams are listed in the standard showschedules format. Deps;logon format: Jobs used in follows dependencies are listed, followed by the dependent jobs and job streams. Jobs are listed in the showjobs;logon format. Job streams are listed in the standard showschedules format.
Examples
To display the status of all jobs in the acctg job stream on workstation site3, you can run the showjobs command in one of these two formats:
showjobs site3#acctg.@
or:
showjobs site3#acctg
To display the status of job JBA belonging to job stream TEST1 on workstation CPUA, on which you are running conman, and ask to show the job stream identifier for the job stream, run the following command:
sj CPUA#TEST1(0900 02/19/06).JBA
A sample output for this command is the following:

Workstation Job Stream SchedTime Job State Pr Start Elapse ReturnCode Dependencies CPUA #TEST1 0900 02/19 *** HOLD 0(02/19) JBA HOLD 66(14:30) {02/20/06}; -TESTJ2(0600 02/24/06).JB1
The at dependency is shown as (14:30) in the Start column and the follows dependency from the job J2(0600 02/24/06).JB1 for job JOBA is shown in the Dependencies column. In the Dependencies column the date enclosed in braces, {02/20/06}, indicates that the job stream instance has been carried forward and the date indicates the day when the job stream instance was added to the production plan for the first time. To display the status of jobs belonging to job stream JSDOC on workstation site3, on which you are running conman, and ask to show the job stream identifier for the job stream, run the following command:
%sj JSDOC.@;showid
328
showjobs
Workstation Job Stream SchedTime Job State Pr Start Elapse ReturnCode Dependencies site3 #JSDOCOM 0600 11/26 *** SUCC 10 11/26 00:01 JDOC SUCC 10 11/26 00:01 0 {0AAAAAAAAAAAACRZ} #J25565
The job stream identifier 0AAAAAAAAAAAACRZ for job stream JDOCOM is shown in the Dependencies column. Note: The time or date displayed in the Start column is converted in the time zone set on the workstation where the job stream is to run. To display the status of jobs belonging to job stream JSDOCOM on workstation site3, and ask to show the information about the user ID under which the job runs, run the following command:
sj site3#JSDOCOM.@;logon

Workstation Job Stream SchedTime Job State Job# Logon ReturnCode site3 #JSDOCOM 0600 11/26 JDOCOM SUCC #J25565 me10_99 0
To display the status of all jobs in the HOLD state on all workstations, in the deps format, run the following command:
sj @#@.@+state=hold;deps

Workstation Job Stream SchedTime Job State Pr Start Elapse RetCode Dependencies CPUA#JS2.JOBB Dependencies are: CPUA #JS21 0900 02/19 ***** HOLD 0(02/19) {02/20/06}; -TEST- JOBA HOLD 66(14:30) JS22(0600 02/24/06).JOBB
CPUA#JS25.JOBC Dependencies are: CPUA #JS25 0600 02/24 ***** HOLD 10(02/24) jobaa HOLD 10(02/24)(00:01) {02/20/06} TEST1; JOBC
TEST2; JOB1 JS18(0600 02/24/06).@
CPUA#JS25.JOB1 Dependencies are: CPUA #JS25 0600 02/24 ***** HOLD 10(02/24) JOBC HOLD 10(02/24)(00:01) jobaa HOLD 10(02/24)(00:01) {02/20/06} JOB1 TEST1; JOBC
TEST2; JOB1
JS18(0600 02/24/06).@
To display the log from the standard list files for the job J25 in the job stream JS25(0600 02/19/06) on workstation CPUA, running in a UNIX environment, run the following command:
sj CPUA#JS25(0600 02/19/06).J25;stdlist
The output is the following:

=============================================================== = JOB : CPUA#JS25[(0600 02/19/06),(0AAAAAAAAAAAABQM)].J25 = USER : tme10_99
329
showjobs
= JCLFILE : ls = Job Number: 28630 = Mon 02/20/06 07:57:37 PST =============================================================== Tivoli Workload Scheduler (UNIX)/JOBMANRC AWSBIS307I Starting /usr/home/tme10_99/jobmanrc ls Tivoli Workload Scheduler (UNIX)/JOBINFO 8.4 (9.5) Installed for user "tme10_99". Locale LANG set to the following: "en" ... ... <stdout, stderr, and echoed commands> ... AWSBIS308I End of job =============================================================== = Exit Status : 0 = System Time (Seconds) : 0 Elapsed Time (Minutes) : 0 = User Time (Seconds) : 0 = Mon 02/20/06 07:57:38 PST ===============================================================
where: Exit Status Is the status of the job when it completed. Elapsed Time Is the elapsed time for the job. System Time Is the time the kernel system spent for the job. User Time Is the time the system user spent for the job. Note: The System Time and User Time fields are used only in UNIX. Their values in Windows are always set to 0. This is because, in Windows, the joblnch.exe process runs in a very short time, which can be considered null. The following example displays the status of the job dbseload with a return code of 7 and a state of SUCCESSFUL:
$conman sj workstation#DAILY_DB_LOAD Tivoli Workload Scheduler (UNIX)/CONMAN 8.4 (1.36.2.22) 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 "tme10_99". Locale LANG set to the following: "en" Scheduled for (Exp) 02/20/06 (#35) on CPUA. Batchman LIVES. Limit:50,Fence:0,Audit Level:0 sj workstation#DAILY_DB_LOAD (Est) (Est) CPU Schedule Job State Pr Start Elapse Dependencies Return Code WORKSTATION #DAILY_DB_LOAD ****************************** SUCC 10 22:11 00:04 DATASPLT SUCC 10 22:11 00:01 #J17922 0 DATAMRGE ABEND 10 22:12 00:01 #J17924 1
330
showjobs
CHCKMRGE SUCC 00:01 #J17926 DATACLNS SUCC 00:01 #J17932 DATARMRG SUCC 00:01 #J18704 DBSELOAD SUCC 00:01 #J18706 DATAREPT SUCC 00:01 #J18712 DATARTRN SUCC 00:01 #J18714 $ 10 0 10 0 10 0 10 7 10 0 10 0 22:12 22:12 22:13 22:13 22:13 22:14
The following example displays the return code for a specific job named workstation#daily_db_load.dbseload:
$ conman sj workstation#daily_db_load.dbseload\;keys\;retcod Tivoli Workload Scheduler (UNIX)/CONMAN 8.4 (1.36.2.22) 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 "tme10_99". Locale LANG set to the following: "en" Scheduled for (Exp) 02/20/06 (#35) on CPUA. Batchman LIVES. Limit:50,Fence:0,Audit Level:0 sj workstation#daily_db_load.dbseload;keys;retcod 8 $
The retcod feature when integrated into a script can become quite powerful.
See also
For the equivalent Job Scheduling Console task, see Working with Object Lists in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
331
showprompts
showprompts
Displays information about prompts. | | | | The displayed information is updated only as long as Tivoli Workload Scheduler (batchman) is running. Whether batchman is up or down is confirmed on screen by the Batchman LIVES or Batchman down message when you issue the conman start command. You must have list access to the object being shown if the enListSecChk option was set to yes on the master domain manager when the production plan was created or extended.
Syntax
sp [promptselect] [;keys] [;offline] sp [promptselect] [;deps[;keys | info | logon]][;offline]
Arguments
promptselect [promptname | [workstation#]msgnum][;state[;...]] promptname Specifies the name of a global prompt. Wildcard characters are permitted. workstation Specifies the name of the workstation on which an unnamed prompt is issued. The default is the workstation on which conman is running. msgnum Specifies the message number of an unnamed prompt. state Specifies the state of prompts to be displayed. The states are as follows: YES NO The prompt was replied to with y. The prompt was replied to with n.
ASKED The prompt was issued, but no reply was given. INACT The prompt has not been issued. keys deps info Displays a single column list of the objects selected by the command. Displays information in the deps format. Use keys, info, or logon to modify the display. Displays information in the info format.
logon Displays information in the logon format. offline Sends the output of the command to the conman output device. For information about this device, see Offline output on page 244.
332
showprompts
Note: Prompt numbers assigned to both global and local prompts change when the production plan is extended.
Results
The output of the command is produced in three formats: standard, keys, and deps. The arguments keys, info, and logon modify the deps display. Standard format: State The state of the prompt.
Message or Prompt For named prompts, the message number, the name, and the text of the prompt. For unnamed prompts, the message number, the name of the job or job stream, and the text of the prompt. Keys format: The prompts are listed one on each line. Named prompts are listed with their message numbers and names. Unnamed prompts are listed with their message numbers, and the names of the jobs or job streams in which they appear as dependencies. Deps format: Prompts used as dependencies are listed, followed by the dependent jobs and job streams. Jobs are listed in the standard showjobs format. Job streams are listed in the standard showschedules format. Deps;keys format: Jobs and job streams that have prompt dependencies are listed one on each line. Deps;info format: Prompts used as dependencies are listed, followed by the dependent jobs and job streams. Jobs are listed in the showjobs;info format. Job streams are listed in the standard showschedules format. Deps;logon format: Prompts used as dependencies are listed, followed by the dependent jobs and job streams. Jobs are listed in the showjobs;logon format. Job streams are listed in the standard showschedules format.
Examples
To display the status of all prompt issued on the workstation on which you are running conman, run the following command:
showprompts
a sample is the following:

State Message or Prompt ASKED 1(PRMT3) !continue? INACT 3(CPUA#SCHED_12[(0600 03/12/06), (0AAAAAAAAAAAABST)]) Are you ready to process job1? INACT 5(CPUA#SCHED_12[(1010 03/12/06),(0AAAAAAAAAAAABSU)]) Are you ready to process job2? INACT 7(CPUA#SCHED_22[(0600 03/12/06),(0AAAAAAAAAAAABTR)]) Are you ready to process job3?
To display the status of all mis prompts that have been issued, in the deps format, run the following command:
sp mis@;asked;deps
To display the status of prompt number 7 on workstation CPUA, run the following command:
sp CPUA#7
333
showprompts
The output of the command is:
INACT 7(CPUA#SCHED_22[(0600 03/12/06),(0AAAAAAAAAAAABTR)]) Are you ready to process job3?
See also
For the equivalent Job Scheduling Console task, see Displaying and Modifying Prompt Properties in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
334
showresources
showresources
Displays information about resources. | | | | The displayed information is updated only as long as Tivoli Workload Scheduler (batchman) is running. Whether batchman is up or down is confirmed on screen by the Batchman LIVES or Batchman down message when you issue the conman start command. You must have list access to the object being shown if the enListSecChk option was set to yes on the master domain manager when the production plan was created or extended.
Syntax
sr [[workstation#]resourcename] [;keys] [;offline] sr [[workstation#]resourcename] [;deps[;keys | info | logon]] [;offline]
Arguments
workstation Specifies the name of the workstation on which the resource is defined. The default is the workstation on which conman is running. Specifies the name of the resource. Wildcard characters are permitted. Displays a single column list of the objects selected by the command. Displays information in the deps format. Use keys, info, or logon to modify the display. Displays information in the info format. Displays information in the logon format. Sends the output of the command to the conman output device. For information about this device, see Offline output on page 244.
resourcename keys deps info logon offline
Results
The output of the command is produced in three formats: standard, keys, and deps. The arguments keys, info, and logon modify the deps display. Standard format: CPU Resource Total Available Qty Used By The workstation on which the resource is defined. The name of the resource. The total number of defined resource units. The number of resource units that have not been allocated. The number of resource units allocated to a job or job stream. The name of the job or job stream.
Keys format: The resources are listed one on each line.

335
showresources
Deps format: Resources used as dependencies are listed, followed by the dependent jobs and job streams. Jobs are listed in the standard showjobs format. Job streams are listed in the standard showschedules format. Deps;keys format: Jobs and job streams that have resource dependencies are listed one on each line. Deps;info format: Resources used as dependencies are listed, followed by the dependent jobs and job streams. Jobs are listed in the showjobs;info format. Job streams are listed in the standard showschedules format. Deps;logon format: Resources used as dependencies are listed, followed by the dependent jobs and job streams. Jobs are listed in the showjobs;logon format. Job streams are listed in the standard showschedules format.
Examples
To display information about all resources on the workstation on which you are running conman, run the following command:
showresources
A sample output is:

CPU#Resource CPUA #JOBSLOTS Total Available 16 16 Qty UsedBy No holders of this resource
To display information about the jobslots resource on workstation CPUA in the deps format, run the following command:
sr CPUA#JOBSLOTS;deps

(Est) (Est) Workstation Job Stream SchedTime Job State Pr Start Elapse RetCode Dependencies CPUA FTAA FTAA FTAA #JOBSLOTS Dependencies are: #SCHED_F+ 0600 03/04 ****** HOLD 55(03/04) (CPUA#)JOBMDM HOLD 30(03/04) #SCHED_F+ 1010 03/04 ****** HOLD 55(03/04) (CPUA#)JOBMDM HOLD 30(03/04) #SCHED_F+ 0600 03/05 ****** HOLD 55(03/05) (CPUA#)JOBMDM HOLD 30(03/05) [03/04/06];#33 #1(PRMT3);-16 JOBSLOTS[03/04/06];#34 #1(PRMT3);-16 JOBSLOTS[03/04/06];#35 #1(PRMT3);-16 JOBSLOTS-
See also
For the equivalent Job Scheduling Console task, see Displaying Resource Properties in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
336
showschedules
showschedules
Displays information about job streams. | | | | The displayed information is updated only as long as Tivoli Workload Scheduler (batchman) is running. Whether batchman is up or down is confirmed on screen by the Batchman LIVES or Batchman down message when you issue the conman start command. You must have list access to the object being shown if the enListSecChk option was set to yes on the master domain manager when the production plan was created or extended.
Syntax
ss [jstreamselect] [;keys] [;offline] [;showid] ss [jstreamselect] [;deps[;keys | info | logon]] [;offline] [;showid]
Arguments
jstreamselect keys deps info logon offline See Selecting job streams in commands on page 257. Displays a single column list of the objects selected by the command. Displays information in the deps format. Use keys, info, or logon to modify the display. Displays information in the info format. Displays information in the logon format. Sends the output of the command to the conman output device. For information about this device, see Offline output on page 244. Displays for each job stream the job stream identifier.
showid
Results
The output of the command is produced in three formats: standard, keys, and deps. The arguments keys, info, and logon modify the deps display. Standard format: CPU The workstation on which the job stream runs.
Schedule The name of the job stream. State The state of the job stream. The states are as follows: ADD The job stream was added with operator intervention.
ABEND The job stream ended with a nonzero exit code.
337
showschedules
CANCL The job stream was cancelled. CANCELP The job stream is pending cancellation. Cancellation is deferred until all of the dependencies, including an at time, are resolved. ERROR For internetwork dependencies only, an error occurred while checking for the remote status. EXEC The job stream is running. EXTRN For internetwork dependencies only, the job stream is in a remote Tivoli Workload Scheduler network and its status is unknown. An error occurred, a rerun action was just performed on the EXTERNAL job stream, or the INET job or job stream does not exist. HOLD The job stream awaiting dependency resolution. READY The job stream is ready to launch and all dependencies are resolved. STUCK Job stream execution was interrupted. No jobs are launched without operator intervention. SUCC The job stream completed successfully. Pr The priority of the job stream.
(Est)Start The start time of the job stream. Parentheses indicate an estimate of the start time. If the start time is more than 24 hours in the past or future, the date is listed instead of the time. (Est)Elapse The run time of the job stream. Parentheses indicate an estimate based on logged statistics. Jobs # The number of jobs in the job stream. Jobs OK The number of jobs that have completed successfully. Sch Lim The job streams job limit. If one is not listed, no limit is in effect. dependencies A list of job stream dependencies and comments. Any combination of the following may be listed: v For a follows dependency, a job stream or job name is displayed. v For an opens dependency, the file name is displayed. If the file resides on an extended agent, and its name is longer than 25 characters, only the last 25 characters are displayed. v For a needs dependency, a resource name enclosed in hyphens (-) is displayed. If the number of units requested is greater than one, the number is displayed before the first hyphen. v For an until time, the time preceded by an angled bracket (<).
338
showschedules
v For a prompt dependency, the prompt number displayed as #num. For global prompts, the prompt name in parentheses follows. v Cancelled job streams are labeled [Cancelled]. v Job streams cancelled with the ;pend option are labeled [Cancel Pend]. v For a deadline time, the time preceded by an angle bracket (<) is displayed. v Job streams with expired until times, including job streams cancelled with the ;pend option, are labeled: [Until]. v Job streams that contain the carryforward keyword are labeled [Carry]. v For job streams that were carried forward from the previous production plan, the original name and date are displayed in brackets. v When reporting time dependencies the showschedules command shows in the Start column: Only the time hh:mm if the day when the time dependencies is set matches with the day when the showschedules command is run. Only the date mm/dd if the day when the time dependencies is set does not match with the day when the showschedules command is run. Note: The time or date displayed in the Start column is converted in the time zone set on the workstation where the job stream is to run. Keys format: The job streams are listed one on each line. Deps format: Job streams used as dependencies are listed, followed by the dependent jobs and job streams. Jobs are listed in the standard showjobs format. Job streams are listed in the standard showschedules format. Deps;keys format: Job streams that have follows dependencies are listed one on each line. Deps;info format: Job streams used in as dependencies are listed, followed by the dependent jobs and job streams. Jobs are listed in the showjobs;info format. Job streams are listed in the standard showschedules format. Deps;logon format: Job streams used in as dependencies are listed, followed by the dependent jobs and job streams. Jobs are listed in the showjobs;logon format. Job streams are listed in the standard showschedules format.
Examples
To display the status of job stream CLEM_DOCOM on workstation site3, and ask for the job stream identifier run the following command:
%ss @#JS_DOCOM ;showid
A sample output of this command is the following:

(Est) (Est) Jobs Sch Workstation Job Stream SchedTime State Pr Start Elapse # OK Lim site3 #JS_DOCOM 0600 11/26 SUCC 10 11/26 00:01 1 1 {0AAAAAAAAAAAACRZ}
To display the status of all job streams in the HOLD state on the workstation on which you are running conman, run the following command:
showschedules @+state=hold

339
showschedules
(Est) (Est) Jobs Sch Workstation Job Stream SchedTime State Pr Start Elapse # OK Lim site3 #FILE_JS1 0600 11/26 HOLD 10 (11/26) 1 0 parms FILE_JS1`
To display the status of all job streams with name beginning with sched on workstation CPUA in the deps;info format, run the following command:
ss CPUA#sched@;deps;info

-------- Restart --------CPU Schedule SchedTime Job JobFile Opt Job Prompt
CPUA #JS_FIRST1[(0600 03/10/06),(0AAAAAAAAAAAABVY)] Dependencies are: CPUA#MOD 0212 03/10 JOBMDM /usr/scripts/gl1(B236153+#)JOB_FTA1 echo Start gl1? CPUA#MOD 0251 03/10 JOBMDM /usr/scripts/gl2(B236153+#)JOB_FTA2 echo Start gl2?
To display offline the status of all job streams in the ABEND state on all workstations, run the following command:
ss @#@+state=abend;off
To display the status of all job streams on all workstations, run the following command:
%ss @#@
This is a sample output for the command:

Workstation site3 site3 site2 site3 site3 site1 site3 site3 Job Stream #JS_DOCOM #JS_SCRIPT #JS_PRED1 #JS_SCRIPT1 #LFILEJOB #RES_100 #FILE_JS1 #FILE_JOB SchedTime 0600 11/26 0600 11/26 1000 11/26 0600 11/26 0600 11/26 0600 11/26 0600 11/26 0600 11/26 State SUCC SUCC SUCC ABEND READY SUCC HOLD SUCC Pr 10 10 10 10 10 10 10 10 (Est) Jobs Sch Elapse # OK Lim 00:01 1 1 00:03 1 1 00:01 1 1 00:01 1 0 1 0 11/26 00:09 1 1 (11/26) 1 0 11/26 00:01 1 1 (Est) Start 11/26 11/26 11/26 11/26
parms FILE_JS1`
See also
For the equivalent Job Scheduling Console task, see Displaying a Job Stream in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
340
shutdown
shutdown
Unconditionally stops all the Tivoli Workload Scheduler production processes and , including batchman, jobman, netman, mailman, all mailman servers, and all writer processes. It does not stop the WebSphere Application Server services. You must have shutdown access to the workstation.
Syntax
shut[down] [;wait]
Arguments
wait Waits until all processes have stopped before prompting for another command.
Comments
| | | | | | | The shutdown command stops the processes only on the workstation on which conman is running. To restart netman only, run the StartUp command. For information about the StartUp command, see StartUp on page 409. To restart the entire process tree, run the following conman commands:
start startappserver startmon
You must run a conman unlink @ command before executing a shutdown command.
Examples
To shut down production on the workstation on which you are running conman, run the following command:
unlink @ shutdown
To shut down production on the workstation on which you are running conman and wait for all processes to stop, run the following command:
unlink@;noask shut ;wait
341
start
start
| | | Starts Tivoli Workload Scheduler production processes, except for the event monitoring engine and WebSphere Application Server (seestartappserver on page 345 and startmon on page 347 to learn the commands that start these processes). Note: Make sure conman start is not issued while either JnextPlan or stageman runs. You must have start access to the workstation.
Syntax
start [domain!]workstation [;mgr] [;noask] [;demgr]
Arguments
domain Specifies the name of the domain in which workstations are started. Wildcard characters are permitted. This argument is useful when starting more than one workstation in a domain. For example, to start all the agents in domain stlouis, use the following command:
start stlouis!@
If domain is omitted, and workstation contains wildcard characters, the default domain is the one in which conman is running. workstation mgr Specifies the name of the workstation to be started. Wildcard characters are permitted. This can be entered only on the workstation on which conman is running. It starts the local workstation as the domain manager. The workstation becomes the new domain manager and the current domain manager becomes a fault-tolerant agent. This form of the command usually follows a stop command. Note: The preferred method of switching a domain manager is to use a switchmgr command. See switchmgr on page 367 for more information. noask demgr Specifies not to prompt for confirmation before taking action on each qualifying workstation. This option prevents the opening of external connections during the transition time between when an agent starts as an old domain manager, and when the switchmgr command is run, depriving the agent of the domain manager function. This option is run automatically, but until the old domain manager has processed the switchmgr event (in the case, for example, of delayed restart or restart after repairing a damaged agent), the demgr option must be used to start the old domain manager from the local command line. For more details on this option, see the IBM Tivoli Workload Scheduler Planning and Installation Guide.
342
start
Comments
The start command is used at the start of each production period to restart Tivoli Workload Scheduler following preproduction processing. At that time it causes the autolinked fault-tolerant agents and standard agents to be initialized and started automatically. Agents that are not autolinked are initialized and started when you run a link command. Assuming the user has start access to the workstations being started, the following rules apply: v A user running conman on the master domain manager can start any workstation in the network. v A user running conman on a domain manager other than the master can start any workstation in that domain and subordinate domains. The user cannot start workstations in peer domains. v A user running conman on an agent can start workstations that are hosted by that agent.
Examples
Figure 11 and Table 46 below show the workstations started by start commands run by users in various locations in the network. DMn are domain managers and Ann are agents.
A11 DM1 A12 Domain1 User1
DM4 Domain4 A41 A42
Figure 11. Started workstations in network Table 46. Started workstations Command start @!@ Started by User1 Started by User2 Started by User3 A21
All workstations are DM2 started A21 A22 DM4 A41 A42 DM1 A11 A12 DM3 A31 A32 DM2 A21 A22 Not allowed
start @
A21
start DOMAIN3!@
Not allowed
343
start
Table 46. Started workstations (continued) Command start DOMAIN4!@ Started by User1 DM4 A41 A42 DM2 A42 A31 Started by User2 DM4 A41 A42 DM2 A42 Not allowed Started by User3 Not allowed
start DM2 start A42 start A31
Not allowed Not allowed Not allowed
344
startappserver
| | | | | | | | | | | | | | | | | | | | | | | workstation
startappserver
Starts the embedded WebSphere Application Server on the workstation.
Syntax
startappserver[domain!]workstation [;wait]
Arguments
domain Specifies the name of the domain of the workstation. Because workstations have unique names, the domain is not needed when starting the WebSphere Application Server on a specific workstation. Wildcard characters are permitted. If domain is omitted, and workstation contains wildcard characters, the default domain is the one in which conman is running. Specifies the name of the workstation where you want to start the monitoring engine. Wildcard characters are permitted. If no domain and workstations are specified, the action is on the local workstation. Waits until WebSphere Application Server has started before prompting for another command.
wait
Comments
Permission to start actions on cpu objects is required in the security file to be enabled to run this command. WebSphere Application Server can also be started with the StartUp utility command.
345
starteventprocessor
| | | | | | | | | | | | | |
starteventprocessor
Starts the event processing server on the master domain manager, backup master, or on a workstation installed as a backup master that functions as a plain fault-tolerant agent.
Syntax
starteventprocessor [domain!]workstation
Arguments
domain workstation Specifies the name of the domain of the workstation. Specifies the name of the workstation where you want to start the event processing server. Wildcard characters are not permitted.
Comments
You can omit the workstation name if you run the command locally. Permission to start actions on cpu objects is required in the security file to be enabled to run this command.
346
startmon
| | | | | | | | | | | | | | | | | | | | workstation noask
startmon
Starts the monman process that turns on the event monitoring engine on the workstation.
Syntax
startmon [domain!]workstation [;noask]
Arguments
domain Specifies the name of the domain of the workstation. Because workstations have unique names, the domain is not needed when starting the monitoring engine on a specific workstation. Wildcard characters are permitted. If domain is omitted, and workstation contains wildcard characters, the default domain is the one in which conman is running. Specifies the name of the workstation where you want to start the monitoring engine. Wildcard characters are permitted. Specifies not to prompt for confirmation before taking action on each qualifying workstation.
Comments
Permission to start actions on cpu objects is required in the security file to be enabled to run this command.
347
status
status
Displays the conman banner and the Tivoli Workload Scheduler production status.
Syntax
status
Results
Following the word schedule on the second line of output, the production plan (Symphony file) mode is shown in parentheses. The Def or Exp information can appear. Def means that the production plan is in non-expanded mode, and Exp means it is in expanded mode. The mode of the production plan is determined by the setting of the global option expanded version. With Tivoli Workload Scheduler, Version 8.2, databases and plans are always expanded, but this information appears for backward compatibility with previous versions.
Examples
The following example displays the status of the current production plan.
%status TWS for UNIX/CONMAN 8.4 (1.36.2.22) Licensed Materials Property of IBM 5698-WKB (C) Copyright IBM Corp 1998, 2007 US Government User Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Job stream (Exp) 11/26/05 (#34) on site3. Batchman LIVES. Limit:19, Fence:0, Audit Level:0
348
stop
stop
Stops Tivoli Workload Scheduler production processes. To stop the netman process, use the shutdown command. You must have stop access to the workstation.
Syntax
stop [domain!]workstation [;wait] [;noask]
Arguments
domain Specifies the name of the domain in which workstations are stopped. Because workstations have unique names, the domain is not needed when stopping a specific workstation. Wildcard characters are permitted. This argument is useful when stopping more than one workstation in a domain. For example, to stop all the agents in domain stlouis, use the following command:
stop stlouis!@
If domain is omitted, and workstation contains wildcard characters, the default domain is the one in which conman is running. workstation wait noask Specifies the name of the workstation to be stopped. Wildcard characters are permitted. Specifies not to accept another command until all processes have stopped. Specifies not to prompt for confirmation before taking action on each qualifying workstation.
Comments
If the stop command cannot be applied to a distant workstation (for example, if the TCP/IP path is not available), the command is stored locally in a pobox file, and is sent to the workstation when it becomes linked. Assuming the user has stop access to the workstations being stopped, the following rules apply: v A user running conman on the master domain manager can stop any workstation in the network. v A user running conman on a domain manager other than the master can stop any workstation in that domain and subordinate domains. The user cannot stop workstations in peer domains. v A user running conman on an agent can stop any workstation in the local domain. When you issue a stop @ command on a domain manager, a local conman stop command runs on the remote CPUs. The command starts running on the lowest stations in the network hierarchy, then finally runs on the domain manager. However, the Symphony file is not updated before the CPUs go down. Therefore, if you issue a conman sc@!@ command from any CPU, the resulting information might be an up to date picture of the states of the CPUs, even of the domain manager.
349
stop
Examples
Figure 12 and Table 47 below show the workstations stopped by different stop commands run by users in different locations in the network. DMn are domain managers and Ann are agents.
A11 DM1 A12 Domain1 User1
DM4 Domain4 A41 A42
Figure 12. Stopped workstations in network Table 47. Stopped workstations Command stop @!@ Stopped by: User1 Stopped by User2 Stopped by User3 DM2 A21 A22
All workstations are DM2 stopped A21 A22 DM4 A41 A42 DM1 A11 A12 DM3 A31 A32 DM4 A41 A42 DM2 A42 A31 DM2 A21 A22 Not allowed
stop @
DM2 A21 A22 Not allowed
stop DOMAIN3!@
stop DOMAIN4!@
DM4 A41 A42 DM2 A42 Not allowed
Not allowed
stop DM2 stop A42 stop A31
DM2 Not allowed Not allowed
350
stop ;progressive
stop ;progressive
Stops Tivoli Workload Scheduler production processes hierarchically when you have defined at least one workstation as BEHINDFIREWALL in an Tivoli Workload Scheduler network. Similar to the stop @!@ command, but more effective in improving plan performance. The command does not run from the domain in which the command was initially issued for each subordinate domain, but runs at each hierarchical level. You must have stop access to the workstation.
Syntax
stop ;progressive
Comments
When you issue the command on a domain manager, all workstations in that domain are stopped and then the domain manager itself is stopped and the command continues to run on any subordinate domains. The command continues to run in this hierarchical manner, the domain manager stops workstations in the same domain, stops itself, and then continues to run on subordinate domains.
Examples
Figure 12 on page 350 and Table 48 show the workstations stopped by issuing the stop ;progressive command on DM2.
Table 48. Stopped workstations with stop ;progressive Command stop ;progressive Stopped by DM2 A21 A22 DM2 Stopped by DM4 A41 A42 DM4
351
stopappserver
| | | | | | | | | | | | | | | | | | | | | workstation
stopappserver
Stops the embedded WebSphere Application Server on the workstation.
Syntax
stopappserver[domain!]workstation [;wait]
Arguments
domain Specifies the name of the domain of the workstation. Because workstations have unique names, the domain is not needed when stopping the WebSphere Application Server on a specific workstation. Wildcard characters are permitted. If domain is omitted, and workstation contains wildcard characters, the default domain is the one in which conman is running. Specifies the name of the workstation where you want to stop the monitoring engine. Wildcard characters are permitted. If no domain and workstations are specified, the action is on the local workstation. Waits until WebSphere Application Server has stopped before prompting for another command.
wait
Comments
Permission to stop actions on cpu objects is required in the security file to be enabled to run this command.
352
stopeventprocessor
| | | | | | | | | | | | | | | |
stopeventprocessor
Stops the event processing server.
Syntax
stopeventprocessor [domain!][workstation]
Arguments
domain workstation Specifies the name of the domain of the workstation. Specifies the name of the master domain manager, backup master, or workstation installed as a backup master that functions as a plain fault-tolerant agent where you want to stop the event processing server. Wildcard characters are not permitted. You can omit the workstation name if you run the command locally.
Comments
This command cannot be issued in an asynchronous way. Permission to stop actions on cpu objects is required in the security file to be enabled to run this command.
353
stopmon
| | | | | | | | | | | | | | | | | | | | | | | | | | workstation wait noask
stopmon
Stops the event monitoring engine on the workstation.
Syntax
stopmon [domain!]workstation [;wait] [;noask]
Arguments
domain Specifies the name of the domain of the workstation. Because workstations have unique names, the domain is not needed when stopping the monitoring engine on a specific workstation. Wildcard characters are permitted. If domain is omitted, and workstation contains wildcard characters, the default domain is the one in which conman is running. Specifies the name of the workstation where you want to stop the monitoring engine. Wildcard characters are permitted. Specifies not to accept another command until the monitoring engine has stopped. Specifies not to prompt for confirmation before taking action on each qualifying workstation.
Comments
The monitoring engine is restarted automatically when the next production plan is activated (on Windows also when Tivoli Workload Scheduler is restarted) unless you disable the autostart monman local option. The command is asynchronous, unless you specify the wait keyword. Permission to stop actions on cpu objects is required in the security file to be enabled to run this command.
354
submit docommand
submit docommand
Submits a command to be launched as a job. You must have submit access to the job. To include needs and prompt dependencies, you must have use access to the resources and global prompts. If you submit the job from a workstation other than the master domain manager you must be connect as a user that is: v defined in the user registry used by WebSphere Application Server for authentication v authorized to perform submit commands in security file stored on the master domain manager.
Syntax
sbd+ [workstation#]cmd [;alias[=name]] [;into=[workstation#] {jobstream_id;schedid |jobstreamname (hhmm[ date])}] [;joboption[;...]]
Arguments
workstation Specifies the name of the workstation on which the job will be launched. Wildcard characters are permitted, in which case, the job is launched on all qualifying workstations. The default is the workstation on which conman is running. You cannot specify a domain or workstation class. Note: Because of a limitation in the way Windows manages the equal (=) sign in the shell environment, you must mask the equal (=) sign as follows \=\ when submitting Windows commands using submit docommand. For example, to set the local variable var1 to hello you must issue the following command:
%sbd "set var1\"=\"hello"
cmd
Specifies a valid system command of up to 255 characters. The entire command must be enclosed in quotes (). The command is treated as a job, and all job rules apply. Note: The local parameters specified in the this field are resolved on the workstation from where the command is submitted as a job using conman sbd.
alias=name Specifies a unique name to be assigned to the job. If you enter the alias keyword without specifying a name, a name is constructed using up to the first six alphanumeric characters (in upper case) of the command, depending on the number of characters in the command, followed by a ten digit random number. If there are blanks in the command, the name is constructed using up to the first six alphanumeric characters before the blank. For example, if the command is rm apfile, the generated name will be similar to RM0123456789. If the command is longer than six alphanumeric characters such as, wlsinst, the generated name will be wlsins0396578515. If you do not include alias the first time you submit the command, a job name is constructed using up to 255 characters of the command name. If
355
submit docommand
you submit a command a second time from the same workstation, the alias keyword is mandatory and must be unique for each command submission. into=jobstream_instance Identifies the job stream instance into which the job will be placed for launching. Select the job stream instance as follows: [workstation#]jobstreamname[hhmm[ date]] or [workstation#]jobstream_id ;schedid If you do not specify a workstation, the default is the workstation on which conman is running. If into is not used, the job is added to a job stream named JOBS. joboption Specify one of the following: at=hhmm [timezone|tz tzname] [+n days | mm/dd[/yy]] | [absolute | abs] confirmed deadline=time [timezone|tz tzname][+n day[s | mm/dd[/yy]] every=rate follows=[netagent::][workstation#]{jobstreamname[hhmm [mm/dd[/yy]]][.job | @] | jobstream_id.job;schedid}| job[;nocheck][;wait=time][,...] Note: The ;nocheck argument is not supported in internetwork dependencies. interactive | Note: This keyword can be used in Windows environments only. logon=user. needs=[num] [workstation#]resource[,...] opens=[workstation#]filename[(qualifier)][,...] Note: The local parameters specified in the opens clause are resolved on the workstation from where the command is submitted as a job using conman sbd. priority[=pri | hi | go] prompt=[: | !]text | promptname[,...] rccondsuccSuccess Condition recovery=stop | continue | rerun after [workstation#]jobname abendprompt text until time [timezone|tz tzname][+n day[s] | [absolute | abs]] [;onuntil action] The default value for joboption is the user on the workstation from which the command is being run.
356
submit docommand
Comments
Jobs submitted in production from the conman command line are not included in the preproduction plan and so they cannot be taken into account when identifying external follows dependencies predecessors. If you do not specify a workstation with follows, needs, or opens, the default is the workstation of the job.
Examples
To submit an rm command into the job stream JOBS with a follows dependency, run the following command:
submit docommand="rm apfile";follows sked3
To submit a sort command with the alias sortit and place the job in the job stream reports with an at time of 5:30 p.m., run the following command:
sbd "sort < file1 > file2";alias=sortit;into=reports;at=1730
To submit chmod commands on all workstations with names beginning with site, run the following command:
sbd site@#"chmod 444 file2";alias
357
submit file
submit file
Submits a file to be launched as a job. You must have submit access to the job. To include needs and prompt dependencies, you must have use access to the resources and global prompts. If you submit the job from a workstation other than the master domain manager you must be connect as a user that is: v defined in the user registry used by WebSphere Application Server for authentication v authorized to perform submit commands in security file stored on the master domain manager.
Syntax
| | | | | sbf filename [;alias[=name]] [;into=[workstation#]{jobstream_id ;schedid |jobstreamname (hhmm[ date])}] [;joboption[;...]] [;noask]
Arguments
filename Specifies the name of the file, up to 255 characters. Wildcard characters are permitted. The name must be enclosed in quotes () if it contains characters other than alphanumeric characters, dashes (-), slashes (/), and underscores (_). See the examples. Note: The local parameters specified within this file are resolved on the workstation from where the file is submitted as a job using conman sbf. alias=name Specifies a unique name to be assigned to the job. If you enter the alias keyword without specifying a name, a name is constructed using up to the first six alphanumeric characters (in upper case) of the file name, depending on the number of characters in the file name, followed by a ten digit random number. For example, if the file name is jclttx5, the generated name will be similar to JCLTTX0123456789. If you do not include alias, a filename is constructed using up to 255 alphanumeric characters of the files base name, in upper case. In either of the above cases, if the file name does not start with a letter, you are prompted to use alias= name. If you submit a file a second time from the same workstation, the alias keyword is mandatory and must be unique for each file submission. into=jobstream_instance Identifies the job stream instance into which the job will be placed for launching. Select the job stream instance as follows: [workstation#]jobstreamname[hhmm[ date]] or [workstation#]jobstream_id ;schedid If you do not specify a workstation, the default is the workstation on which conman is running. If into is not used, the job is added to a job stream named JOBS.
358
submit file
joboption Specify one of the following: at=hhmm [timezone|tz tzname] [+n days | mm/dd[/yy]] | [absolute | abs] confirmed deadline=time[timezone | tz tzname][+n days | mm/dd[/yy]] every=rate follows=[netagent::][workstation#]{jobstreamname(hhmm [mm/dd[/yy]])[.job | @] | jobstream_id.job;schedid}| job[;nocheck][;wait=time][,...] Note: The ;nocheck argument is not supported in internetwork dependencies. interactive | Note: This keyword can be used in Windows environments only. logon=user needs=[num] [workstation#]resource[,...] opens=[workstation#]filename[(qualifier)][,...] Note: The local parameters specified in the opens clause are resolved on the workstation from where the file is submitted as a job using conman sbf. priority[=pri | hi | go] prompt=[: | !]text | promptname[,...] rccondsuccSuccess Condition recovery=stop | continue | rerun after [workstation#]jobname abendprompt text until time [timezone|tz tzname][+n day[s] | [absolute | abs]] [;onuntil action] noask Specifies not to prompt for confirmation before taking action against each qualifying file.
Comments
Jobs submitted in production from the conman command line are not included in the preproduction plan and so they cannot be taken into account when identifying external follows dependencies predecessors. If you do not specify a workstation with follows, needs, or opens, the default is the workstation on which conman is running.
Examples
To submit a file into the job stream jobs (the job name is myjcl), run the following command:
submit file=d:\jobs\lib\daily\myjcl
where the ;into sequence was omitted.
359
submit file
To submit a file, with a job name of misjob4, into the job stream missked, run the following command:
sbf /usr/lib/mis/jcl4;alias=misjob4;into=missked ;needs=2 slots
The job needs two units of the slots resource. To submit all files that have names beginning with back into the job stream bkup, run the following command:
sbf "/usr/lib/backup/back@";into=bkup
| | | | | | | | | | |
To submit file tws_env.cmd, whose path contains a blank, on a Windows workstation run: v In interactive mode:
sbf "\"C:\Program Files\IBM\TWS\lucaMDM\tws_env.cmd\"";alias=MYJOB
Being in Windows, the double quotes (") must be escaped by the "\ character sequence. v In command line mode:
conman sbf "\"\\\"C:\Program Files\IBM\TWS\lucaMDM\tws_env.cmd\\\"\"";alias=MYJOB
Being in Windows, and running the command externally from the conman environment, the escape sequence becomes longer. where "\" is the escape character for the blank in the file path.
360
submit job
submit job
Submits a job to be launched. You must have submit access to the job. To include needs and prompt dependencies, you must have use access to the resources and global prompts. If you submit the job from a workstation other than the master domain manager you must be connect as a user that is: v defined in the user registry used by WebSphere Application Server for authentication v authorized to perform submit commands in security file stored on the master domain manager.
Syntax
sbj [workstation#]jobname [;alias[=name]] [;into=[workstation#]{jobstream_id ;schedid | jobstreamname(hhmm[ date])}] [;joboption[;...]] [;noask]
Arguments
workstation Specifies the name of the workstation on which the job will be launched. Wildcard characters are permitted, in which case, the job is launched on all qualifying workstations. The default is the workstation on which conman is running. You cannot specify a domain or workstation class. jobname Specifies the name of the job. Wildcard characters are permitted, in which case, all qualifying jobs are submitted. If the job is already in the production plan, and is being submitted into the same job stream, you must use the alias argument to assign a unique name. alias=name Specifies a unique name to be assigned to the job in place of jobname. If you enter the alias keyword without specifying a name, a name is constructed using the first two alphanumeric characters of jobname followed by a six digit random number. The name is always upshifted. For example, if jobname is jcrttx5, the generated name will be similar to JC123456. into=jobstream_instance Identifies the job stream instance into which the job will be placed for launching. Select the job stream instance as follows: [workstation#]jobstreamname[hhmm[ date]] or [workstation#]jobstream_id ;schedid If you do not specify a workstation, the default is the workstation on which conman is running. If into is not used, the job is added to a job stream named JOBS. joboption Specify one of the following: at=hhmm [timezone|tz tzname] [+n days | mm/dd[/yy]] | [absolute | abs] confirmed
361
submit job
deadline=time[timezone | tz tzname][+n days | mm/dd[/yy]] every=rate follows=[netagent::][workstation#]{jobstreamname(hhmm [mm/dd[/yy]]) [.job | @] | jobstream_id.job;schedid}| job[;nocheck][;wait=time][,...] Note: The ;nocheck argument is not supported in internetwork dependencies. needs=[num] [workstation#]resource[,...] opens=[workstation#]filename[(qualifier)][,...] Note: The local parameters specified in the opens clause are resolved on the workstation from where the job is submitted using conman sbj. priority[=pri | hi | go] prompt=[: | !]text | promptname[,...] rccondsuccSuccess Condition recovery=stop | continue | rerun after [workstation#]jobname abendprompt text until time [timezone|tz tzname][+n day[s] | [absolute | abs]] [;onuntil action] noask Specifies not to prompt for confirmation before taking action against each qualifying job. This option can be used only with ;schedid.
Comments
Jobs submitted in production from the conman command line are not included in the preproduction plan and so they cannot be taken into account when identifying external follows dependencies predecessors. If you do not specify a workstation with follows, needs, or opens, the default is the workstation of the job.
Examples
To submit the test jobs into the job stream JOBS, run the following command:
sbj test
To submit a job with an alias of rptx4 and place the job in the job stream reports with an at time of 5:30 p.m., run the following command:
sbj rjob4;alias=rptx4;into=reports;at=1730
To submit job txjob3 on all workstations whose names begin with site, run the following command:
sbj site@#txjob3;alias
See also
For the equivalent Job Scheduling Console task, see Submitting Jobs in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
362
submit sched
submit sched
Submits a job stream to be launched. You must have submit access to the job stream. To include needs and prompt dependencies, you must have use access to the resources and global prompts. If you submit the job stream from a workstation other than the master domain manager you must be connect as a user that is: v defined in the user registry used by WebSphere Application Server for authentication v authorized to perform submit commands in security file stored on the master domain manager. The submit schedule command uses the credentials set in the useropts file belonging to the TWS_user who installed that workstation.
Syntax
sbs [workstation#]jstreamname [;alias[=name]] [;jstreamoption[;...]] [;noask]
Arguments
workstation Specifies the name of the workstation on which the job stream will be launched. Wildcard characters are permitted, in which case, the job stream is launched on all qualifying workstations. The default is the workstation on which conman is running. You cannot specify a domain or workstation class. jstreamname Specifies the name of the job stream. Wildcard characters are permitted, in which case, all qualifying job streams are submitted. If the job stream is already in the production plan, you must use the alias argument to assign a unique name. alias=name Specifies a unique name to be assigned to the job stream in place of jstreamname, if set this value corresponds also to the jobstream_id. If you enter the alias keyword without specifying a name, a name is constructed using the first alphanumeric characters of jstreamname followed by a six digit random number. The name is always upshifted. For example, if jstreamname is sttrom, the generated name will be similar to ST123456. jstreamoption Enter one of the following: [at=hhmm [timezone|tz tzname] [+n days | date] | [absolute | abs]] | [schedtime=[hhmm [date] | [+n days]] where: schedtime Represents the day and time when the job stream is positioned in the plan. If, by then, it is free from dependencies and it has no at time restriction is defined, the job streams is launched. The value assigned to schedtime does not represent a dependency for the job
363
submit sched
stream. Its value is then displayed in the SchedTime columns in the output of the show commands. If an at restriction is defined then the value assigned to schedtime is overwritten by the at value. When the job stream actually starts then the value assigned to schedtime is overwritten by the actual start time of the job stream. The format used for date depends on the value assigned to the date format variable specified in the localopts file. carryforward deadline=time[timezone | tz tzname][+n days | date] follows=[netagent::][workstation#]{jobstreamname[hhmm [mm/dd[/yy]]][.job | @] | jobstream_id.job;schedid}| job[;nocheck][;wait=time][,...] The matching criteria used when submitting job streams in production is different from the way follows dependencies are resolved in the preproduction plan. When a job stream, for example JS_A, containing a follows dependency from a job or a job stream, for example JS_B, is submitted from the conman command line program the predecessor instance of JS_B is defined following this criteria: 1. The closest instance of JS_B preceding JS_A. 2. If no preceding instance of JS_B exists then the predecessor instance is the closest instance of JS_B following JS_A. 3. Otherwise an error is displayed and the command fails if the keyword ;nocheck is not used. The predecessor job stream instance is searched among the instances added to the production plan when JnextPlan was run, and the instances submitted in production, using sbs, including those submitted with an alias. Note: The ;nocheck argument is not supported in internetwork dependencies. limit=joblimit needs=[num] [workstation#]resource[,...] opens=[workstation#]filename[(qualifier)][,...] Note: The local parameters specified in the opens clause are resolved on the workstation from where the job stream is submitted using conman sbs. priority[=pri | hi | go] prompt=[: | !]text | promptname[,...] until time [timezone|tz tzname][+n day[s] | [absolute | abs]] [;onuntil action] noask Specifies not to prompt for confirmation before taking action against each qualifying job stream. This option can be used only with ;schedid.
Comments
Job streams submitted in production from the conman command line are not included in the preproduction plan and so they cannot be taken into account when identifying external follows dependencies predecessors.
364
submit sched
If you do not specify a workstation with follows, needs, or opens, the default is the workstation of the job stream.
Examples
To submit the adhoc job stream on workstation site1 and flags it as a carryforward job stream, run the following command:
submit sched=site1#adhoc;carryforward
To submit job stream fox4 with a job limit of 2, a priority of 23, and an until time of midnight, run the following command:
sbs fox4;limit=2;pri=23;until=0000
To submit job stream sched3 on all workstations with names that start with site, run the following command:
sbs site@#sched3
See also
For the equivalent Job Scheduling Console task, see Managing distributed plans in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
365
| | | | | | | | | | | | | | | | | | | |
Switches the event processing server from the master domain manager to the backup master or vice versa. Note that you can run the event processing server also on a workstation installed as a backup master that runs as a plain fault-tolerant agent.
Syntax
switcheventprocessor workstation
Arguments
workstation Specifies the name of the master domain manager or of the backup master where you want to switch the event processing server. Wildcard characters are not permitted.
Comments
In case of backup masters the workstation must have the full-status attribute set to on. Permission to start and stop actions on cpu objects is required in the security file to be enabled to run this command. The correlation state of pending correlation rule instances is lost whenever the server is switched off or migrated. If caching of received events is enabled in the configuration file of the EIF listener, the cached events are lost after the event processing is switched.
366
switchmgr
switchmgr
Switches domain management from the current domain manager to a backup domain manager. You must have start and stop access to the backup domain manager. The switchmgr command must only be used as part of specific procedures for switching domain management capabilities from a domain manager to its backup domain manager either permanently or temporarily. For information about these procedures, refer to the IBM Tivoli Workload Scheduler: Administration and Troubleshooting Guide.
Syntax
switchmgr domain;newmgr
Arguments
domain newmgr Specifies the domain in which you want to switch managers. Specifies the name of the new domain manager. This must be a workstation in the same domain, and should be defined beforehand as a fault-tolerant agent with Resolve Dependencies and Full Status enabled.
Comments
The command stops a specified workstation and restarts it as the domain manager. All domain member workstations are informed of the switch, and the old domain manager is converted to a fault-tolerant agent in the domain. The next time JnextPlan is run on the old domain manager, the domain acts as though another switchmgr command had been run and the old domain manager automatically resumes domain management responsibilities.
Examples
To switch the domain manager to workstation orca in the masterdm domain, run the following command:
switchmgr masterdm,orca
To switch the domain manager to workstation ruby in the bldg2 domain, run the following command:
switchmgr bldg2,ruby
367
system
system
Runs a system command.
Syntax
[: | !] sys-command
Arguments
sys-command Specifies any valid system command. The prefix (: or !) is required only when a command name has the same spelling as a conman command.
Examples
To run a ps command in UNIX, run the following command:
ps -ef
To run a dir command in Windows, run the following command:

dir \bin
368
tellop
tellop
Sends a message to the Tivoli Workload Scheduler console.
Syntax
to [text]
Arguments
text Specifies the text of the message. The message can contain up to 900 characters.
Comments
If tellop is issued on the master domain manager, the message is sent to all linked workstations. If issued on a domain manager, the message is sent to all of the linked agents in its domain and subordinate domains. If issued on a workstation other than a domain manager, the message is sent only to its domain manager if it is linked. The message is displayed only if the console message level is greater than zero. See console on page 279. If tellop is entered alone, it prompts for the message text. At the prompt, type each line and press the Return key. At the end of the message, type two slashes (//) or a period (.), and press the Return key. You can use the new line sequence (\n) to format messages. Typing Control+c at any time will exit the tellop command without sending the message.
Examples
To send a message, run the following command:
tellop TWS will be stopped at\n4:30 for 15 minutes.
To prompt for text before sending a message, run the following command:
to TELLOP>********************************* TELLOP>* TWS will be stopped at * TELLOP>* 4:30 for 15 minutes. * TELLOP>********************************* TELLOP>//
369
unlink
unlink
Closes communication links between workstations. You must have unlink access to the target workstation.
Syntax
unlink [domain!]workstation [;noask]
Arguments
domain Specifies the name of the domain in which to close links. It is not necessary to specify the domain name of a workstation in the master domain. Wildcard characters are permitted. Note: You must always specify the domain name when unlinking a workstation not in the master domain. This argument is useful when unlinking more than one workstation in a domain. For example, to unlink all the agents in domain stlouis, use the following command:
unlink stlouis!@
If you do not specify domain, and workstation includes wildcard characters, the default domain is the one in which conman is running. workstation noask Specifies the name of the workstation to be unlinked. Wildcard characters are permitted. Specifies not to prompt for confirmation before taking action on each qualifying workstation.
Comments
Assuming that a user has unlink access to the workstations being unlinked, the following rules apply: v A user running conman on the master domain manager can unlink any workstation in the network. v A user running conman on a domain manager other than the master can unlink any workstation in its own domain and subordinate domains. The user cannot unlink workstations in peer domains. v A user running conman on an agent can unlink any workstation in its local domain provided that the workstation is either a domain manager or host. A peer agent in the same domain cannot be unlinked. For additional information see link on page 295.
Examples
Figure 13 on page 371 and Table 49 on page 371 show the links closed by unlink commands run by users in various locations in the network. DMn are domain managers and Ann are agents.
370
unlink
A11 DM1
A12
Domain1 User1
DM4 Domain4 A41 A42
Figure 13. Unlinked network workstations Table 49. Unlinked workstations Command unlink@!@ Closed by User1 Closed by User2 Closed by User3 DM2-A21
All links are closed DM1-DM2 DM2-A21 DM2-A22 DM2-DM4 DM4-A41 DM4-A42 DM1-A11 DM1-A12 DM1-DM2 DM1-DM3 DM3-A31 DM3-A32 DM4-A41 DM4-A42 DM1-DM2 DM4-A42 DM3-A31 DM1-DM2 DM2-A21 DM2-A22 DM2-DM4 Not allowed DM4-A41 DM4-A42 Not applicable DM4-A42 Not allowed
unlink @
DM2-A21
unlink DOMAIN3!@ unlink DOMAIN4!@ unlink DM2 unlink A42 unlink A31
Not allowed Not allowed DM2-A21 Not allowed Not allowed
371
version
version
| | Displays the conman program banner, inclusive of the version up to the installed fix pack level.
Syntax
version
Examples
To display the conman program banner, run the following command:
%version
The output is similar to this:

TWS for UNIX/CONMAN 8.4 (1.36.2.22) Licensed Materials Property of IBM 5698-WKB (C) Copyright IBM Corp 1998, 2007 US Government User Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Job stream (Exp) 11/26/06 (#34) on site3. Batchman LIVES.Limit:19,Fence:0,Audit Level:0
372

This chapter describes Tivoli Workload Scheduler utility commands. These commands, with the exception of StartUp and version, are installed in the TWS_home/bin directory. StartUp is installed in the TWS_home directory and version is installed in the TWS_home/version directory. You run utility commands from the operating system command prompt. | | | | | | | | | |
What is new in using utility commands

This section gives a quick reference to the enhancements in using the utility commands introduced with Tivoli Workload Scheduler version 8.4. The following utility commands for event rule management have been added : v The evtdef command can be used to change custom event definitions using a supplied generic event provider. v The sendevent command can be used for sending custom events defined with the evtdef command to the currently active event processor server also from non-Tivoli Workload Scheduler systems. See the following sections for additional details.
Table 50 contains the list of the utility commands, and for each command, its description and the operating systems it supports.
Table 50. List of utility commands Command at batch cpuinfo datecalc delete Description Submits a job to be run at a specific time. Submits a job to be run as soon as possible. Returns information from a workstation definition. Converts date and time to a desired format Removes script files and standard list files by name. Imports/exports custom events definitions. Defines the maximum size of event message files. Returns information about a job. Returns the pathnames of standard list files. Lists processes. This command is not supported. Kills processes. This command is not supported. Operating system UNIX UNIX UNIX, Windows UNIX, Windows UNIX, Windows UNIX, Windows UNIX, Windows UNIX, Windows UNIX, Windows Windows Windows
| |
evtdef evtsize jobinfo jobstdl listproc killproc
373
Table 50. List of utility commands (continued) Command maestro makecal metronome.pl Description Returns the Tivoli Workload Scheduler home directory. Creates custom calendars. Operating system UNIX, Windows UNIX, Windows
Generates an HTML report containing a snapshot of UNIX, Tivoli Workload Scheduler. Makes a backup copy of the Windows Tivoli Workload Scheduler database. Displays the contents of standard list files. Displays, changes, and adds parameters. Releases units of a resource. Removes standard list files based on age. Sends generic events to the currently active event processor server. Displays information about executing jobs. Starts the netman process and, optionally, WebSphere Application Server. Displays version information. UNIX, Windows UNIX, Windows UNIX, Windows UNIX, Windows UNIX, Windows UNIX UNIX, Windows UNIX
morestdl parms release rmstdlist sendevent showexec StartUp version
374
at and batch
at and batch
Submit ad hoc commands and jobs to be launched by Tivoli Workload Scheduler. These command runs on UNIX only. See at.allow and at.deny below for information about the availability to users.
Syntax
at -v | -u at {-s jstream | -q queue} time-spec batch -v | -u batch [-s jstream]
Arguments
-v -u Displays the command version and exits. Displays command usage information and exits.
-s jstream Specifies the jobstream_id of the job stream instance into which the job is submitted. If a job stream instance with that jobstream_id does not exist, it is created a new job stream having jstream both as alias and as jobstream_id. The name must start with a letter, and can contain alphanumeric characters and dashes. It can contain up to 16 characters. If the -s and -q arguments are omitted, a job stream name is selected based on the value of the environment variable ATSCRIPT. If ATSCRIPT contains the word maestro, the job stream alias will be the first eight characters of the users group name. If ATSCRIPT is not set, or is set to a value other than maestro, the job stream alias will be at (for jobs submitted with at), or batch (for jobs submitted with batch). See Other considerations on page 376 for more information about job streams. The following keywords apply only to at jobs: -qqueue Specifies to submit the job into a job stream with the name queue, which can be a single letter (a through z). See Other considerations on page 376 for more information about job streams. time-spec Specifies the time at which the job will be launched. The syntax is the same as that used with the UNIX at command.
Comments
After entering at or batch, enter the commands that constitute the job. End each line of input by pressing the Return key. The entire sequence is ended with end-of-file (usually Control+d), or by entering a line with a period (.). Alternatively, use an angle bracket (<) to read commands from a file. See Examples on page 377.
375
at and batch
Information about at and batch jobs is sent to the master domain manager, where the jobs are added to job streams in the production plan, Symphony file. The jobs are launched based on the dependencies included in the job streams. The UNIX shell used for jobs submitted with the Tivoli Workload Scheduler at and batch commands is determined by the SHELL_TYPE variable in the jobmanrc configuration script. Do not use the C shell. For more information, see the IBM Tivoli Workload Scheduler Planning and Installation Guide. Once submitted, jobs are launched in the same way as other scheduled jobs. Each job runs in the submitting users environment. To ensure that the environment is complete, set commands are inserted into the script to match the variable settings in the users environment. Replacing the UNIX commands: The standard UNIX at and batch commands can be replaced by Tivoli Workload Scheduler commands. The following commands show how to replace the UNIX at and batch commands:
$ $ $ $ mv mv ln ln /usr/bin/at /usr/bin/uat /usr/bin/batch /usr/bin/ubatch -s TWShome/bin/at /usr/bin/at -s TWShome/bin/batch /usr/bin/batch
The at.allow and at.deny files: The at and batch commands use the files /usr/lib/cron/at.allow and /usr/lib/cron/at.deny to restrict usage. If the at.allow file exists, only users listed in the file are allowed to use at and batch. If the file does not exist, at.deny is checked to see if the user is explicitly denied permission. If neither of the files exists, only the root user is permitted to use the commands. Script files: The commands entered with at or batch are stored in script files. The file are created by Tivoli Workload Scheduler using the following naming convention: TWS_home/atjobs/epoch.sss where: epoch sss The number of seconds since 00:00, 1/1/70. The first three characters of the job stream name.
Note: Tivoli Workload Scheduler removes script files for jobs that are not carried forward. However, you should monitor the disk space in the atjobs directory and remove older files if necessary. Job names: All at and batch jobs are given unique names by Tivoli Workload Scheduler when they are submitted. The names consist of the users process ID (PID) preceded by the users name truncated so as not to exceed eight characters. The resulting name is upshifted. Other considerations: v The job streams into which at and batch jobs are submitted should be created beforehand with composer. The job streams can contain dependencies that determine when the jobs will be launched. At a minimum, the job streams should contain the carryforward keyword. This ensures that jobs that do not complete, or are not launched, while the current production plan is in process are carried forward to the next production plan.
376
at and batch
v Include the expression on everyday to have the job streams selected every day. v Use the limit keyword to limit the number of submitted jobs that can be run concurrently. v Use the priority keyword to set the priority of submitted jobs relative to other jobs. If the time value is less than the current time, the value is regarded as for the following day. If the time value is greater than the current time, the value is regarded as for the current day.
Examples
To submit a job into job stream with jobstream_id sched8 to be launched as soon as possible, run the following command:
batch -s sched8 command <Return> ... <Control d>
To submit a job to be launched two hours from the time when the command was entered, run the following command:
at now + 2 hours command <Return> ... <Control d>
If the variable ATSCRIPT is null, the job is submitted into a job stream having the same name as the users group. Otherwise, it is submitted into a job stream named at. To submit a job into a job stream instance with jobstream_id sked-mis to be launched at 5:30 p.m., run the following command:
at -s sked-mis 17h30 command <Return> ... <Control d>
The following command is the same as the previous command, except that the jobs commands are read from a file:
at -s sked-mis 17h30 < ./myjob
The fact that the commands are read from a file does not change the way they are processed. That is, the commands are copied from the ./myjob file into a script file.
377
cpuinfo
cpuinfo
Returns information from a workstation definition.
Syntax
cpuinfo -V | -U cpuinfo workstation [infotype] [...]
Arguments
-V -U workstation The name of the workstation. infotype The type of information to display. Specify one or more of the following: os_type Returns the value of the os field: UNIX, WNT, and OTHER. node port Returns the value of the node field. Returns the value of the port field. Displays the command version and exits. Displays command usage information and exits.
autolink Returns the value of the autolink field: ON or OFF. fullstatus Returns the value of the fullstatus field: ON or OFF. host method Returns the value of the access field. server Returns the value of the server field. type Returns the type of workstation: MASTER, MANAGER, FTA, S-AGENT, and X-AGENT. Returns the value of the host field.
time_zone Returns the time zone of the workstation. For an extended agent, the field is blank. version Returns the Tivoli Workload Scheduler version that is running on the workstation. For an extended agent, the field is blank. info Returns the operating system version and workstation model. For an extended agent, the field is blank.
Comments
The values are returned, one on each line, in the same order that the arguments were entered on the command line. If no arguments are specified, all applicable information is returned with labels, one on each line.
Examples
The examples below are based on the following workstation definition:
378
cpuinfo
Workstation Name Type Domain Updated On Locked By ---------------- ------- ---------------- ---------- -----------------oak_wks manager MASTERDM 03/04/2006 CPUNAME oak_wks DESCRIPTION "MASTER CPU" OS UNIX NODE oak.tivoli.com TCPADDR 51099 DOMAIN MASTERDM FOR MAESTRO TYPE MANAGER AUTOLINK ON BEHINDFIREWALL OFF FULLSTATUS ON END
To print the node and port for workstation oak, run the following command:
>cpuinfo oak_wks node port oak.tivoli.com 51099
To print all information for workstation oak, run the following command:
>cpuinfo oak_wks OS TYPE:UNIX NODE:oak.tivoli.com PORT:51099 SSLPORT: 0 SEC_LEVEL: NONE AUTOLINK:ON FULLSTATUS:ON RESOLVEDEP: ON BEHINDFIREWALL: OFF HOST:oak_wks DOMAIN: MASTERDM METHID: SERVER: TYPE: MASTER TIME ZONE:Europe/Rome VERSION:8.3 INFO: Linux 2.4.21-4.ELsmp #1 SMP Fri O i686
379
datecalc
datecalc
Resolves date expressions and returns dates in the format you choose.
Syntax
datecalc -V | -U datecalc base-date [offset] [pic format] [freedays Calendar_Name [-sa] [-su]] datecalc -t time [base-date] [offset] [pic format] datecalc yyyymmddhhtt [offset] [pic format]
Arguments
-V -U Displays the command version and exits. Displays command usage information and exits.
base-date Specify one of the following: day | date | today | tomorrow | scheddate where: day date Specifies a day of the week. Valid values are: su, mo, tu, we, th, fr, or sa. Specifies a date, in the format element/element[/element], where element is: d[d], m[m], and yy[yy]. If two digits are used for the year (yy), a number greater than 70 is a 20th century date, and a number less than 70 is a 21st century date. Valid values for the month (m[m]) are jan, feb, mar, apr, may, jun, jul, aug, sep, oct, nov, or dec. The slashes (/) can be replaced by dashes (-), periods (.), commas (,), or spaces. For example, any of the following can be entered for March 28, 2005: 03/28/05 3-28-2005 28.mar.05 05,28,3 mar 28 2005 28 3 05 If numbers are used, it is possible to enter an ambiguous date, for example, 2,7,04. In this case, datecalc uses the date format defined
380
datecalc
in the Tivoli Workload Scheduler message catalog to interpret the date. If the date does not match the format, datecalc generates an error message. today Specifies the current system date.
tomorrow Specifies the current system date plus one day, or, in the case of time calculations, plus 24 hours. scheddate Specifies the date of the production plan. This might not be the same as the system date. When used inside jobs within a job stream that is not a carried forward job stream, it returns the date when the job should run, which could be different from the production date of the job stream if the job has an at dependency specified. When used inside jobs within a carried forward job stream, it returns the date when the job should have run, which could be different from the production date of the carried forward job stream if the job has an at dependency specified. If the at dependency is used with the following syntax: at=hhmm + n days, the n days are not added to the variable TIVOLI_JOB_DATE and therefore, the datecalc command does not report these days. -t time [base-date] Specify time in one of the following formats: now | noon | midnight | [h[h][[:]mm] [am | pm] [zulu] where: now noon Specifies the current system date and time. Specifies 12:00 p.m. (or 1200).
midnight Specifies 12:00 a.m. (or 0000). h[h][[:]mm] Specifies the hour and minute in 12-hour time (if am or pm are used), or 24-hour time. The optional colon (:) delimiter can be replaced by a period (.), a comma (,), an apostrophe (), the letter h, or a space. For example, any of the following can be entered for 8:00 p.m.: 8:00pm 20:00 0800pm 2000 8pm 20 8,00pm 20.00 8\00pm 20 00 zulu Specifies that the time you entered is Greenwich Mean Time (Universal Coordinated Time). datecalc converts it to the local time.
381
datecalc
yyyymmddhhtt Specifies the year, month, day, hour, and minute expressed in exactly twelve digits. For example, for 2005, May 7, 9:15 a.m., enter the following: 200505070915 offset Specifies an offset from base-date in the following format: {[+ | > | - | < number | nearest] | next} day[s] | weekday[s] | workday[s] | week[s] | month[s] | year[s] | hour[s] | minute[s] | day | calendar where: +|> Specifies an offset to a later date or time. Use + (Plus) in Windows; use > (greater than) in UNIX. Be sure to add a backslash (\) before the angle bracket (>). Specifies an offset to an earlier date or time. Use - (Minus) in Windows; use < (less than) in UNIX. Be sure to add a backslash (\) before the angle bracket (>). The number of units of the specified type. nearest Specifies an offset to the nearest occurrence of the unit type (earlier or later). next Specifies the next occurrence of the unit type.
-|<
number
day[s] Specifies every day. weekday[s] Specifies every day except Saturday and Sunday. workday[s] Same as weekday[s], but also excludes the dates on the holidays calendar. week[s] Specifies seven days. month[s] Specifies calendar months. year[s] Specifies calendar years. hour[s] Specifies clock hours. minute[s] Specifies clock minutes. day calendar Specifies the entries in a calendar with this name. pic format Specifies the format in which the date and time are returned. The format characters are as follows: m Month number. Specifies a day of the week. Valid values are: su, mo, tu, we, th, fr, or sa.
382
datecalc
d y j h t ^|/ Day number. Year number. Julian day number. Hour number. Minute number. One space. Use / (slash) in Windows; use ^ (carat) in UNIX (add a backslash (\) before the carat (^) if you are in the Bourne shell).
You can also include punctuation characters. These are the same as the delimiters used in date and time. If a format is not defined, datecalc returns the date and time in the format defined by the Native Language Support (NLS) environment variables. If the NLS variables are not defined, the native language defaults to C. freedays Specifies the name of a freedays calendar Calendar_Name that is to replace holidays in the evaluation of workdays. In this case, workdays is evaluated as everyday excluding saturday, sunday, and all the dates listed in Calendar_Name. By default, saturday and sunday are not regarded as workdays, unless you explicitly state the opposite by adding -sa and -su after Calendar_Name. You can also specify holidays as the name of the freedays calendar.
Examples
To return the next date, from today, on the monthend calendar, run the following command:
>datecalc today next monthend
In the following examples, the current system date is Friday, April 16, 2006.
>datecalc today +2 days pic mm/dd/yyyy 04/16/2006 >datecalc today next tu pic yyyy\^mm\^dd 2006 04 16 >LANG=american;export LANG >datecalc -t 14:30 tomorrow Sat, Apr 17, 2006 02:30:00 PM >LANG=french;datecalc -t 14:30 tomorrow Samedi 17 avril 2006 14:30:00
In the following example, the current system time is 10:24.

>datecalc -t now \> 4 hours pic hh:tt 14:24
383
delete
delete
Removes files. Even though this command is intended to remove standard list files you are suggested to use the rmstdlist command instead. The users maestro and root in UNIX, and Administrator in Windows can remove any file. Other users can remove only files associated with their own jobs.
Syntax
delete -V | -U delete filename
Arguments
-v -u filename Specifies the name of the file or group of files to be removed. The name must be enclosed in quotes () if it contains characters other than the following: alphanumerics, dashes (-), slashes (/), backslashes (\), and underscores (_). Wildcard characters are permitted. Note: Use this command carefully. Improper use of wildcard characters can result in removing files accidentally. Displays the command version and exits. Displays command usage information and exits.
Examples
To remove all the standard list files for 4/11/04, run the following command:
delete d:\win32app\maestro\stdlist\2004.4.11\@
The following script, included in a scheduled job in UNIX, removes the jobs standard list file if there are no errors:
... #Remove the stdlist for this job: if grep -i error $UNISON_STDLIST then exit 1 else `maestro`/bin/delete $UNISON_STDLIST fi ...
The standard configuration script, jobmanrc, sets the variable UNISON_STDLIST to the name of the job standard list file. For more information about jobmanrc, refer to the IBM Tivoli Workload Scheduler Planning and Installation Guide.
384
evtdef
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
evtdef
Imports/exports a generic event provider XML definition file where you can add and modify custom event types. You can then use the sendevent command to send these events to the event processing server.
Syntax
evtdef -U | -V evtdef [connection parameters] dumpdef file-path evtdef [connection parameters] loaddef file-path
Arguments
-U -V Displays command usage information and exits. Displays the command version and exits.
connection parameters Represents the set of parameters that rule the interaction between the command line and the WebSphere Application Server infrastructure using HTTP or HTTPS. Use this syntax to specify the settings for the connection parameters: [-host hostname] [-port port_number] [-protocol protocol_name] [-proxy proxy_name] [-proxyport proxy_port_number] [-password user_password] [-timeout timeout] [-username username] where: hostname Is the hostname of the master domain manager. port_number Is the port number used when establishing the connection with the master domain manager. protocol_name Is the protocol used during the communication. It can be HTTP with basic authentication or HTTPS with certificate authentication. proxy_name Is the proxy hostname used in the connection with HTTP. proxy_port_number Is the proxy port number used in the connection with HTTP. user_password Is the password of the user running the command. timeout Is the maximum time, expressed in seconds, the connecting command-line program can wait for the master domain manager response before considering the communication request as failed. username Is the user ID of the user running the command. If any of these parameters is omitted when invoking the command, Tivoli Workload Scheduler searches for the value first in the useropts file and then in the localopts file. If a setting for the parameter is not specified
385
evtdef
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | either in the connection parameters when invoking the command or inside the useropts and localopts files then an error is displayed. Refer toSetting up options for using the user interfaces on page 29 for information on useropts and localopts files. dumpdef file-path Downloads the generic event provider XML file. The file is downloaded with the file name and path you provide in file-path. You can edit the file to add your own custom event types. The name of the generic event provider supplied with the product is GenericEventPlugIn. loaddef file-path Uploads the modified generic event provider XML file from the file and path you provide in file-path.
Comments
The following rule language schemas are used to validate your custom event definitions and, depending upon the XML editor you have, to provide syntactic help: v eventDefinitions.xsd v common.xsd The files are located in the schemas subdirectory of the Tivoli Workload Scheduler installation directory.
Examples
In this example you: 1. Download the generic event provider XML file as file c:\custom\myevents.xml
evtdef dumpdef c:\custom\myevents.xml
2. Edit the file to add your own event type definitions. The first time you download the generic event provider file, it looks like this:
<?xml version="1.0" encoding="UTF-8" ?> -<eventDefinitions xmlns="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/plugins/events" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.ibm.com/xmlns/prod/tws/1.0/event-management/plugins/events eventDefinitions.xsd" > -<eventPlugin> <complexName displayName="Custom event" name="GenericEventPlugIn" /> -<scopes> -<scope name="Generic"> <scopedef text="{Param1} on {Workstation}" /> </scope> </scopes> - -<event baseAliasName="genericEvt" scope="Generic"> <complexName displayName="Generic event" name="Event1" /> <displayDescription>The event is sent when the specified expression is matched.</displayDescription> -<property type="string" required="true" wildcardAllowed="true" multipleFilters="true" minlength="1"> <complexName displayName="Parameter 1" name="Param1" /> <displayDescription>The value of parameter 1</displayDescription> </property> -<property type="string" required="true" wildcardAllowed="false" multipleFilters="false" minlength="1> <complexName displayName="Workstation" name="Workstation" /> <displayDescription>The workstation for which the event is generated.</displayDescription>
386
evtdef
| | | | | | | |
</property> </event> </eventPlugin> </eventDefinitions>
3. When finished, you upload the generic event provider XML file from file c:\custom\myevents.xmll
evtdef loaddef c:\custom\myevents.xml
387
evtsize
evtsize
Defines the size of the Tivoli Workload Scheduler message files. This command is used by the Tivoli Workload Scheduler administrator either to increase the size of a message file after receiving the message, End of file on events file., or to monitor the size of the queue of messages contained in the message file. You must be maestro or root in UNIX, or Administrator in Windows to run evtsize. Be sure to stop the IBM Tivoli Workload Scheduler engine before running this command.
Syntax
evtsize -V | -U evtsize filename size evtsize -show filename
Arguments
-V -U Displays the command version and exits. Displays command usage information and exits.
-show filename Displays the size of the queue of messages contained in the message file filename The name of the event file. Specify one of the following: Courier.msg Intercom.msg Mailbox.msg pobox/workstation.msg size The maximum size of the event file in bytes. When first built by Tivoli Workload Scheduler, the maximum size is set to 10 MB. Note: The size of the message file is equal to or bigger than the real size of the queue of messages it contains and it progressively increases until the queue of messages becomes empty; as this occurs the message file is emptied.
Examples
To set the maximum size of the Intercom.msg file to 20 MB, run the following command:
evtsize Intercom.msg 20000000
To set the maximum size of the pobox file for workstation chicago to 15 MB, run the following command:
evtsize pobox\chicago.msg 15000000
The following command:

evtsize -show Intercom.msg
returns the following output:

Tivoli Workload Scheduler (UNIX)/EVTSIZE 8.3 (1.2.2.4) Licensed Materials Property of IBM(R) 5698-WSH (C) Copyright IBM Corp 1998, 2006 All rights reserved. US Government User Restricted Rights
388
evtsize
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. AWSDEK703I Queue size current 240, maximum 10000000 bytes (read 48, write 288)
where: 880 10000000 read 48 write 928
Is Is Is Is
the the the the
size of the current queue of the Intercom.msg file maximum size of the Intercom.msg file pointer position to read records pointer position to write records
389
jobinfo
jobinfo
Used in a job script to return information about the job.
Syntax
jobinfo -v | -u jobinfo job-option [...]
Arguments
job-option The job option. Specify one or more of the following: confirm_job is_command job_name job_pri Returns YES if the job requires confirmation. Returns YES if the job was scheduled or submitted using the docommand construct. Returns the jobs name without the workstation and job stream names. Returns the jobs priority level.
programmatic_job Returns YES if the job was submitted with using the at or batch command. UNIX only. re_job re_type rstrt_flag rstrt_retcode schedule schedule_ia schedule_id time_started Returns YES if the job is being rerun as the result of a conman rerun command, or the rerun recovery option. Returns the jobs recovery option (stop, continue, or rerun). Returns YES if the job is being run as the recovery job. If the current job is a recovery job, returns the return code of the parent job. Returns the name of the job stream where the job is submitted. Returns the time and date the job stream is scheduled to start. Returns the jobstream_ID of the job stream where the job is submitted. Returns the time the job started running.
Comments
Job option values are returned, one on each line, in the same order they were requested.
390
jobinfo
Examples
1. The script file /jcl/backup is referenced twice, giving it the job names partback and fullback. If the job runs as partback, it performs a partial backup. If it runs as fullback, it performs a full backup. Within the script, commands like the following are used to make the distinction:
#Determine partial (1) or full (2): if [ "`\`maestro\`/bin/jobinfo job_name`" = "PARTBACK" ] then bkup=1 else bkup=2 fi ...
2. To display the return code of the parent job, if the current job is a recovery job, run the following command:
$ jobinfo rstrt_retcode
The first job (parent job) has been defined in the script recovery.sh while the second job (recovery job) gets enabled only if the first job abends. When combined with a return code condition, jobinfo rstrt_retcode can be used to direct the recovery job to take different actions depending on the parent jobs return code. A recovery job is shown in the example below:
$JOBS MASTER#DBSELOAD DOCOMMAND "/usr/local/tws/maestro/scripts/populate.sh" STREAMLOGON "^TWSUSER^" DESCRIPTION "populate database manual" RECOVERY RERUN AFTER MASTER#RECOVERY RCCONDSUCC "(RC = 0) OR ((RC > 4) AND (RC < 11))"
Note: The job is defined with the recovery action RERUN. This enables the recovery job to take some corrective action, before the parent job attempts to run again. The recovery job itself is defined as shown in the example below:
$ JOBS MASTER#RECOVERY DOCOMMAND "^TWSHOME^/scripts/recovery.sh" STREAMLOGON "^TWSUSER^" DESCRIPTION "populate database recovery manual" RECOVERY STOP
391
jobstdl
jobstdl
Returns the names of standard list files. This command must be run by the user for which Tivoli Workload Scheduler was installed. If you use this command without any parameters, ensure that you are logged on as a Tivoli Workload Scheduler user.
Syntax
jobstdl -v | -u jobstdl [-day num] [{-first | -last | -num n | -all}] [-twslog] [{-name ["jobstreamname [(hhmm date),(jobstream_id)].]jobname" | jobnum | -schedid jobstream_id.jobname}]
Arguments
-day num Returns the names of standard list files that are the specified number of days old (1 for yesterday, 2 for the day before yesterday, and so on). The default is zero (today). -first -last -num n Returns the name of the standard list file for the specified run of a job. -all -twslog Returns the path of the current day stdlist file. -name ["jobstreamname[(hhmm date), (jobstream_id)].]jobname" | jobnum Specifies the instance of the job stream and name of the job for which standard list file names are returned. jobnum Specifies the job number of the job for which standard list file names are returned. -schedid jobstream_id.jobname Specifies the job stream ID and name of the job for which standard list file names are returned. Returns the name of all qualifying standard list files. Returns the name of the first qualifying standard list file. Returns the name of the last qualifying standard list file.
Comments
File names are returned in a format suitable for input to other commands. Multiple names are returned separated by a space. The square brackets in the expression [(hhmm date), (jobstream_id)] are part of the command, not syntax indicators. This means that you can supply either of the following for the -name argument:
jobstdl -name ["jobstreamname[(hhmm date),(jobstream_id)].jobname" jobstdl -name jobnum
392
jobstdl
The whole job identification string must be enclosed in double quotes if the part identifying the job stream instance contains blanks. For example, because the schedtime, represented by hhmm date, has a space in it you must enclose the whole job identification in double quotes. If you just want to identify a job name, you do not need the double quotes. The following is an example of the syntax to use when identifying a job both with and without its job stream. In the example, job_stream1 is the name of the job stream, 0600 04/05/06 is the scheduled time, 0AAAAAAAAAAAAAB5 is the job stream ID, and job1 is the job name. You can run the jobstdl command against job1 using either of these two formats:
jobstdl -name "job_stream1[(0600 04/05/06),(0AAAAAAAAAAAAAB5)].job1" jobstdl -name job1
Examples
To return the path names of all standard list files for the current day, run the following command:
jobstdl
To return the path name of the standard list for the first run of job MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR on the current day, run the following command:
jobstdl -first -name "MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR"
To return the path name of the standard list for the first run of job 0AAAAAAAAAAAAAEE.DIR on the current day, run the following command:
jobstdl -first -schedid 0AAAAAAAAAAAAAEE.DIR
To return the path name of the standard list for the second run of job MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR on the current day, run the following command:
jobstdl -num 2 -name "MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR"
To return the path names of the standard list files for all runs of job MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR from three days ago, run the following command:
jobstdl -day 3 -name "MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR"
To return the path name of the standard list for the last run of job MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR from four days ago, run the following command:
jobstdl -day 4 -last -name "MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR"
To return the path name of the standard list for job number 455, run the following command:
jobstdl 455
To print the contents of the standard list file for job number 455, run the following command:
cd `maestro`/bin lp -p 6 `jobstdl 455`
393
maestro
maestro
Returns the path name of the Tivoli Workload Scheduler home directory, referred to as TWS_home.
Syntax
maestro [-v | -u]
Arguments
Examples
To display the Tivoli Workload Scheduler home directory, run the following command:
$ maestro /usr/lib/maestro
To change the directory to the Tivoli Workload Scheduler home directory, run the following command:
$ cd `maestro`
394
makecal
makecal
Creates a custom calendar. In UNIX, the Korn shell is required to run this command.
Syntax
makecal [-v | -u] makecal [-c name] -d n | -e | {-f 1 | 2 | 3 -s date} | -l | -m | -p n | {-r n -s date} | -w n [-i n] [-x | -z] [-freedays Calendar_Name [-sa] [-su]]
Arguments
-v -u -c name Specifies a name for the calendar. Tivoli Workload Scheduler keywords (such as Freedays or Schedule) cannot be used as calendar names. The name can contain up to eight alphanumeric characters and must start with a letter. Do not use the names of weekdays for the calendar names. The default name is: Chhmm, where hhmm is the current hour and minute. -d n -e Specifies the nth day of every month. Specifies the last day of every month. Displays the command version and exits. Displays command usage information and exits.
-f 1 | 2 | 3 Creates a fiscal month-end calendar containing the last day of the fiscal month. Specify one of the following formats: 1 2 3 4-4-5 week format 4-5-4 week format 5-4-4 week format
This argument requires the -s argument. -i n -l Specifies to insert n dates in the calendar. Specifies the last workday of every month. For this argument to work properly, the production plan (Symphony file) and the holidays calendar must already exist. Note: Using this argument results in the new calendar also including the last workday of the month that precedes the date of creation of the calendar. -m Specifies the first and fifteenth days of every month.
395
makecal
-p n Specifies the workday before the nth day of every month. For this argument to work properly, the production plan (Symphony file) and the holidays calendar must already exist Specifies every nth day. This argument requires the -s argument.
-r n
-s date Specifies the starting date for the -f and -r arguments. The date must be enclosed in quotation marks, and must be valid and unambiguous, for example, use JAN 10 2005, not 1/10/05. See base-date for datecalc on page 380 for more information about date formats. -w n Specifies the workday after the nth of the month. For this argument to work properly, the production plan (Symphony file) and the holidays calendar must already exist. Sends the calendar output to stdout instead of adding it to the database. Adds the calendar to the database and compiles the production plan (Symphony file). Note: This argument re-submits jobs and job streams from the current days production plan. It might be necessary to cancel job streams and jobs. -freedays Specifies the name of a freedays calendar Calendar_Name that is to replace holidays in the evaluation of workdays. In this case, workdays is evaluated as everyday excluding saturday, sunday and all the dates listed in Calendar_Name. By default, saturday and sunday are not regarded as workdays, unless you explicitly state the opposite by adding -sa and/or -su after Calendar_Name. You can also specify holidays as the name of the freedays calendar. This keyword affects the processing of makecal with options -l, -p, and -w.
-x -z
Examples
To make a two-year calendar with the last day of every month selected, run the following command:
makecal -e -i 24
To make a calendar with 30 days that starts on May 30, 2005, and has every third day selected, run the following command:
makecal -r 3 -s "30 MAY 2005" -i 30
396
metronome.pl
metronome.pl
It is a PERL Version 5.8.0 script used mainly for troubleshooting and diagnosis purposes. This utility command can be used to get one of the following: v A backup copy of the Tivoli Workload Scheduler configuration files v An HTML report containing a snapshot of Tivoli Workload Scheduler v A backup copy of the Tivoli Workload Scheduler DB2 database It is useful to collect problem determination information to provide to IBM Software Support, if a problem with the product the problem is encountered.
Comments
Refer to IBM Tivoli Workload Scheduler Administration and Troubleshooting Guide for more information about the metronome.pl command.
397
morestdl
morestdl
Displays the contents of standard list files. This command must be run by the user for which Tivoli Workload Scheduler was installed. If you use this command without any parameters, ensure that you are logged on as a Tivoli Workload Scheduler user.
Syntax
morestdl -v | -u morestdl [-day num] [-first | -last | -num n | -all] [-twslog] [{-name ["jobstreamname [(hhmm date),(jobstream_id)].]jobname" | jobnum | -schedid jobstream_id.jobname}]
Arguments
-day num Displays standard list files that are the specified number of days old (1 for yesterday, 2 for the day before yesterday, and so on). The default is zero (today). -first -last -num n Displays the standard list file for the specified run of a job. -all -twslog Displays the content of the current day stdlist file. -name ["jobstreamname [(hhmm date),(jobstream_id)].]jobname"|jobnum Specifies the instance of the job stream and the name of the job for which the standard list file is displayed. jobnum Specifies the job number of the job for which the standard list file is displayed. -schedid jobstream_id.jobname Specifies the job stream ID and name of the job for which standard list file names are returned. Displays all qualifying standard list files. Displays the first qualifying standard list file. Displays the last qualifying standard list file.
Comments
The square brackets in the expression [(hhmm date), (jobstream_id)] are part of the command, not syntax indicators. This means that you can supply either of the following for the -name argument:
morestdl -name ["jobstreamname[(hhmm date),(jobstream_id)].jobname" morestdl -name jobnum
398
morestdl
The whole job identification string must be enclosed in double quotes if the part identifying the job stream instance contains blanks. For example, because the schedtime, represented by hhmm date, has a space in it you must enclose the whole job identification in double quotes. If you just want to identify a job name, you do not need the double quotes. The following is an example of the syntax to use when identifying a job both with and without its job stream. In the example, job_stream1 is the name of the job stream, 0600 04/05/06 is the scheduled time, 0AAAAAAAAAAAAAB5 is the job stream ID, and job1 is the job name. You can run the morestdl command against job1 using either of these two formats:
morestdl -name "job_stream1[(0600 04/05/06),(0AAAAAAAAAAAAAB5)].job1" morestdl -name job1
Examples
To display the standard list file for the first run of job MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR on the current day, run the following command:
morestdl -first -name "MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR"
To display the standard list file for the first run of job 0AAAAAAAAAAAAAEE.DIR on the current day, run the following command:
morestdl -first -schedid 0AAAAAAAAAAAAAEE.DIR
To display the standard list file for the second run of job MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR on the current day, run the following command:
morestdl -num 2 -name "MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR"
To display the standard list files for all runs of job MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR from three days ago, run the following command:
morestdl -day 3 -name "MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR"
To display the standard list file for the last run of job MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR from four days ago, run the following command:
morestdl -day 4 -last -name "MY_CPU#ELI[(1824 03/09/06),(0AAAAAAAAAAAAAEE)].DIR"
To print the standard list file for job number 455, run the following command:
morestdl 455 | lp -p 6
399
parms
parms
Manages parameters defined locally on workstations. Parameters managed by parms can only be used in jobs or job streams definition with the scriptname or opens keywords or in a job script file. These parameters are resolved at submission time on the workstation where the job or job stream is submitted from the conman command line. If there is no match between the specified parametername and the name of the parameters defined in the local database on the workstation then a null value is returned.
Authorization
You must have display access to the locally defined parameters database. In addition you must be authorized with the following access: build on object file If you use the -b option to create or rebuild the local parameters database. delete If you use the -d option to delete parameter definitions.
modify on object file If you use the -replace option to add or modify parameter definitions.
Syntax
parms {[-V | -u] | -build} parms {-replace | -extract} filename parms [-d]parametername parms -c parametername value
Arguments
-V -u Displays the command version and exits. Displays command usage information and exits.
-build Creates the parameters database on the workstation if it does not exist. Rebuilds the parameters database, removing unused records and avoiding fragmentation from numerous additions and deletions, if it already exists. -extract Extracts all parameter definitions from the local database and stores them in the file with name filename. Use this option if you want to export local parameter definitions to import them as global parameter definitions into the scheduling objects database using the add on page 203 or the replace on page 236 commands. -replace Add in the local database new parameter definitions stored in a file named filename or substitute the already existing ones. Use this option if you want to import, as local parameter definitions, the global parameter definitions contained in the file named filename and extracted from the scheduling objects database using the create - extract on page 207 command. -d Deletes the parameters with name parametername from the local database on the workstation.
400
parms
parametername Specifies the name of the parameter whose value is displayed. When used with the argument -d it represents the name of the parameter to be deleted. -c name value Specifies the name and the value of a parameter. The value can contain up to 72 characters. Enclose the value in double quotes if it contains special characters. If the parameter does not exist, it is added to the database. If the parameter already exists, its value is changed.
Comments
When parms is run at the command line without arguments, it prompts for parameter names and values. The use of parms in either job definitions and job script files requires that the parameter already exists locally in the parameters database on the workstation. This is a sample usage of a local parameter, MYFILE, in a file dependency clause:
schedule test_js on everyday opens "/usr/home/tws_99/`/usr/home/tws_99/bin/parms MYFILE`" : test_job end
The following example explains how the variable var enclosed by the caret ^ is replaced while the job is in process. If the job is submitted as an ad hoc job, the parameter var is expanded, that means replaced by the value assigned to var in the local database, at submission time and not when the job launches. UNIX job definition example:
DATA#UX_P_TEST DOCOMMAND "ls ^var^" STREAMLOGON "mae82" DESCRIPTION "Test parms in job definition on UNIX." RECOVERY STOP
Windows job definition example:

BORG#WIN_P_TEST DOCOMMAND "dir ^var^" STREAMLOGON "mae82" DESCRIPTION "Test parms in job definition on Windows." RECOVERY STOP
When used in a job script file, the parameter is not expanded until the script launches. It is not expanded when the job stream containing the job is processed by JnextPlan. These are examples on how to use the var parameter in job script files. UNIX script example:
#!/bin/sh TWS_HOME="/opt./tws/mae82/maestro" export TWS_HOME MDIR=`$TWS_HOME/bin/parms var` export MDIR ls -l $MDIR
Windows script example:
401
parms
set TWS_HOME=d:\win32app\TWS\mae82\maestro echo %TWS_HOME% FOR /F "Tokens=*" %%a in (%TWS_HOME%\bin\parms var) do set MDIR=%%a echo %MDIR% dir %MDIR%
Examples
To return the value of myparm, run the following command:
parms myparm
To change the value of myparm, run the following command:

parms -c myparm "item 123"
To create a new parameter named hisparm, run the following command:

parms -c hisparm "item 789"
To change the value of myparm and add herparm, run the following command:
parms Name of parameter ? Value of parameter? Name of parameter ? Value of parameter? Name of parameter ? myparm < Return> "item 456" < Return> herparm < Return> "item 123" < Return> < Return>
402
release
release
Releases jobs and job streams from needs dependencies on a resource. This command must be issued only from within the job script file.
Syntax
release -v | -u release [-s] [workstation#] resourcename [count]
Arguments
-v -u -s Displays the command version and exits. Displays command usage information and exits. Releases the needs dependency from the specified resource only at the job stream level. If -s is not used, the needs dependency from the specified resource is released at the job level, or at the job stream level if the needs dependency from that resource is not found at the job level. workstation# Specifies the name of the workstation or workstation class on which the resource is defined. The default is the local workstation. resourcename Specifies the name of the resource involved in the needs dependency. count Specifies the number of units of the resource to be released.
Comments
Units of a resource are acquired by a job or job stream at the time it is launched and are released automatically when the job or job stream completes. The release command can be used in a job script to release resources before job or job stream completion or to release manually jobs and job streams from needs dependencies in emergency situations.
Examples
In the following job stream, two units of the dbase resource are required by job stream sked5:
schedule ux1#sked5 on tu needs 2 dbase : job1 jobrel follows job1 job2 follows jobrel end
To release the dbase resource before job2 begins, the script file for jobrel contains the following command:
`maestro`/bin/release -s dbase
Note: The -s argument can be omitted, because no resources were reserved at the job level.
403
rmstdlist
rmstdlist
Removes or displays standard list files based on the age of the file. This utility should be used by the Tivoli Workload Scheduler administrator to maintain the scheduling environment.
Syntax
rmstdlist -v | -u rmstdlist [-p] [age]
Arguments
-v -u -p Displays the command version and exits. Displays command usage information and exits. Displays the names of qualifying standard list file directories. No directories or files are removed. If you do not specify -p, the qualifying standard list files are removed. The minimum age, in days, of standard list file directories to be displayed or removed. The default is 10 days.
age
Note: Because the list of directories and files shown or deleted using rmstdlist is produced based on the last time they were accessed, the dates shown in the list of directories could differ from the dates displayed in the list of files. | | | | | | | | | | | | | | | |
Syntax
As a rule, you should regularly remove standard list files somewhere between every 10-20 days. Larger backlogs may be harder to manage and, if the number of files becomes exceedingly large, you might be required to erase some of them manually before you can use rmstdlist again. This problem might occur on AIX systems, particularly, because of a currently unresolved limitation with the rm -rf command. When rmstdlist fails because of this limitation, it does not display any errors other than exit code 126. If you would rather have the rm -rf error displayed, you can edit the rmstdlist script in the following way: 1. Locate the script in the TWS_home/bin directory 2. Find the line:
rm -rf `cat /tmp/rm$$` 2> /dev/null
3. Remove the redirection to /dev/null so that the line becomes:

rm -rf `cat /tmp/rm$$`
Examples
To display the names of standard list file directories that are more than 14 days old, run the following command:
rmstdlist -p 14
To remove all standard list files (and their directories) that are more than seven days old, run the following command:
rmstdlist 7
404
sendevent
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
sendevent
The command sends the custom events defined with the evtdef command to the event processor server currently active in the production plan. As the events are received by the event processor, they trigger the event rules in which they were specified. Users can override the default destination server (defined by global options) by specifying the host and the port of a new server.
Syntax
sendevent -V | ? | -help | -u | -usage sendevent [-hostname hostname][-port port] eventType source [[attribute=value]...]
Arguments
-V Displays the command version and exits. ? | -help | -u | -usage Displays command usage information and exits. -hostname hostname Specifies the host name of an alternate event processor server other than the currently active one. This parameter is required if the command is launched from a remote command line. -port port Specifies the port number of an alternate event processor server other than the currently active one. This parameter is required if the command is launched from a remote command line. eventType One of the custom event types defined with the evtdef command in the generic event provider and specified as the triggering event in an event rule definition. source The event originator. Currently, you must specify the name of the generic event provider that you customized with evtdef, that is:
GenericEventPlugIn
GenericEventPlugIn must also be specified as the event provider in the definition of the event rules triggered by the custom events. attribute=value One or more of the attributes qualifying the custom event type that are specified as the triggering event attributes for the event rule.
Comments
This command can be run also on systems where only the Tivoli Workload Scheduler remote command line client is installed.
Examples
In this example an application sends the BusProcCompleted custom event type to an alternate event processor server named master3. The event is that file calcweek finished processing.
sendevent -hostname master3 -port 4294 BusProcCompleted GenericEventPlugIn TransacName=calcweek Workstation=ab5supp
405
sendevent
| | | The file name and the associated workstation are the two BusProcCompleted event attributes that were specified as triggering event attributes in an associated event rule.
406
showexec
showexec
Displays the status of running jobs. This command applies to UNIX only. This command is for standard agents. On domain managers and fault-tolerant agents, use the conman showjobs command instead.
Syntax
showexec [-v | -u | INFO]
Arguments
INFO Displays the name of the job file instead of the user, date, and time.
Results
The output of the command is available in two formats: standard and INFO. Standard format: CPU Schedule Job Job# User Start Date Start Time (Est) Elapse Info format: CPU Schedule Job Job# JCL The workstation on which the job runs. The name of the job stream in which the job runs. The job name. The job number. The file name of the job. The workstation on which the job runs. The name of the job stream in which the job runs. The job name. The job number. The user name of the job. The date the job started running. The time the job started running. The estimated time, in minutes, that the job will run.
Examples
To display running jobs in the standard format, run the following command:
showexec
To display running jobs in the INFO format, run the following command:
showexec INFO
407
shutdown
shutdown
| | | Stops the Tivoli Workload Scheduler processes, and optionally also stops the embedded application server. Applies to Windows workstations only. You must have shutdown access to the workstation.
Syntax
shutdown [-v | -u] [-appsrv]
Arguments
-v -u -appsrv Stops also WebSphere Application Server. Displays the command version and exits. Displays command usage information and exits.
Comments
Make sure the TWS_user you are using belongs to the Admnistrators group defined on the Windows workstation.
Examples
To display the command name and version, run the following command:
shutdown -v
To stop both the Tivoli Workload Scheduler processes and WebSphere Application Server, run the following command:
shutdown -appsrv
408
StartUp
StartUp
Starts netman, the Tivoli Workload Scheduler network management process. You must have start access to the workstation.
Syntax
StartUp [-v | -u]
Arguments
Comments
In Windows, the netman service is started automatically when a computer is restarted. StartUp can be used to restart the service if it is stopped for any reason. In UNIX, the StartUp command can be run automatically by invoking it from the /etc/inittab file, so that WebSphere Application Server infrastructure and netman is started each time a computer is rebooted. StartUp can be used to restart netman if it is stopped for any reason. The remainder of the process tree can be restarted with the
conman start conman startmon
commands. See conman start on page 342 for more information.
Examples
To display the command name and version, run the following command:
StartUp -v
To start the netman process, run the following command:

StartUp
409
version
version
Displays information about the current release of Tivoli Workload Scheduler installed on the system. This command applies to UNIX only. The information is extracted from a version file.
Syntax
version -V | -u | -h version [-a] [-f vfile] [file [...]]
Arguments
-V -u -h -a Displays the command version and exits. Displays command usage information and exits. Displays command help information and exits. Displays information about all product files. The default is to display information only about the specified files.
-f vfile Specifies the path and name of the version file if different from the default setting. The default is a file named version.info in the current working directory. file Specifies the names of product files, separated by spaces, for which version information is displayed. The default is to display no file information, or, if -a is used, all file information.
Results
The output header contains the product name, version, operating system, patch level, and installation date. The remaining display lists information about the file or files specified. The files are listed in the following format: File Revision Patch Size (bytes) Checksum The name of the file. The revision number of the file. The patch level of the file, if any. The size of the file in bytes. The checksum for the file. Checksum is calculated using the UNIX sum command. On AIX, sum is used with the -o argument.
Comments
Tivoli Workload Scheduler file information is contained in the version.info file. This file is placed in the TWS_home/version directory during installation. The version.info file is in a specific format and should not be altered. You can move the version.info file to another directory. However, you must then include the -f argument to locate the file.
Examples
To display information about the release of Tivoli Workload Scheduler installed, run the following command:
./version
A sample output of this command is:
410
version
IBM Tivoli Workload Scheduler/VERSION 8.3 (9.9) (C) Copyright IBM Corp 1998, 2006 IBM Tivoli Workload Scheduler 8.3 UNIX linux-ix86 PATCH February 2006
To display information about all files, run the following command:

version/version -a -f version/version.info
To display information about the file customize, run the following command:
cd version ./version customize
To display information about the file customize, when version.info is located in /apps/maestro, run the following command:
cd version ./version -f /apps/maestro/version.info customize
411
Unsupported commands
Unsupported commands
The following unsupported utility commands provide functions in Windows that are similar to UNIX ps and kill commands. They can be used if similar Windows utilities are not available.
Syntax
listproc killproc pid
Comments
listproc Displays a tabular listing of processes on the system. killproc Kills the process with the process ID pid. Note: When run by the Administrator, killproc is capable of killing system processes.
412
Chapter 11. Getting reports and statistics

| | | | | | | | | | | | | | | | | | | | | | | | | | This chapter describes the report commands that let you get summary or detailed information about the previous or next production plan. These commands are run from the operating system command prompt on the master domain manager. The chapter is divided into the following sections: v What is new in running reports and statistics v Setup for using report commands v Command descriptions on page 414 v Sample report outputs on page 425 v Report extract programs on page 440 v Additional reports available on the Tivoli Dynamic Workload Console on page 454
What is new in running reports and statistics

This product version supports a set of new reports that can be run on the Tivoli Dynamic Workload Console. There are: v Historical reports: Job run history Job run statistics Workstation workload summary Workstation workload runtimes Custom SQL v Production reports: Actual production details Planned production details See Additional reports available on the Tivoli Dynamic Workload Console on page 454 and the Tivoli Dynamic Workload Console online documentation for more information.
Setup for using report commands

To configure the environment for using report commands set the PATH and TWS_TISDIR variables by running one of the following scripts: v . ./TWS_home/tws_env.sh for Bourne and Korn shells in UNIX v . ./TWS_home/tws_env.csh for C shells in UNIX v TWS_home\tws_env.cmd in Windows | The report commands must be run from the TWS_home directory. The output of the report commands is controlled by the following environment variables: MAESTROLP Specifies the destination of the output of a command. The default is stdout. You can set it to any of the following: filename Writes the output to a file.
413
Setup for report commands output

> filename UNIX only. Redirects output to a file, overwriting the contents of the file. If the file does not exist it is created. >> filename UNIX only. Redirects output to a file, appending to the end of the file. If the file does not exist it is created. | command UNIX only. Pipes output to a system command or process. The system command is always run. || command UNIX only. Pipes output to a system command or process. The system command is not run if there is no output. MAESTRO_OUTPUT_STYLE Specifies the output style for long object names. Set the variable to LONG to use full length (long) fields for object names. If it is not set or is set to anything other than LONG, long names are truncated to eight characters and a plus sign. For example: A1234567+. You are suggested to use a fixed font size for correctly managing reports output formatting.
Changing the date format

In Tivoli Workload Scheduler, the date format affects all commands that accept a date as an input option (except the datecalc command), and the headers in all reports. The default date format is mm/dd/yy. To select a different format, edit the date format local option store in the localopts file. The values are:
Table 51. Date formats date format value 0 1 2 3 Corresponding date format output yy/mm/dd mm/dd/yy dd/mm/yy Native language support variables.
See the IBM Tivoli Workload Scheduler Planning and Installation Guide for details on modifying local variables in the localopts file.
Tivoli Workload Scheduler report commands are listed in Table 52:
Table 52. List of report commands Command rep1 rep2 rep3 rep4a rep4b Description Report 01 - Job Details Listing Report 02 - Prompt Listing Report 03 - Calendar Listing Report 04A - Parameter Listing Report 04B - Resource Listing
414
Table 52. List of report commands (continued) Command rep7 rep8 rep11 reptr Description Report 07 - Job History Listing Report 08 - Job Histogram Report 11 - Planned Production Schedule Report Report Report Report Report 09A 09B 09D 10A 10B Planned Production Summary Planned Production Detail Planned Production Detail (Long Names) Actual Production Summary Actual Production Detail
xref
Report 12 - Cross Reference Report
415
rep1 - rep4b
rep1 - rep4b
These commands print the following reports: Report 01 Job Details Listing Report 02 Prompt Listing Report 03 Calendar Listing Report 04A Parameters Listing Report 04B Resource Listing
Syntax
rep[x] [-v|-u] | Run the command from the TWS_home directory.
Arguments
x -u -v A number corresponding to the report. The numbers are: 1, 2, 3, 4a, or 4b. Displays the command usage information and exits. Displays the command version and exits.
Comments
| | The Job Details Listing (report 01) cannot include jobs that were submitted using an alias name.
Examples
Print Report 03, User Calendar Listing:
rep3
Display usage information for the rep2 command:

rep2 -u
In UNIX, print two copies of report 04A, User Parameters Listing, on printer lp2:
MAESTROLP="| lp -dlp2 -n2" export MAESTROLP rep4a
416
rep7
rep7
This command prints Report 07-Job History Listing.
Syntax
rep7 -v|-u rep7 [-c wkstat] [-s jstream_name] [-j job] [-f date ] [-t date] [-l] | Run the command from the TWS_home directory.
Arguments
-u -v Displays the command usage information and exits. Displays the command version and exits.
-c wkstat Specifies the name of the workstation on which the jobs run. The default is all workstations. -s jstream_name Specifies the name of the job stream in which the jobs run. The default is all job streams. -j job Specifies the name of the job. The default is all jobs.
-f date Specifies to print job history from this date forward. Enter the date as yyyymmdd. The default is the earliest available date. -t date Specifies to print job history up to this date. Enter the date as yyyymmdd. The default is the most recent date. -l Limits the summary line information to the jobs which fall in the date range specified by the -f or -t options. Using this option causes the order of output to be reversed: the job summary line will be printed after the individual job run lines. This option is valid only if you also specify at least one of the -f or -t options.
Comments
| The report does not include jobs that were submitted using an alias name. Any time you run rep7 the output of the command contains the information stored until the last time you run JnextPlan, the information related to the run of the current production plan will be contained in the rep7 output the next time you run JnextPlan. For this reason if you run rep7 after having generated the production plan for the first time or after a ResetPlan command, the output of the command contains no statistic information.
Examples
Print all job history for workstation ux3:
rep7 -c ux3
Print all job history for all jobs in job stream sked25:
417
rep7
rep7 -s sked25
Print job history for all jobs in job stream mysked on workstation x15 between 1/21/2005 and 1/25/2005:
rep7 -c x15 -s mysked -f 20050121 -t 20050125
418
rep8
rep8
This command prints Report 08-Job Histogram.
Syntax
rep8 -v|-u rep8 [-f date -b time -t date -e time] [-i file] [-p ] rep8 [-b time -e time] [-i file] [-p ] | Run the command from the TWS_home directory.
Arguments
-f date Specifies to print job history from this date forward. Enter the date as yyyymmdd. The default is todays date. -b time Specifies to print job history from this time forward. Enter the time as hhmm. The default is the Tivoli Workload Scheduler startOfDay. -t date Specifies to print job history up to this date. Enter the date as yyyymmdd. The default is the most recent date. -e time Specifies to print job history up to this time. Enter the time as hhmm. The default is the Tivoli Workload Scheduler start of day time. -i file Specifies the name of the log file from which job history is extracted. Note that log files are stored in the schedlog directory. The default is the current Symphony file. Note: Ensure that the time range specified by the [-f date -b time -t date -e time] arguments is within the date and time range defined in the -i file log file name. -p Specifies to insert a page break after each run date.
Comments
| The report does not include jobs that were submitted using an alias name. Any time you run rep8 the output of the command contains the information stored until the last time you run JnextPlan, the information related to the run of the current production plan will be contained in the rep8 output the next time you run JnextPlan. For this reason if you run rep8 after having generated the production plan for the first time or after a ResetPlan command, the output of the command contains no statistic information.
419
rep8
Examples
Print a job histogram which includes all information in the current plan (Symphony file):
rep8
Print a job histogram beginning at 6:00 a.m. on 1/25/2005, and ending at 5:59 a.m. on 1/26/2005:
rep8 -f 20050125 -b 0600 -t 20050126 -e 0559 -i schedlog/M199801260601
Print a job histogram, from the current plan (Symphony file), beginning at 6:00 am, and ending at 10:00 pm:
rep8 -b 0600 -e 2200
420
rep11
rep11
This command prints Report 11-Planned Production Schedule.
Syntax
rep11 -v|-u rep11 [-m mm[yy] [...]] [-c wkstat [...]] [-s jstream_name] [-o file] | Run the command from the TWS_home directory.
Arguments
-m mm[yy] Specifies the months to be reported. Enter the month number as mm. The default is the current month. You can also enter a year as yy. The default is the current year or next year if you specify a month earlier than the current month. -c wkstat Specifies the workstations to be reported. The default is all workstations. -s jstream_name Specifies the name of the job stream in which the jobs run. The default is all job streams. -o file Specifies the output file. The default is the file defined by the MAESTROLP variable. If MAESTROLP is not set, the default is stdout.
Examples
Report on June, July, and August of 2004 for workstations main, site1 and sagent1:
rep11 -m 062004 072004 082004 -c main site1 sagent1
Report on June, July, and August of this year for all workstations, and direct output to the file r11out:
rep11 -m 06 07 08 -o r11out
Report on this month and year for workstation site2:

rep11 -c site2
421
reptr
reptr
This command prints the following reports: Report 09A Planned Production Summary Report 09B Planned Production Detail Report 10A Actual Production Summary Report 10B Actual Production Detail Report 09A and Report 09B refer to future production processing while Report 10A and Report 10B show processing results and status of each single job of already processed production.
Syntax
reptr [-v|-u] reptr -pre [-{summary | detail}] [symfile] reptr -post [-{summary | detail}] [logfile] | Run the command from the TWS_home directory.
Arguments
-u -v -pre -post Displays the command usage information and exits. Displays the command version and exits. Specifies to print the pre-production reports (09A and 09B). Specifies to print the post-production reports (10A and 10B).
-summary Specifies to print the summary reports (09A and 10A). If -summary and -detail are omitted, both sets of reports are printed. -detail Specifies to print the detail reports (09B and 10B). If -summary and -detail are omitted, both sets of reports are printed. symfile Specifies the name of the plan file from which reports will be printed. The default is Symnew in the current directory. logfile Specifies the name of the log file from which the reports will be printed. Note that plan log files are stored in the schedlog directory. The default is the current plan (Symphony file).
If the command is run with no options, all pre and post reports are printed.
Examples
Print the pre-production detail report from the Symnew file:
reptr -pre -detail
422
reptr
Print the pre-production summary report from the file mysym:
reptr -pre -summary mysym
Print the post-production summary report from the log file M199903170935:
reptr -post -summary schedlog/M199903170935
Print all pre and post-production reports.

reptr
The pre-production reports are based on information read from the Symnew file. The post-production reports are based on information read from the Symphony file.
423
xref
xref
This command prints Report 12-Cross Reference Report.
Syntax
xref [-V|-U] xref [-cpu wkstat] [-depends|-files|-jobs|-prompts|-resource|-schedules|-when[...]] | Run the command from the TWS_home directory.
Arguments
-U -V Displays the command usage information and exits. Displays the command version and exits.
-cpu wkstat Specifies to print the report for the named workstation. The @ wildcard is permitted, in which case, information from all qualified workstations is included. The default is all workstations. -depends Specifies to print a report showing the job streams and jobs that are successors of each job. -files -jobs Specifies to print a report showing the job streams and jobs that are dependent on each file. Specifies to print a report showing the job streams in which each job is run.
-prompts Specifies to print a report showing the job streams and jobs that are dependent on each prompt. -resource Specifies to print a report showing the job streams and jobs that are dependent on each resource. -schedules Specifies to print a report showing the job streams and jobs that are successors of each job stream. -when Specifies to print a report showing job stream Include and Exclude dates. If the command is run with no options, all workstations and all options are selected.
Examples
Print a report for all workstations, showing all cross-reference information:
xref
Print a report for all workstations. Include cross-reference information about all successor dependencies:
xref -cpu @ -depends -schedules
424
Sample report outputs
Sample report outputs Report 01 - Job Details Listing:

TWS for UNIX (AIX)/REPORT1 8.3 (1.7) Report 01 Job Description JCL File Logon Creator Recovery Job Recovery Type Recovery Prompt composer Autodoc Total Runs Total Normal Last Run Maximum Minimum Job Description JCL File Logon Creator Recovery Job Recovery Type Recovery Prompt composer Autodoc Total Runs Total Normal Last Run Maximum Minimum Job Description JCL File Logon Creator Recovery Job Recovery Type Recovery Prompt composer Autodoc Total Runs Total Normal Last Run Maximum Minimum : : : : : : : : : : FTAWIN8+ dir maestro_adm root STOP Yes 0 0 Successful, CPU(secs) 0 0 (On 0 (On 0 (On at 00:00) ) ) 0 Aborted ibm Job Details Listing Page 1 03/06/06
#SCHEDDDD
Elapsed(mins) 00:00:00 00:00:00 00:00:00 00:00:00 00:00:00 : : : : : : : : : :
MASTER8+ #JnextPlan ADDED BY composer FOR SCHEDULE MASTER821#FINAL. /test/maestro_adm/tws/JnextPlan maestro_adm maestro_adm STOP Yes 11 11 Successful, CPU(secs) 44 4 (On 03/05/06 at 23:16) 4 (On 03/04/06) 4 (On 03/04/06) 0 Aborted
Elapsed(mins) 00:00:14 00:00:01 00:00:01 00:00:02 00:00:01 : : : : : : : : : :
MASTER8+ #JOB1 ADDED BY composer. pwd ^ACCLOGIN^ root STOP Yes 1 1 Successful, CPU(secs) 0 0 (On 03/05/06 at 22:22) 0 (On 03/05/06) 0 (On 03/05/06) E n d o f R e p o r t * * * * 0 Aborted
Elapsed(mins) 00:00:01 00:00:01 00:00:01 00:00:01 00:00:01 * * * *
425
Report 01 - Job Details Listing

In the output you see the values set in the Job definition on page 119 as follows:: composer Autodoc Says if the job statement was described in the job stream definition using the command line interface. CPU (secs) Is the actual time, expressed in seconds, the job made use of the CPU to run. Total Normal Is the average value of CPU time recorded during the Total Runs. Last Run Is the CPU time recorded during the last run of the job. | | | | | | | | Creator Description Elapsed Maximum Is the maximum among the values collected for CPU time during the Total Runs (calculated only for jobs ended successfully). Minimum Is the minimum among the values collected for CPU time during the Total Runs (calculated only for jobs ended successfully). Is the name of the user who created the job definition. Is the textual description of the job set in the description field of the job definition statement. Is the amount of time, expressed in minutes, that includes both the time during which the job made use of the CPU and the time the job had to wait for other processes to release the CPU. Total Normal Is the average value of Elapsed time recorded during the Total Runs. Last Run Is the Elapsed time recorded during the last run of the job. | | | | | | | | JCL File Maximum Is the maximum among the values collected for Elapsed time during the Total Runs' (calculated only for jobs ended successfully). Minimum Is the minimum among the values collected for Elapsed time during the Total Runs (calculated only for jobs ended successfully). Is the name of the file set in the scriptname field that contains the script to run, or the command specified in the docommand field to invoke when running the job. Is the identifier of the job, [workstation#]jobname. Is the user name, specified in the streamlogon field, under which the job runs. Is the sum of Elapsed time recorded for the Total Runs. Is the sum of CPU time recorded for the Total Runs.
Job Logon
426
Report 01 - Job Details Listing

Recovery Job Is the job, specified as after [workstation#]jobname, that is run if the parent job abends.
Recovery Prompt Is the text of the prompt, specified in the abendprompt field, that is displayed if this job abends. Recovery Type Is the recovery option set in the job definition. It can be set to stop, continue, or rerun.
427
Report 02 - Prompt Listing
Report 02 - Prompt Listing:

TWS for UNIX (AIX)/REPORT2 8.3 (1.7) Report 02 Prompt PROMPT1 PROMPT2 CALLNO CALLOPER PERSON2CALL Message Reply YES when ready to run acc103 and acc104. Have all users logged out? 555-0911 Call ^PERSON2CALL^ at ^CALLNO^ to ensure all time cards have been processed. Lou Armstrong 5 E n d o f R e p o r t * * * * ibm Prompt Message Listing Page 1 03/06/06
Total number of prompts on file: * * * *
The Report 02 output lists the name and the text of the prompts defined in the environment.
428
Report 03 - Calendar Listing
Report 03 - Calendar Listing:

TWS for UNIX (AIX)/REPORT3 8.3 (1.7) Report 03 ibm User Calendar List Page 1 03/06/06
Calendar Type: MONTHEND Description: End of month until end of 2006. Jan 2006 Sun Mon Tue Wed Thu Fri Sat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Apr 2006 Sun Mon Tue Wed Thu Fri Sat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Jul 2006 Sun Mon Tue Wed Thu Fri Sat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Oct 2006 Sun Mon Tue Wed Thu Fri Sat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Feb 2006 Sun Mon Tue Wed Thu Fri Sat . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 May 2006 Sun Mon Tue Wed Thu Fri Sat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Aug 2006 Sun Mon Tue Wed Thu Fri Sat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Nov 2006 Sun Mon Tue Wed Thu Fri Sat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Mar 2006 Sun Mon Tue Wed Thu Fri Sat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Jun 2006 Sun Mon Tue Wed Thu Fri Sat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Sep 2006 Sun Mon Tue Wed Thu Fri Sat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Dec 2006 Sun Mon Tue Wed Thu Fri Sat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
* * * *
E n d o f R e p o r t * * * *
In the output you see highlighted the end of month days selected in calendar MONTHEND.
429
Report 04A - Parameter Listing
Report 04A - Parameter Listing:

TWS for UNIX (AIX)/REPORT4A 8.3 (1.7) Report 4A Parameter Name ACCHOME ACCLOGIN BADEXIT GOODEXIT SCRPATH Contents /usr/local/Tivoli/maestro_adm maestro_adm 99 0 /usr/local/Tivoli/maestro_adm/scripts 5 E n d o f R e p o r t * * * * ibm User Parameter Listing Page 1 03/06/06
Number of Parameters on file: * * * *
The Report 04A output lists the name and the content of the parameters defined in the environment.
430
Report 04B - Resource Listing
Report 04B - Resource Listing:

TWS for UNIX (AIX)/REPORT4B 8.3 (1.7) Report 4B Resource Name #DATTAPES #QUKTAPES #TAPES #JOBSLOTS 4 E n d o f R e p o r t * * * * ibm TWS Resources Listing Number Avail 1 2 2 1024 Page 1 03/06/06
CPU FTAHP FTAWIN8+ MASTER8+ MASTER8+
Description DAT tape units Quick tape units Tape units Job slots
Number of Resources on file:
* * * *
The Report 04B output lists the name, the number of available resources defined in the environment and their description.
431
Report 07 - Job History Listing
Report 07 - Job History Listing:

TWS for UNIX (AIX)/REPORT7 8.3 Report 07 Date Time (1.13) ibm Job History Listing Elapsed CPU Status Page 1 03/08/06
Job Stream Name
Job:MASTER8+#MyJS Runs: Aborted 0 Successful 11 Elapsed Time: Normal 1 Min 1 Max 2 03/03/06 03/03/06 03/03/06 03/03/06 03/03/06 03/03/06 03/05/06 03/06/06 03/06/06 03/06/06 01:46 19:08 19:33 19:37 23:08 05:59 05:59 05:59 21:57 23:16 MASTER8+#JS1 MASTER8+#JS2 MASTER8+#JS3 MASTER8+#JS4 MASTER8+#JS5 MASTER8+#JS_A MASTER8+#JS_G MASTER8+#JS_H MASTER8+#TIMEJ MASTER8+#SLEEPJ Runs: Aborted 0 MASTER8+#JOBS * * * * 1 1 1 1 2 1 1 1 2 1 4 4 4 4 4 4 4 4 4 4 SU SU SU SU SU SU SU SU SU SU
Job:MASTER8+#JOB1 03/06/06 22:22
Successful 1 Elapsed Time: Normal 1 Min 1 Max 1 1 0 SU
E n d o f R e p o r t * * * *
The Report 7 reads the information about job run stored in the database and displays them. The possible states for a job are: AB SU DN for failed jobs for successfully completed jobs for submitted jobs whose state is unknown because neither a successful or a failure message has been received yet.
432
Report 08 - Job Histogram
Report 08 - Job Histogram:

TWS for UNIX (AIX)/REPORT8 8.3 (1.7) ibm Report 08 Job Histogram 03/05/06 14:05 - 03/06/06 14:04 Interval Per Column: 15 minutes 1 4 0 5 Job Name 03/06/06 Stat SU * * * * E n d o f R e p o r t * * * * .*. 1 5 3 5 1 7 0 5 1 8 3 5 2 0 0 5 2 1 3 5 2 3 0 5 0 0 3 5 0 2 0 5 0 3 3 5 0 5 0 5 0 6 3 5 0 8 0 5 0 9 3 5 1 1 0 5 1 2 3 5 1 4 0 4 Page 1 03/06/05
CF05066+.JnextPlan
The output of Report 8 shows the time slots during which the jobs run. The numbers at the top of the job histogram are times, written top-down, for example the first column 1405 means 2:05PM. The time slots when the job run are marked by asterisks when the position of the marker is aligned with a time written top-down, and dots.
433
Report 9B - Planned Production Detail
Report 9B - Planned Production Detail:

TWS for UNIX (AIX) REPORTER 8.3 (1.7) ibm Report 09B Symnew Planned Production Detail For 03/06/06 Estimated Job Name Run Time Pri Start Time Schedule NETAG #EXTERNAL E0000000 Total Total Schedule MYFTA #IWDSKE JOBIWD Total Schedule MYMST #TESTSKE TESTCRO+ NEWTEST Total 0 0 00:00 00:00 10 10 00:00 00:29 10 00:01 10 00:29 10 08:30(03/06/06) 00:29 NETAG#EXTERNAL.E0000000 23:00(03/06/06) 01:00 Until Page 1 03/06/06 Every Limit Dependencies
TESTCROME
Schedule MYMST #FINAL 00:00 10 05:59(03/07/06) JnextPlan 00:01 10 Total 00:01 Total 00:34 * * * * E n d o f R e p o r t * * * *
The output of Report 9B shows what is in plan to run on the selected date in the Tivoli Workload Scheduler environment. The information displayed is taken from the definitions stored in the Tivoli Workload Scheduler database. The output shows the job streams that are planned to run on the 6th of March 2006 with their description, the list of jobs they contain, the time dependencies, repetition rate, and job limit, if set, and the dependency on other jobs or job streams. For example, job stream named iwdske that is planned to run on MYFTA has a follows dependency on job NETAG#EXTERNAL.E0000000 that is planned to run on the network agent named NETAG. The Start Time field in the output of the reports generated by the reptr command shows: A time restriction set in the job stream definition using the at keyword. If the date is enclosed in parenthesis (), for example:
Start Time 06:00(03/20/06)
The time the job stream is planned to run set in the job stream definition using the schedtime keyword. If the date is enclosed in braces {}, for example:
Start Time 06:00{03/20/06}
The time the job stream actually started to run. If the date is not enclosed either in braces or in parenthesis, for example:
Start Time 06:00 03/20/06
434
Report 10B - Actual Production Detail
Report 10B - Actual Production Detail:

TWS for UNIX (AIX) REPORTER 8.3 (1.7) ibm Report 10B Symphony Actual Production Detail For 03/06/06 Estimated Job Name Run Time Priority Start Time Schedule NETAG #EXTERNAL E0000000 Total Schedule MYMST #MONTHSKE GETLOGS Total Schedule MYFTA #IWSKE JOBIWD Total Schedule MYMST #TESTSKE TESTCRO+ NEWTEST Total Schedule MYMST #FINAL JnextPlan Total Total 0 0 00:00 00:02 00:02 00:02 10 10 10 10 00:00 00:29 00:01 00:29 00:30 00:01 00:01 00:01 01:38 * * * * 10 10 10 10 10 00:00 06:01(03/06/06) 00:02 06:01(03/06/06) 00:02 00:02 05:59(03/07/06) 00:00 00:09 0 0 0 HOLD HOLD 0 STUCK #J11613 ABEND HOLD 00:00 06:01(03/06/06) 00:03 06:01(03/06/06) 00:03 00:03 0 #J11612 0 HOLD HOLD SUCC SUCC Page 1 03/07/06
Actual CPU Job Run Time Seconds Number Status EXTRN ERROR
E n d o f R e p o r t * * * *
The output of Report 10B shows states of the scheduling activities currently running across the Tivoli Workload Scheduler network. The information displayed is taken from copy of the Symphony file that is currently used and updated across the scheduling environment. This means that anytime this report command is run during the processing the information displayed reflects the actual status of the planned activity. If you compare this output with the output of Report 9B you see that job stream MONTHSKE has run during the current production day, the 6th of March, but is not in plan to run the next day, the 7th of March. The job stream EXTERNAL instead failed on the network agent NETAG and so the IWSKE job stream that has a follows dependency from EXTERNAL job stream remains in the HOLD state. The job stream TESTSKE, instead, is in state STUCK, that means that operator intervention is needed, because within the job stream run time, job TESTCROME, after having started with job ID J11613, failed in ABEND state causing the depending job NEWTEST to turn into HOLD state.
435
Report 11 - Planned Production Schedule
Report 11 - Planned Production Schedule:

TWS for UNIX (AIX)/REPORT11 8.3 (1.7) Report 11 Planned Production Schedule for FEB 2006 CPU: FTAWIN8+ Num Est Cpu 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 Schedule Jobs Time Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo SCHED1 1 1 * An * between Schedule name and Num Jobs indicates that the schedule has jobs running on other cpus. ---------------------------------------------------------------------------------------------------Estimated Cpu Time Per Day in Seconds Mon Tue Wed Thu Fri Sat Sun 1 0 7 0 14 0 21 0 28 0 TWS for UNIX (AIX)/REPORT11 8.3 (1.7) Report 11 Planned Production Schedule for FEB 2006 CPU: MASTER8+ Num Est Cpu 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 Schedule Jobs Time Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo Tu We Th Fr Sa Su Mo FINAL 1 4 * * * * * * * * * * * * * * * * * * * * * * * * * * * * An * between Schedule name and Num Jobs indicates that the schedule has jobs running on other cpus. ---------------------------------------------------------------------------------------------------Estimated Cpu Time Per Day in Seconds Mon Tue Wed Thu Fri Sat Sun 1 4 7 4 14 4 21 4 28 4 * * * * E n d o f R e p o r t * * * * 8 4 15 4 22 4 2 4 9 4 16 4 23 4 3 4 10 4 17 4 24 4 4 4 11 4 18 4 25 4 5 4 12 4 19 4 26 4 6 4 13 4 20 4 27 4 Page 2 03/08/06 8 0 15 0 22 0 2 0 9 0 16 0 23 0 3 0 10 0 17 0 24 0 4 0 11 1 18 0 25 0 5 0 12 0 19 0 26 0 6 0 13 0 20 0 27 0 Page 1 03/08/065
436

The output of Report 11 shows when the job streams are planned to run during the selected month. In the first line it is displayed the number of jobs the job stream contains, the estimated CPU time used by the job stream to run, and when the job stream is planned to run. In the matrix it is displayed for each day of the selected month the estimated CPU time used by that job stream to run.
437
Report 12 - Cross Reference Report:

The output of Report 12 shows different information according to the flag used when issuing the xref command. In this section you find some samples of output. For each of these sample the corresponding flag used with the xref command is highlighted. xref -when
TWS for UNIX (AIX)/CROSSREF 8.3 (1.7) ibm Page 1 Report 12 Cross Reference Report for the ON, EXCEPT(*) and FREEDAYS(f) options. 03/08/06 CPU: FTAHP WHEN REQUEST Used by the following schedules: TRFINAL
TWS for UNIX (AIX)/CROSSREF 8.3 (1.7) ibm Page 2 Report 12 Cross Reference Report for the ON, EXCEPT(*) and FREEDAYS(f) options. 03/08/06 CPU: FTAWIN8+ WHEN MONTHEND REQUEST Used by the following schedules: SCHED1 SCHED1 , SCHEDDAA
TWS for UNIX (AIX)/CROSSREF 8.3 (1.7) ibm Page 3 Report 12 Cross Reference Report for the ON, EXCEPT(*) and FREEDAYS(f) options. 03/08/06 CPU: MASTER8+ WHEN EVERYDAY REQUEST Used by the following schedules: FINAL TMP * * * * E n d o f R e p o r t * * * *
xref -jobs
TWS for UNIX (AIX)/CROSSREF 8.3 (1.7) ibm Report 12 Cross Reference Report for Job Names. CPU: FTAWIN8+ Job Name SCHEDDDD Exists in Schedules SCHED1 Page 4 03/08/06
TWS for UNIX (AIX)/CROSSREF 8.3 (1.7) ibm Report 12 Cross Reference Report for Job Names. CPU: MASTER8+ Job Name JnextPlan JOB1 Exists in Schedules FINAL TMP * * * * E n d o f R e p o r t * * * *
Page 5 03/08/06
438

xref -resource
TWS for UNIX (AIX)/CROSSREF 8.3 (1.7) ibm Report 12 Cross Reference Report for Resource Users. CPU: FTAWIN8+ Resource QUKTAPES(N/F) Used by the following: SCHED1 Page 8 03/08/06
TWS for UNIX (AIX)/CROSSREF 8.3 (1.7) ibm Report 12 Cross Reference Report for Resource Users. CPU: MASTER8+ Resource TAPES(N/F) Used by the following: TMP * * * * E n d o f R e p o r t * * * *
Page 9 03/08/06
xref -prompts
TWS for UNIX (AIX)/CROSSREF 8.3 (1.7) ibm Report 12 Cross Reference Report for Prompt Dependencies. CPU: FTAWIN8+ Prompt User defined text Used by the following: SCHED1 Page 6 03/08/06
TWS for UNIX (AIX)/CROSSREF 8.3 (1.7) ibm Report 12 Cross Reference Report for Prompt Dependencies. CPU: MASTER8+ Prompt BADEXIT GOODEXIT User defined text Used by the following: FTAWIN8+#SCHED1 FTAWIN8+#SCHED1 , TMP TMP * * * * E n d o f R e p o r t * * * *
Page 7 03/08/06
xref -files
TWS for UNIX (AIX)/CROSSREF 8.3 (1.7) ibm Report 12 Cross Reference Report for File Dependencies. CPU: MASTER8+ File Name /root/MY_FILE.sh Used by the following: FTAWIN8+#SCHED1 , TMP * * * * E n d o f R e p o r t * * * * Page 10 03/08/06
439
Report extract programs

Data extraction programs are used to generate several of the Tivoli Workload Scheduler reports. The programs are listed in Table 53:
Table 53. Report extract programs. Report extract program jbxtract prxtract caxtract paxtract rextract r11xtr xrxtrct Description Used to generate Report 01 - Job Details Listing and for Report 07 - Job History Listing Used to generate Report 02 - Prompt Listing Used to generate Report 03 - Calendar Listing Used to generate Report 04A - Parameters Listing Used to generate Report 04B - Resource Listing Used to generate Report 11 - Planned Production Schedule Used to generate Report 12 - Cross Reference Report
The output of the extract programs is controlled by the MAESTRO_OUTPUT_STYLE variable, which defines how long object names are handled. For more information on the MAESTRO_OUTPUT_STYLE variable, refer to Command descriptions on page 414.
440
jbxtract
jbxtract
Extracts information about jobs from the database.
Syntax
jbxtract [-v | -u] [-j job] [-c wkstat] [-f date -t date] [-o file]
Arguments
-v -u -j job Displays the command version and exits. Displays command usage information and exits. Specifies the job for which extraction is performed. The default is all jobs.
-c wkstat Specifies the workstation of jobs for which extraction is performed. The default is all workstations. -f date Specifies to print job history from this date forward. Enter the date as yyyymmdd. The default is the earliest available date. -t date Specifies to print job history up to this date. Enter the date as yyyymmdd. The default is the most recent date. -o file Specifies the output file. The default is stdout.
Results
The MAESTRO_OUTPUT_STYLE variable specifies the output style for long object names. Set the variable to LONG to use full length (long) fields for object names. If the variable is not set, or is set to anything other than LONG, long names are truncated to eight characters and a plus sign. For example: A1234567+. Each job record contains tab-delimited, variable length fields. The fields are described Table 54.
Table 54. Jbxtract output fields Field 1 2 3 4 5 6 7 8 9 10 11 12 13 Description workstation name job name job script file name job description recovery job name recovery option (0=stop, 1=rerun, 2=continue) recovery prompt text auto-documentation flag (0=disabled, 1=enabled) job login user name job creator user name number of successful runs number of abended runs total elapsed time of all job runs Max Length (bytes) 16 16 4096 65 16 5 64 5 36 36 5 5 8
441
jbxtract
Table 54. Jbxtract output fields (continued) Field 14 15 16 17 18 19 20 21 22 23 24 25 Description total cpu time of all job runs average elapsed time last run date (yymmdd) last run time (hhmm) last cpu seconds last elapsed time maximum cpu seconds maximum elapsed time maximum run date (yymmdd) minimum cpu seconds minimum elapsed time minimum run date (yymmdd) Max Length (bytes) 8 8 8 8 8 8 8 8 8 8 8 8
Examples
To extract information about job myjob on workstation main and direct the output to the file jinfo, run the following command:
jbxtract -j myjob -c main -o jinfo
442
prxtract
prxtract
Extracts information about prompts from the database.
Syntax
prxtract [-v | -u] [-o file]
Arguments
-v -u -o file Displays the command version and exits. Displays command usage information and exits. Specifies the output file. The default is stdout.
Results
Each prompt record contains tab-delimited, variable length fields. The fields are described in Table 55.
Table 55. Prxtract output fields Field 1 2 Description prompt name prompt value Max Length (bytes) 8 200
Examples
To extract information about all prompt definitions and direct the output to the file prinfo, run the following command:
prxtract -o prinfo
443
caxtract
caxtract
Extracts information about calendars from the database.
Syntax
caxtract [-v | -u] [-o file]
Arguments
Results
Each calendar record contains tab-delimited, variable length fields. The fields are described in Table 56.
Table 56. Caxtract output fields Field 1 2 Description calendar name calendar description Max Length (bytes) 8 64
Examples
To extract information about all calendar definitions and direct the output to the file cainfo, run the following command:
caxtract -o cainfo
444
paxtract
paxtract
Extracts information about parameters from the database.
Syntax
paxtract [-v | -u] [-o file]
Arguments
Results
Each parameter record contains tab-delimited, variable length fields. The fields are described in Table 57.
Table 57. Paxtract output fields Field 1 2 Description parameter name parameter value Max Length (bytes) 8 64
Examples
To extract information about all parameter definitions and direct the output to the file painfo, run the following command:
paxtract -o painfo
445
rextract
rextract
Extracts information about resources from the database.
Syntax
rextract [-v | -u] [-o file]
Arguments
Results
Each resource record contains tab-delimited, variable length fields. The fields are described in Table 58.
Table 58. Rextract output fields Field 1 2 3 4 Description workstation name resource name total resource units resource description Max Length (bytes) 8/16 8 4 72
Examples
To extract information about all resource definitions and direct the output to the file reinfo, run the following command:
rextract -o reinfo
446
r11xtr
r11xtr
Extracts information about job streams from the database.
Syntax
r11xtr [-v | -u] [-m mm[yyyy]] [-c wkstat] [-o file] [-s jstream_name]
Arguments
-v -u Displays the program version and exits. Displays program usage information and exits.
-m mm[yy] Specifies the month (mm) and, optionally, the year (yy) of the job streams. The default is the current month and year. -c wkstat Specifies the workstation to be reported. The default is all workstations. -s jstream_name Specifies the name of the job stream in which the jobs run. The default is all job streams. -o file Specifies the output file. The default is stdout.
Results
The MAESTRO_OUTPUT_STYLE variable specifies the output style for long object names. Set the variable to LONG to use full length (long) fields for object names. If the variable is not set, or is set to anything other than LONG, long names are truncated to eight characters and a plus sign. For example: A1234567+. Each job stream record contains tab-delimited, variable length fields. The fields are described in Table 59.
Table 59. R11xtr output fields Field 1 2 3 4 5 6 7 Description workstation name job stream name job stream date (yymmdd) estimated cpu seconds multiple workstation flag (* means some jobs run on other workstations) number of jobs day of week (Su, Mo, Tu, We, Th, Fr, Sa) Max Length (bytes) 16 16 6 6 1 4 2
Examples
To extract information about job streams on June 2004 for workstation main, run the following command:
r11xtr -m 0604 -c main
447
r11xtr
To extract information about job streams on June of this year for all workstations, and direct the output to file r11out, run the following command:
r11xtr -m 06 -o r11out
448
xrxtrct
xrxtrct
Extracts information about cross-references from the database.
Syntax
xrxtrct [-v | -u]
Arguments
Results
The MAESTRO_OUTPUT_STYLE variable specifies the output style for long object names. Set the variable to LONG to use full length (long) fields for object names. If the variable is not set, or is set to anything other than LONG, long names are truncated to eight characters and a plus sign. For example: A1234567+. The command output is written to eight files, xdep_job, xdep_sched, xfile, xjob, xprompt, xresources, xsched, and xwhen. xdep_job file: The xdep_job file contains two record types. The first contains information about jobs and job streams that are dependent on a job. Each dependent job and job stream record contains the fixed length fields, with no delimiters. The fields are described in Table 60.
Table 60. Xdep_job output fields Field 1 2 3 4 5 6 7 8 9 10 11 12 13 Description 03 workstation name job name job stream name not used dependent job stream workstation name dependent job stream name dependent job workstation name dependent job name not used not used not used end-of-record (null) Length (bytes) 2 16 40 16 240 16 16 16 40 6 6 8 1
The second record type contains information about jobs and job streams that are dependent on an internetwork dependency. Each dependent job and job stream record contains fixed length fields, with no delimiters. The fields are described in Table 61.
Table 61. Xdep_job output fields (continued) Field 1 Description 08 Length (bytes) 2
449
xrxtrct
Table 61. Xdep_job output fields (continued) (continued) Field 2 3 4 5 6 7 8 9 10 11 12 Description workstation name job name not used dependent job stream workstation name dependent job stream name dependent job workstation name dependent job name not used not used not used end-of-record (null) Length (bytes) 16 120 128 16 16 16 40 6 6 8 1
xdep_sched file: The xdep_sched file contains information about job streams that are dependent on a job stream. Each dependent job stream record contains fixed length fields, with no delimiters. The fields are described in Table 62.
Table 62. Xdep_sched output fields Field 1 2 3 4 5 6 7 8 9 10 11 12 Description 02 workstation name job stream name not used dependent job stream workstation name dependent job stream name not used not used not used not used not used end-of-record (null) Length (bytes) 2 16 16 248 16 16 8 8 6 6 8 1
xfile file: The xfile file contains information about jobs and job streams that are dependent on a file. Each record contains fixed length fields, with no delimiters. The fields are described in Table 63.
Table 63. Xfile output fields Field 1 2 3 4 5 Description 07 workstation name file name dependent job stream workstation name dependent job stream name Length (bytes) 2 16 256 16 16
450
xrxtrct
Table 63. Xfile output fields (continued) Field 6 7 8 9 10 11 Description dependent job workstation name dependent job name not used not used not used end-of-record (null) Length (bytes) 16 40 6 6 8 1
xjob file: The xjob file contains information about the job streams in which each job appears. Each job record contains fixed length fields, with no delimiters. The fields are described in Table 64.
Table 64. Xjob output fields Field 1 2 3 4 5 6 7 8 9 10 11 12 Description 04 workstation name job name not used job stream workstation name job stream name not used not used not used not used not used end-of-record (null) Length (bytes) 2 16 40 248 16 16 8 8 6 6 8 1
xprompt file: The xprompt file contains information about jobs and job streams that are dependent on a prompt. Each prompt record contains fixed length fields, with no delimiters. The fields are described in Table 65.
Table 65. Xprompts output fields Field 1 2 3 4 5 6 7 8 9 10 Description 05 workstation name prompt name or text not used dependent job stream workstation name dependent job stream name dependent job workstation name dependent job name not used not used Length (bytes) 2 16 20 236 16 16 16 40 6 6
451
xrxtrct
Table 65. Xprompts output fields (continued) Field 11 12 Description not used end-of-record (null) Length (bytes) 8 1
xresource file: The xresource file contains information about jobs and job streams that are dependent on a resource. Each resource record contains fixed length fields, with no delimiters. The fields are described in Table 66.
Table 66. Xresource output fields Field 1 2 3 4 5 6 7 8 9 10 11 12 Description 06 workstation name resource name not used dependent job stream workstation name dependent job stream name dependent job workstation name dependent job name units allocated not used not used end-of-record (null) Length (bytes) 2 16 8 248 16 16 16 40 6 6 8 1
xsched file: The xsched file contains information about job streams. Each job stream record contains fixed length fields, with no delimiters. The fields are described in Table 67.
Table 67. Xsched output fields Field 1 2 3 4 5 6 7 8 9 10 11 12 Description 00 workstation name job stream name not used workstation name (same as 2 above) job stream name (same as 3 above) not used not used not used not used not used end-of-record (null) Length (bytes) 2 16 16 248 16 16 8 8 6 6 8 1
xwhen file: The xwhen file contains information about when job streams will run. Each job stream record contains the following fixed length fields, with no
452
xrxtrct
delimiters. The fields are described in Table 68.
Table 68. Xwhen output fields Field 1 2 3 4 5 6 7 8 9 10 11 12 13 Description 01 workstation name ON/EXCEPT name or date except flag (*=EXCEPT) not used workstation name job stream name not used not used not used offset num offset unit end-of-record (null) Length (bytes) 2 16 8 1 247 16 16 8 8 6 6 8 1
Examples
To extract information about all cross-references, run the following command:
xrxtrct
453
xrxtrct
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Additional reports available on the Tivoli Dynamic Workload Console

These reports can be run only from the Tivoli Dynamic Workload Console. This section provides an overview. Refer to the Tivoli Dynamic Workload Console online help for details.
Historical reports
The following table summarizes the historical reports in terms of their: v Functionality v Selection criteria v Output content options
Table 69. Summary of historical reports Report name Job run history Description Corresponds to Report 07. Selection criteria Output content options You can select from the following: v Job name v Workstation (job) v Job stream name v Workstation (job stream) v Scheduled time v Actual start time v Estimated duration v Actual duration v Job number v Started late (delay) v Ended late (delay) v Status v Return code v CPU consumption (not available on Windows workstations) v Logon user v Rerun type v Iteration number v Return code The output is in table view.
v Job name, job stream name, workstation name, and workstation Collects historical job name (job stream). execution data Each field can be during a time specified using a interval. Helps you wildcard and find: commas to add v Jobs ended in error more values. v Late jobs v Status (Success, v Missed deadlines Error, Canceled, v Long duration Unknown) and v Rerun indicators external status. for reruns v Delay indicators v Other historical v Job execution information. interval v Include/Exclude Note: The report rerun iterations does not include jobs that were submitted using an alias name.
454
xrxtrct
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 69. Summary of historical reports (continued) Report name Job run statistics Description Corresponds to Report 01. Selection criteria Output content options You can select from the following: v Job details: Job name Workstation name Logon user Job creator Description Script v Job statistics: Total runs (divided in Successful and Error) Total of runtime exceptions (Started late, Ended late, Long duration) Minimum and maximum elapsed and CPU times (for successful runs only) Average duration (for successful runs only) CPU consumption (not available on Windows workstations) v Report format: Charts view (pie, bar) Table view Include table of contents by job or by workstation
v Job name, workstation name, and user login. Collects job execution Each field can be statistics. Helps you specified using a find: wildcard and v Success/error rates commas to add v Minimum and more values. maximum elapsed v Percentage of jobs and CPU times in Success, Error, v Average duration Started late, Ended v Late and long late, and Long duration statistics duration v Total runs and Note: The report total reruns does not include jobs that were submitted using an alias name.
455
xrxtrct
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 69. Summary of historical reports (continued) Report name Workstation workload summary Description Selection criteria Output content options You can select from the following: v Workstation information granularity arranged by: Hour Day Production day v Information aggregation options: Provide cumulative and aggregated workstation summary information for all or a desired subset of workstations v Report format: Charts view (bar, line) Table view Include table of contents by date or by workstation
Provides data on the v Workstation workload in terms of names. Each field the number of jobs can be specified that have run on using a wildcard each workstation. and commas to Helps making the add more values. necessary capacity v Date ranges or planning adjustments specific days for (workload modeling, workload filtering. and workstation v Relative time tuning). intervals (allows to reuse the same report task for running each day and getting the report of the production of the day before)
456
xrxtrct
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 69. Summary of historical reports (continued) Report name Workstation workload runtimes Description Corresponds to Report 08. Selection criteria Output content options You can select from the following: v Information grouped by: Workstation Run date Production day Can be ordered by rerun iteration v Job information: Job name Workstation name Workstation name (Job stream) Job stream name Scheduled time Actual start time Actual duration Status Rerun iteration v Report format: Charts view (GANNT) Table view Include table of contents Limit the number of jobs in each single chart
v Job and workstation names. Each field can be Provides data on the specified using a job runs (time and wildcard and duration) on the commas to add workstations. Helps more values. making the necessary v Job execution capacity planning interval adjustments v Daily time (workload modeling, intervals and workstation tuning). Note: The report does not include jobs that were submitted using an alias name.
Custom SQL
A wizard helps you define your custom SQL query (only on the database views which you are authorized to access). The resulting report has a table with the column name as specified in the SELECT part of the SQL statement.
All reports are created in HTML (PDF) or CSV format. The heading of the output contains the SQL statement. The body contains the report charts in the selected form. You must have the appropriate security file authorizations for report objects to run these reports (granted by default to the tws_user on fresh Version 8.4 installations).
457
xrxtrct
| | | | |
Production reports
The following table summarizes the historical reports in terms of their: v Functionality v Selection criteria v Output content options
458
xrxtrct
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 70. Summary of production reports Report name Actual production details Description Corresponds to Report 10B. Provides data on current and archived plans. Selection criteria Output content options
v Job stream name You can select from the following: and workstation name (job stream). v Job stream information: v Job name, Job stream name workstation name Workstation (job), job stream name name (job), job Priority stream workstation Limit (job) Total jobs v Priority Status Internal status Scheduled start time Latest start time Actual start time Estimated deadline time Estimated duration Actual duration CPU time v Job information: Job name Workstation name Priority Status Internal status Is every job Is rerun job CPU time Job log Estimated start time Latest start time Actual start time Estimated deadline time Estimated duration Actual duration Rerun code Job number Dependencies v Report format: Flat format CSV separator
459
xrxtrct
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 70. Summary of production reports (continued) Report name Planned production details Description Corresponds to Report 9B. Selection criteria Output content options
v Job stream name You can select from the following: and workstation name (job stream). v Job Stream Provides data on trial v Job name, information: and forecast plans. Job stream name workstation name Workstation (job), job stream name name (job), job Priority stream workstation Limit (job) Total jobs v Priority Scheduled start time Latest start time Estimated deadline time v Job information: Job name Workstation name Priority Is every job Scheduled start time Latest start time Estimated deadline time Estimated duration Dependencies v Report format: Flat format CSV separator
You must have the appropriate security file authorizations for report objects to run these reports (granted by default to the tws_user on fresh Version 8.4 installations).
460
Chapter 12. Managing time zones

Tivoli Workload Scheduler supports different time zones. Enabling time zones provides you with the ability to manage your workload across a multiple time zone environment. Both the 3-character and the variable length notations are supported. The variable length notation format is area/city, for example Europe/Paris as equivalent to ECT (European Central Time). The 3-character notation is supported for backward compatibility with previous versions of Tivoli Workload Scheduler. At the end of this chapter are two sections each containing a time zone list table. The first shows for each 3-character format time zone name that was already in use and the corresponding default long name notation assigned. The second contains the complete set of time zones with long name notation. The chapter is divided in the following sections: v What is new about managing time zones v Enabling time zone management v How Tivoli Workload Scheduler manages time zones on page 462 v Moving to daylight saving time on on page 464 v Moving to daylight saving time off on page 464 v General rules on page 464 v Backward compatibility time zone table on page 465 v Complete table of time zones with variable length notation on page 466 | | | | |
What is new about managing time zones

New time zone labels have been added for use with this product version, while all SystemV labels are no longer available. The new labels can be used only on this version of Tivoli Workload Scheduler. The new labels are indicated by revision bars in Table 72 on page 466.
Enabling time zone management

You can enable or disable the management of time zones by modifying the setting assigned to the global option enTimeZone on the master domain manager using the optman command line. The setting takes effect after the next JnextPlan is run. These are the available settings: | | | | | | no Disable time zone management. This means that the values assigned to all timezone keywords in the definitions are ignored. All the at, until, and deadline time restrictions are managed individually by each fault-tolerant agent, including the master and the domain managers, thus ignoring the time zone of the agent scheduling the job or job stream. As a consequence, when different time zones are involved:
461
Enabling time zone management

| | | | | | | yes v For jobs, incorrect information is displayed about these time dependencies when looked at from an agent other than the job owner. This has no impact however on the scheduling process of the job. v For job streams, the impact is that each agent processes the time dependencies by its own time zone, and therefore at different times, causing jobs of the same job stream, but defined on a different agent, to run at a different time. Enable time zone management. This means that the values assigned to the timezone settings are used to calculate the time when the jobs and job streams run on the target workstations.
By default the enTimeZone option is set to yes. For more details on how to use the optman command line to manage global options on the master domain manager, refer to the IBM Tivoli Workload Scheduler Planning and Installation Guide.
How Tivoli Workload Scheduler manages time zones

When the time zone is enabled, you can use time zone settings in workstations, jobs, and job streams definitions. While performing plan management activities, Tivoli Workload Scheduler converts the value set for the time zones into objects definitions. The conversions are applied in this order: 1. When the job stream instances are added to the preproduction plan, the time zone set in the job stream definitions is converted into the GMT time zone and then the external follows dependencies are resolved. 2. When the production plan is created or extended, the job stream instances are assigned to workstations where the instance is scheduled to run and the time zone is converted from GMT into the time zone set in the target workstation definition. This is why if you use the conman showsched or conman showjobs commands to see the information about scheduled jobs and job streams you see the time zone values expressed using the time zone set on the workstation where the job or job stream is planned to run. Based on the level of Tivoli Workload Scheduler you installed on the master domain manager you can decide how the product manages time zones while processing, and precisely: If you installed Tivoli Workload Scheduler version 8.3 or if you installed Tivoli Workload Scheduler version 8.3 and Fix Pack 01 and you set the enLegacyStartOfDayEvaluation to no The value assigned to the startOfDay option on the master domain manager is not converted into the local time zone set on each workstation across the network. This means that if the startOfDay option is set to 0600 on the master domain manager, it is 0600 in the local time zone set on each workstation in the network. This also means that the processing day begins at the same hour on all workstations. Figure 14 on page 463 shows you how the start of day, set to 0600 on the master domain manager, is applied to the different time zones on the two fault-tolerant agents. The same time conversion is applied to the job stream JS1 scheduled to run on the three machines and containing an at time dependency at 0745 US/Central time zone. The time frame that identifies
462

the new processing day is greyed out in Figure 14.
start of day 6 a.m. US/Eastern
Fault-tolerant agent 2
+ 2h US/Eastern TZ (GMT-5) JS1
Master Domain Manager
JS1 7:45 a.m.
US/Central TZ(GMT-7)
JS1 JS1 - 4h US/Samoa TZ (GMT-11)
start of day 6 a.m. US/Samoa
start of day 6 a.m. US/Central
Figure 14. Example when start of day conversion is not applied
If you installed Tivoli Workload Scheduler version 8.3 and Fix Pack 01 and you set the enLegacyStartOfDayEvaluation to yes The value assigned to the startOfDay option on the master domain manager is converted into the local time zone set on each workstation across the network. This means that if the startOfDay option is set to 0600 on the master domain manager, it is converted on each workstation into the corresponding time according to the local time zone set on that workstation. This also means that the scheduling day begins at the same moment, but not necessarily at the same hour, on all workstations in the network. Figure 15 shows you how the start of day, set to 0600 on the master domain manager, is applied to the different time zones on the two fault-tolerant agents. It also shows how the timing of the job stream JS1 scheduled to run on the three machines and containing an at time dependency at 0730 US/Central time zone is not modified because of the startOfDay conversion. The time frame that identifies the new processing day is greyed out in Figure 15.
+ 2h US/Eastern TZ (GMT-5) JS1
Master Domain Manager
JS1 7:45 a.m.
US/Central TZ(GMT-7)
JS1 JS1 - 4h
start of day 8 a.m. US/Eastern start of day 6 a.m. US/Central start of day 2 a.m. US/Samoa
US/Samoa TZ (GMT-11)
Figure 15. Example when start of day conversion is applied
463

Note: Starting from version 8.3 there is no linking between the time set for the startOfDay and the moment when JnextPlan is run. JnextPlan can be run at any time and the startOfDay indicates only the moment when the new processing day starts. By default, on the systems where Tivoli Workload Scheduler version 8.3 and Fix Pack 01 are installed, the enLegacyStartOfDayEvaluation global option is set to no. For more details on how to use the optman command line to manage global options on the master domain manager, refer to the IBM Tivoli Workload Scheduler Planning and Installation Guide.
Moving to daylight saving time on

Tivoli Workload Scheduler manages the moving to daylight saving time (DST) when generating the production plan. This means that the date and time to run assigned to jobs and job streams in the plan is already converted into the corresponding date and time with DST on. The following example explains how Tivoli Workload Scheduler applies the time conversion when JnextPlan is run to generate or extend the production plan while the time moves to DST. If DST is switched on at 3:00 p.m. then all job streams scheduled to start between 2:00 and 2:59 are set to start at 3:00. The reason for doing this is that at 2:00 the clock time is moved one hour ahead because DST is switched on, and so all job streams planned to start between 2:00 and 2:59, if free from dependencies, start immediately because 3:00 is later than their scheduled start time.
Moving to daylight saving time off

Moving to daylight saving time (DST) off, the clock time is set to one hour earlier with respect to the DST time. To maintain consistency with production planning criteria, Tivoli Workload Scheduler ensures that the job stream instances planned to run during the hour before the time shift backward are run only one time. Because the time conversion is applied when generating or extending the production plan, the date and time to run assigned to jobs and job streams in the plan is already converted into the corresponding date and time with DST off.
General rules
When the time zone is enabled in the Tivoli Workload Scheduler environment, regardless of which value is set for the enLegacyStartOfDayEvaluation option, some general rules are applied. These rules are now described divided by topic: Identifying default time zone settings for jobs and job streams: Within a job stream definition you can set a time zone for the entire job stream and for the jobs contained in the job stream. These time zones can differ from each other. To manage all possible time zone settings the time zone conversion is made respecting the following criteria: v If a time zone is not set for a job within a job stream, then that job inherits the time zone set on the workstation where the job is planned to run. v If a time zone is not set for a job stream, then the time zone set is the one set on the workstation where the job stream is planned to run.
464
General rules
v If none of the mentioned time zones is set, then the time zone used is the one set on the master domain manager. Choosing the correct time zone for the workstations: To avoid inconsistencies, before enabling the time zone management across the Tivoli Workload Scheduler network, make sure that, if a time zone is set in the workstation definition, it is the same as the time zone set on the system where the workstation is installed. Default time zone setting for the master domain manager: If a time zone is not set in the master domain manager definition, it inherits the time zone set on the system where the master domain manager is installed. To see which time zone is set on the master domain manager you can run the following command:
conman showcpu;info
Using the time zone on extended agents: Extended agents inherit the time zone of the master domain manager. Displaying time zone setting in production for an AT time dependency: If you use conman commands sj or ss to display a job or job stream having an at time dependency with a time zone set, the time specified for the at dependency is automatically converted into the time zone set on the workstation from where the conman command is run. Applying an offset to a time zone when scheduling a job stream: If you submit in production a job stream specifying an at dependency with an offset of +n days, then Tivoli Workload Scheduler first adds the offset to the date and then converts the time zone set in the at dependency. This is important especially when referring to the time when daylight saving time moving occurs. As a best practice, if you enable time zone management, set a time zone on each workstation of your Tivoli Workload Scheduler network.
Backward compatibility time zone table

Table 71 shows for each 3-character format time zone that was in use with the previous versions of the product, the default long name notation assigned. The time zone name is case sensitive.
Table 71. Backward compatibility time zone table Long Name GMT UTC Europe/Paris Europe/Istanbul Africa/Cairo Asia/Riyadh Europe/Paris Asia/Yerevan Asia/Karachi Short Name GMT UTC ECT EET ART EAT MET NET PLT Description Greenwich Mean Time Universal Coordinated Time European Central Time Eastern European Time (Arabic) Egypt Standard Time Eastern African Time Middle Europe Time Near East Time Pakistan Lahore Time Relative to GMT GMT GMT GMT+1:00 GMT+2:00 GMT+2:00 GMT+3:00 GMT+1:00 GMT+4:00 GMT+5:00
465
Backward compatibility time zone table

Table 71. Backward compatibility time zone table (continued) Long Name Asia/Calcutta Asia/Dacca Asia/Bangkok Asia/Shanghai Asia/Tokyo Australia/Darwin Australia/Sydney Pacific/Guadalcanal Pacific/Fiji Pacific/Apia Pacific/Honolulu America/Anchorage America/Los_ Angeles America/Phoenix America/Denver America/Chicago America/New_York America/ Indianapolis America/Caracas America/St_Johns America/Buenos_ Aires America/Sao_Paulo Atlantic/Cape_Verde Short Name IST BST VST CTT JST ACT AET SST NST MIT HST AST PST PNT MST CST EST IET PRT CNT AGT BET CAT Description India Standard Time Bangladesh Standard Time Vietnam Standard Time China Taiwan Time Japan Standard Time Australia Central Time Australia Eastern Time Solomon Standard Time New Zealand Standard Time Midway Islands Time Hawaii Standard Time Alaska Standard Time Pacific Standard Time Phoenix Standard Time Mountain Standard Time Central Standard Time Eastern Standard Time Indiana Eastern Standard Time Puerto Rico and US Virgin Islands Time Canada Newfoundland Time Argentina Standard Time Brazil Eastern Time Central African Time Relative to GMT GMT+5:30 GMT+6:00 GMT+7:00 GMT+8:00 GMT+9:00 GMT+9:30 GMT+10:00 GMT+11:00 GMT+12:00 GMT-11:00 GMT-10:00 GMT-9:00 GMT-8:00 GMT-7:00 GMT-7:00 GMT-6:00 GMT-5:00 GMT-5:00 GMT-4:00 GMT-3:30 GMT-3:00 GMT-3:00 GMT-1:00
Complete table of time zones with variable length notation

Table 72 shows all the supported time zones expressed with variable length notation, their descriptions, and their offset with respect to GMT. | | | | | | The new time zone labels that can be used with this version of the product are shown with revision bars. Note that : v Time zone names are case sensitive. v The SystemV time zones are no longer supported. v The new names are not supported by earlier Tivoli Workload Scheduler versions than 8.4.
Table 72. Variable length notation time zones list Long Name ACT AET Africa/Abidjan Description Central Standard Time (Northern Territory) Eastern Standard Time (New South Wales) Greenwich Mean Time Relative to GMT GMT+9 GMT+11 GMT
466

Table 72. Variable length notation time zones list (continued) Long Name Africa/Accra Africa/Addis_Ababa Africa/Algiers Description Greenwich Mean Time Eastern African Time Central European Time Eastern African Time Eastern African Time Greenwich Mean Time Western African Time Greenwich Mean Time Greenwich Mean Time Central African Time Western African Time Central African Time Eastern European Time Western European Time Central European Time Greenwich Mean Time Greenwich Mean Time Eastern African Time Eastern African Time Western African Time Western European Time Greenwich Mean Time Central African Time Central African Time South Africa Standard Time Eastern African Time Eastern African Time Central African Time Western African Time Western African Time Western African Time Greenwich Mean Time Western African Time Central African Time Central African Time Western African Time Central African Time South Africa Standard Time South Africa Standard Time Relative to GMT GMT GMT+3 GMT+1 GMT+3 GMT+3 GMT GMT+1 GMT GMT GMT+2 GMT+1 GMT+2 GMT+2 GMT GMT+1 GMT GMT GMT+3 GMT+3 GMT+1 GMT GMT GMT+2 GMT+2 GMT+2 GMT+3 GMT+3 GMT+2 GMT+1 GMT+1 GMT+1 GMT GMT+1 GMT+2 GMT+2 GMT+1 GMT+2 GMT+2 GMT+2
Africa/Asmara Africa/Asmera Africa/Bamako Africa/Bangui Africa/Banjul Africa/Bissau Africa/Blantyre Africa/Brazzaville Africa/Bujumbura Africa/Cairo Africa/Casablanca Africa/Ceuta Africa/Conakry Africa/Dakar Africa/Dar_es_Salaam Africa/Djibouti Africa/Douala Africa/El_Aaiun Africa/Freetown Africa/Gaborone Africa/Harare Africa/Johannesburg Africa/Kampala Africa/Khartoum Africa/Kigali Africa/Kinshasa Africa/Lagos Africa/Libreville Africa/Lome Africa/Luanda Africa/Lubumbashi Africa/Lusaka Africa/Malabo Africa/Maputo Africa/Maseru Africa/Mbabane
467

Table 72. Variable length notation time zones list (continued) Long Name Africa/Mogadishu Africa/Monrovia Africa/Nairobi Africa/Ndjamena Africa/Niamey Africa/Nouakchott Africa/Ouagadougou Africa/Porto-Novo Africa/Sao_Tome Africa/Timbuktu Africa/Tripoli Africa/Tunis Africa/Windhoek AGT America/Adak America/Anchorage America/Anguilla America/Antigua America/Araguaina Description Eastern African Time Greenwich Mean Time Eastern African Time Western African Time Western African Time Greenwich Mean Time Greenwich Mean Time Western African Time Greenwich Mean Time Greenwich Mean Time Eastern European Time Central European Time Western African Time Argentine Time Hawaii-Aleutian Standard Time Alaska Standard Time Atlantic Standard Time Atlantic Standard Time Brazil Time Argentine Time Argentine Time Argentine Time Argentine Time Argentine Time Argentine Time Argentine Time Argentine Time Argentine Time Argentine Time Argentine Time Atlantic Standard Time Relative to GMT GMT+3 GMT GMT+3 GMT+1 GMT+1 GMT GMT GMT+1 GMT GMT GMT+2 GMT+1 GMT+2 GMT-3 GMT-10 GMT-9 GMT-4 GMT-4 GMT-2 GMT-3 GMT-3 GMT-3 GMT-3 GMT-3 GMT-3 GMT-3 GMT-3 GMT-3 GMT-3 GMT-3 GMT-4
| | | | | | | | | | | | | | | | | | | | | |
America/Argentina/ Buenos_Aires America/Argentina/ Catamarca America/Argentina/ ComodRivadavia America/Argentina/ Cordoba America/Argentina/ Jujuy America/Argentina/ La_Rioja America/Argentina/ Mendoza America/Argentina/ Rio_Gallegos America/Argentina/ San_Juan America/Argentina/ Tucuman America/Argentina/ Ushuaia America/Aruba
468

Table 72. Variable length notation time zones list (continued) Long Name America/Asuncion Description Paraguay Time Eastern Standard Time Hawaii-Aleutian Standard Time Brazil Time Atlantic Standard Time Brazil Time Central Standard Time Eastern Standard Time Amazon Standard Time Colombia Time Mountain Standard Time Argentine Time Mountain Standard Time Central Standard Time Venezuela Time Argentine Time French Guiana Time Eastern Standard Time Central Standard Time Mountain Standard Time Argentine Time Relative to GMT GMT-3 GMT-5 GMT-10 GMT-3 GMT-4 GMT-3 GMT-6 GMT-5 GMT-4 GMT-5 GMT-7 GMT-3 GMT-7 GMT-6 GMT-4 GMT-3 GMT-3 GMT-5 GMT-6 GMT-7 GMT-3 GMT-5 GMT-6 GMT-3 GMT-4 GMT GMT-8 GMT-7 GMT-7 GMT-5 GMT-4 GMT-7 GMT-5 GMT-6 GMT-8 GMT-5 GMT-3 GMT-4
| |
America/Atikokan America/Atka America/Bahia America/Barbados America/Belem America/Belize
America/Blanc-Sablon America/Boa_Vista America/Bogota America/Boise America/Buenos_Aires America/Cambridge_ Bay America/Cancun America/Caracas America/Catamarca America/Cayenne America/Cayman America/Chicago America/Chihuahua America/Cordoba
America/Coral_Harbour Eastern Standard Time America/Costa_Rica America/Cuiaba America/Curacao Central Standard Time Amazon Standard Time Atlantic Standard Time
America/Danmarkshavn Greenwich Mean Time America/Dawson Pacific Standard Time
America/Dawson_Creek Mountain Standard Time America/Denver America/Detroit America/Dominica America/Edmonton America/Eirunepe America/El_Salvador America/Ensenada America/Fort_Wayne America/Fortaleza America/Glace_Bay Mountain Standard Time Eastern Standard Time Atlantic Standard Time Mountain Standard Time Acre Time Central Standard Time Pacific Standard Time Eastern Standard Time Brazil Time Atlantic Standard Time
469

Table 72. Variable length notation time zones list (continued) Long Name America/Godthab America/Goose_Bay America/Grand_Turk America/Grenada America/Guadeloupe America/Guatemala America/Guayaquil America/Guyana America/Halifax America/Havana America/Hermosillo America/Indiana/ Indianapolis America/Indiana/Knox America/Indiana/ Marengo Description Western Greenland Time Atlantic Standard Time Eastern Standard Time Atlantic Standard Time Atlantic Standard Time Central Standard Time Ecuador Time Guyana Time Atlantic Standard Time Central Standard Time Mountain Standard Time Eastern Standard Time Eastern Standard Time Eastern Standard Time Eastern Standard Time Eastern Standard Time Eastern Standard Time Eastern Standard Time Eastern Standard Time Mountain Standard Time Eastern Standard Time Eastern Standard Time Argentine Time Alaska Standard Time Eastern Standard Time Eastern Standard Time Eastern Standard Time Bolivia Time Peru Time Pacific Standard Time Eastern Standard Time Brazil Time Central Standard Time Amazon Standard Time Relative to GMT GMT-3 GMT-4 GMT-5 GMT-4 GMT-4 GMT-6 GMT-5 GMT-4 GMT-4 GMT-5 GMT-7 GMT-5 GMT-5 GMT-5 GMT-5 GMT-5 GMT-5 GMT-5 GMT-5 GMT-7 GMT-5 GMT-5 GMT-3 GMT-9 GMT-5 GMT-5 GMT-5 GMT-4 GMT-5 GMT-8 GMT-5 GMT-3 GMT-6 GMT-4
| |
America/Indiana/ Petersburg America/Indiana/ Vevay
| | | |
America/Indiana/ Vincennes America/Indiana/ Winamac America/Indianapolis America/Inuvik America/Iqaluit America/Jamaica America/Jujuy America/Juneau America/Kentucky/ Louisville America/Kentucky/ Monticello America/Knox_IN America/La_Paz America/Lima America/Los_Angeles America/Louisville America/Maceio America/Managua America/Manaus
470

Table 72. Variable length notation time zones list (continued) Long Name America/Martinique America/Mazatlan America/Mendoza America/Menominee America/Merida America/Mexico_City America/Miquelon Description Atlantic Standard Time Mountain Standard Time Argentine Time Central Standard Time Central Standard Time Central Standard Time Pierre & Miquelon Standard Time Atlantic Standard Time Central Standard Time Uruguay Time Eastern Standard Time Atlantic Standard Time Eastern Standard Time Eastern Standard Time Eastern Standard Time Alaska Standard Time Fernando de Noronha Time Central Standard Time Central Standard Time Relative to GMT GMT-4 GMT-7 GMT-3 GMT-6 GMT-6 GMT-6 GMT-3 GMT-4 GMT-6 GMT-3 GMT-5 GMT-4 GMT-5 GMT-5 GMT-5 GMT-9 GMT-2 GMT-6 GMT-6
America/Moncton America/Monterrey America/Montevideo America/Montreal America/Montserrat America/Nassau America/New_York America/Nipigon America/Nome America/Noronha America/ North_Dakota/ Center
| | |
America/ North_Dakota/ New_Salem America/Panama America/Pangnirtung America/Paramaribo America/Phoenix America/Port_of_Spain America/Port-au-Prince America/Porto_Acre America/Porto_Velho America/Puerto_Rico America/Rainy_River America/Rankin_Inlet America/Recife America/Regina
Eastern Standard Time Eastern Standard Time Suriname Time Mountain Standard Time Atlantic Standard Time Eastern Standard Time Acre Time Amazon Standard Time Atlantic Standard Time Central Standard Time Eastern Standard Time Brazil Time Central Standard Time Central Standard Time Acre Time Argentine Time Chile Time
GMT-5 GMT-5 GMT-3 GMT-7 GMT-4 GMT-5 GMT-5 GMT-4 GMT-4 GMT-6 GMT-6 GMT-3 GMT-6 GMT-6 GMT-5 GMT-3 GMT-3
America/Resolute America/Rio_Branco America/Rosario America/Santiago
471

Table 72. Variable length notation time zones list (continued) Long Name America/Santo_ Domingo America/Sao_Paulo America/Scoresbysund America/Shiprock America/St_Johns America/St_Kitts America/St_Lucia America/St_Thomas America/St_Vincent America/Swift_Current America/Tegucigalpa America/Thule America/Thunder_Bay America/Tijuana America/Tortola Description Atlantic Standard Time Brazil Time Eastern Greenland Time Mountain Standard Time Newfoundland Standard Time Atlantic Standard Time Atlantic Standard Time Atlantic Standard Time Atlantic Standard Time Central Standard Time Central Standard Time Atlantic Standard Time Eastern Standard Time Pacific Standard Time Atlantic Standard Time Central Standard Time Pacific Standard Time Atlantic Standard Time Pacific Standard Time Central Standard Time Alaska Standard Time Mountain Standard Time Western Standard Time (Australia) Davis Time Dumont-dUrville Time Mawson Time New Zealand Standard Time Chile Time Rothera Time New Zealand Standard Time Syowa Time Vostok Time Central European Time Eastern European Time Arabia Standard Time Alma-Ata Time Eastern European Time Anadyr Time Relative to GMT GMT-4 GMT-2 GMT-1 GMT-7 GMT-3 GMT-4 GMT-4 GMT-4 GMT-4 GMT-6 GMT-6 GMT-4 GMT-5 GMT-8 GMT-4 GMT-6 GMT-8 GMT-4 GMT-8 GMT-6 GMT-9 GMT-7 GMT+8 GMT+7 GMT+10 GMT+6 GMT+13 GMT-3 GMT-3 GMT+13 GMT+3 GMT+6 GMT+1 GMT+2 GMT+3 GMT+6 GMT+2 GMT+12
America/Toronto America/Vancouver America/Virgin America/Whitehorse America/Winnipeg America/Yakutat America/Yellowknife Antarctica/Casey Antarctica/Davis Antarctica/Dumont DUrville Antarctica/Mawson Antarctica/McMurdo Antarctica/Palmer Antarctica/Rothera Antarctica/South_Pole Antarctica/Syowa Antarctica/Vostok Arctic/Longyearbyen ART Asia/Aden Asia/Almaty Asia/Amman Asia/Anadyr
472

Table 72. Variable length notation time zones list (continued) Long Name Asia/Aqtau Asia/Aqtobe Asia/Ashgabat Asia/Ashkhabad Asia/Baghdad Asia/Bahrain Asia/Baku Asia/Bangkok Asia/Beirut Asia/Bishkek Asia/Brunei Asia/Calcutta Asia/Choibalsan Asia/Chongqing Asia/Chungking Asia/Colombo Asia/Dacca Asia/Damascus Asia/Dhaka Asia/Dili Asia/Dubai Asia/Dushanbe Asia/Gaza Asia/Harbin Asia/Hong_Kong Asia/Hovd Asia/Irkutsk Asia/Istanbul Asia/Jakarta Asia/Jayapura Asia/Jerusalem Asia/Kabul Asia/Kamchatka Asia/Karachi Asia/Kashgar Asia/Katmandu Asia/Krasnoyarsk Asia/Kuala_Lumpur Asia/Kuching Description Aqtau Time Aqtobe Time Turkmenistan Time Turkmenistan Time Arabia Standard Time Arabia Standard Time Azerbaijan Time Indochina Time Eastern European Time Kirgizstan Time Brunei Time India Standard Time Choibalsan Time China Standard Time China Standard Time Sri Lanka Time Bangladesh Time Eastern European Time Bangladesh Time East Timor Time Gulf Standard Time Tajikistan Time Eastern European Time China Standard Time Hong Kong Time Hovd Time Irkutsk Time Eastern European Time West Indonesia Time East Indonesia Time Israel Standard Time Afghanistan Time Petropavlovsk-Kamchatski Time Pakistan Time China Standard Time Nepal Time Krasnoyarsk Time Malaysia Time Malaysia Time Relative to GMT GMT+4 GMT+5 GMT+5 GMT+5 GMT+3 GMT+3 GMT+4 GMT+7 GMT+2 GMT+5 GMT+8 GMT+5 GMT+9 GMT+8 GMT+8 GMT+6 GMT+6 GMT+2 GMT+6 GMT+9 GMT+4 GMT+5 GMT+2 GMT+8 GMT+8 GMT+7 GMT+8 GMT+2 GMT+7 GMT+9 GMT+2 GMT+4 GMT+12 GMT+5 GMT+8 GMT+5 GMT+7 GMT+8 GMT+8
473

Table 72. Variable length notation time zones list (continued) Long Name Asia/Kuwait Asia/Macao Asia/Macau Asia/Magadan Asia/Makassar Asia/Manila Asia/Muscat Asia/Nicosia Asia/Novosibirsk Asia/Omsk Asia/Oral Asia/Phnom_Penh Asia/Pontianak Asia/Pyongyang Asia/Qatar Asia/Qyzylorda Asia/Rangoon Asia/Riyadh Description Arabia Standard Time China Standard Time China Standard Time Magadan Time Central Indonesia Time Philippines Time Gulf Standard Time Eastern European Time Novosibirsk Time Omsk Time Oral Time Indochina Time West Indonesia Time Korea Standard Time Arabia Standard Time Qyzylorda Time Myanmar Time Arabia Standard Time Arabia Standard Time Arabia Standard Time Arabia Standard Time Indochina Time Sakhalin Time Turkmenistan Time Korea Standard Time China Standard Time Singapore Time China Standard Time Uzbekistan Time Georgia Time Iran Standard Time Israel Standard Time Bhutan Time Bhutan Time Japan Standard Time Central Indonesia Time Ulaanbaatar Time Ulaanbaatar Time China Standard Time Relative to GMT GMT+3 GMT+8 GMT+8 GMT+11 GMT+8 GMT+8 GMT+4 GMT+2 GMT+6 GMT+6 GMT+4 GMT+7 GMT+7 GMT+9 GMT+3 GMT+6 GMT+6 GMT+3 GMT+3 GMT+3 GMT+3 GMT+7 GMT+10 GMT+5 GMT+9 GMT+8 GMT+8 GMT+8 GMT+5 GMT+4 GMT+3 GMT+2 GMT+6 GMT+6 GMT+9 GMT+8 GMT+8 GMT+8 GMT+8
| | |
Asia/Riyadh87 Asia/Riyadh88 Asia/Riyadh89 Asia/Saigon Asia/Sakhalin Asia/Samarkand Asia/Seoul Asia/Shanghai Asia/Singapore Asia/Taipei Asia/Tashkent Asia/Tbilisi Asia/Tehran Asia/Tel_Aviv Asia/Thimbu Asia/Thimphu Asia/Tokyo Asia/Ujung_Pandang Asia/Ulaanbaatar Asia/Ulan_Bator Asia/Urumqi
474

Table 72. Variable length notation time zones list (continued) Long Name Asia/Vientiane Asia/Vladivostok Asia/Yakutsk Asia/Yekaterinburg Asia/Yerevan AST Atlantic/Azores Atlantic/Bermuda Atlantic/Canary Atlantic/Cape_Verde Atlantic/Faeroe Description Indochina Time Vladivostok Time Yakutsk Time Yekaterinburg Time Armenia Time Alaska Standard Time Azores Time Atlantic Standard Time Western European Time Cape Verde Time Western European Time Western European Time Eastern Greenland Time Western European Time Greenwich Mean Time South Georgia Standard Time Greenwich Mean Time Falkland Is. Time Eastern Standard Time (New South Wales) Central Standard Time (South Australia) Eastern Standard Time (Queensland) Central Standard Time (South Australia/New South Wales) Eastern Standard Time (New South Wales) Eastern Standard Time (Tasmania) Central Standard Time (Northern Territory) Western Standard Time (Australia) Eastern Standard Time (Tasmania) Load Howe Standard Time Eastern Standard Time (Queensland) Load Howe Standard Time Eastern Standard Time (Victoria) Central Standard Time (Northern Territory) Eastern Standard Time (New South Wales) Western Standard Time (Australia) Eastern Standard Time (Queensland) Central Standard Time (South Australia) Eastern Standard Time (New South Wales) Eastern Standard Time (Tasmania) Relative to GMT GMT+7 GMT+10 GMT+9 GMT+5 GMT+4 GMT-9 GMT-1 GMT-4 GMT GMT-1 GMT GMT GMT+1 GMT GMT GMT-2 GMT GMT-3 GMT+11 GMT+10 GMT+10 GMT+10 GMT+11 GMT+11 GMT+8:.45 GMT+11 GMT+11 GMT+11 GMT+10 GMT+11 GMT+11 GMT+9 GMT+11 GMT+8 GMT+10 GMT+10 GMT+11 GMT+11
Atlantic/Faroe Atlantic/Jan_Mayen Atlantic/Madeira Atlantic/Reykjavik Atlantic/South_Georgia Atlantic/St_Helena Atlantic/Stanley Australia/ACT Australia/Adelaide Australia/Brisbane Australia/Broken_Hill Australia/Canberra
| |
Australia/Currie Australia/Darwin Australia/Eucla Australia/Hobart Australia/LHI Australia/Lindeman Australia/Lord_Howe Australia/Melbourne Australia/North Australia/NSW Australia/Perth Australia/Queensland Australia/South Australia/Sydney Australia/Tasmania
475

Table 72. Variable length notation time zones list (continued) Long Name Australia/Victoria Australia/West Australia/Yancowinna BET Brazil/Acre Brazil/DeNoronha Brazil/East Brazil/West BST Canada/Atlantic Canada/Central Canada/Eastern Canada/EastSaskatchewan Canada/Mountain Canada/Newfoundland Canada/Pacific Canada/Saskatchewan Canada/Yukon CAT CET Chile/Continental Chile/EasterIsland CNT CST CST6CDT CTT Cuba EAT ECT EET Egypt Eire EST EST5EDT Description Eastern Standard Time (Victoria) Western Standard Time (Australia) Central Standard Time (South Australia/New South Wales) Brazil Time Acre Time Fernando de Noronha Time Brazil Time Amazon Standard Time Bangladesh Time Atlantic Standard Time Central Standard Time Eastern Standard Time Central Standard Time Mountain Standard Time Newfoundland Standard Time Pacific Standard Time Central Standard Time Pacific Standard Time Central African Time Central European Time Chile Time Easter Is. Time Newfoundland Standard Time Central Standard Time Central Standard Time China Standard Time Central Standard Time Eastern African Time Central European Time Eastern European Time Eastern European Time Greenwich Mean Time Eastern Standard Time Eastern Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Relative to GMT GMT+11 GMT+8 GMT+10 GMT-2 GMT-5 GMT-2 GMT-2 GMT-4 GMT+6 GMT-4 GMT-6 GMT-5 GMT-6 GMT-7 GMT-3 GMT-8 GMT-6 GMT-8 GMT+2 GMT+1 GMT-3 GMT-5 GMT-3 GMT-6 GMT-6 GMT+8 GMT-5 GMT+3 GMT+1 GMT+2 GMT+2 GMT GMT-5 GMT-5 GMT GMT-0 GMT-1 GMT-10
| | | |
Etc/GMT Etc/GMT-0 Etc/GMT-1 Etc/GMT-10
476

Table 72. Variable length notation time zones list (continued) Long Name Description Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Greenwich Standard Time Central European Time Central European Time Eastern European Time Greenwich Mean Time Central European Time Central European Time Central European Time Central European Time Eastern European Time Central European Time Relative to GMT GMT-11 GMT-12 GMT-13 GMT-14 GMT-2 GMT-3 GMT-4 GMT-5 GMT-6 GMT-7 GMT-8 GMT-9 GMT+0 GMT+1 GMT+11 GMT+12 GMT+2 GMT+3 GMT+4 GMT+5 GMT+6 GMT+7 GMT+8 GMT+9 GMT GMT GMT GMT GMT+2 GMT+1 GMT+1 GMT+2 GMT GMT+1 GMT+1 GMT+1 GMT+1 GMT+2 GMT+1
| | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Etc/GMT-11 Etc/GMT-12 Etc/GMT-13 Etc/GMT-14 Etc/GMT-2 Etc/GMT-3 Etc/GMT-4 Etc/GMT-5 Etc/GMT-6 Etc/GMT-7 Etc/GMT-8 Etc/GMT-9 Etc/GMT+0 Etc/GMT+1 Etc/GMT+11 Etc/GMT+12 Etc/GMT+2 Etc/GMT+3 Etc/GMT+4 Etc/GMT+5 Etc/GMT+6 Etc/GMT+7 Etc/GMT+8 Etc/GMT+9 Etc/GMT0 Etc/Greenwich Etc/UTC Etc/Universal Etc/Zulu Europe/Amsterdam Europe/Andorra Europe/Athens Europe/Belfast Europe/Belgrade Europe/Berlin Europe/Bratislava Europe/Brussels Europe/Bucharest Europe/Budapest
477

Table 72. Variable length notation time zones list (continued) Long Name Europe/Chisinau Europe/Copenhagen Europe/Dublin Europe/Gibraltar Description Eastern European Time Central European Time Greenwich Mean Time Central European Time Central European Time Eastern European Time Greenwich Mean Time Eastern European Time Greenwich Mean Time Eastern European Time Eastern European Time Western European Time Central European Time Greenwich Mean Time Central European Time Central European Time Central European Time Eastern European Time Eastern European Time Central European Time Moscow Standard Time Eastern European Time Central European Time Central European Time Central European Time Central European Time Eastern European Time Central European Time Samara Time Central European Time Central European Time Eastern European Time Central European Time Eastern European Time Central European Time Eastern European Time Central European Time Eastern European Time Eastern European Time Relative to GMT GMT+2 GMT+1 GMT GMT+1 GMT+1 GMT+2 GMT GMT+2 GMT GMT+2 GMT+2 GMT GMT+1 GMT GMT+1 GMT+1 GMT+1 GMT+2 GMT+2 GMT+1 GMT+3 GMT+2 GMT+1 GMT+1 GMT+1 GMT+1 GMT+2 GMT+1 GMT+4 GMT+1 GMT+1 GMT+2 GMT+1 GMT+2 GMT+1 GMT+2 GMT+1 GMT+2 GMT+2
| | |
Europe/Guernsey Europe/Helsinki Europe/Isle_of_Man Europe/Istanbul Europe/Jersey Europe/Kaliningrad Europe/Kiev Europe/Lisbon Europe/Ljubljana Europe/London Europe/Luxembourg Europe/Madrid Europe/Malta
Europe/Mariehamn Europe/Minsk Europe/Monaco Europe/Moscow Europe/Nicosia Europe/Oslo Europe/Paris
Europe/Podgorica Europe/Prague Europe/Riga Europe/Rome Europe/Samara Europe/San_Marino Europe/Sarajevo Europe/Simferopol Europe/Skopje Europe/Sofia Europe/Stockholm Europe/Tallinn Europe/Tirane Europe/Tiraspol Europe/Uzhgorod
478

Table 72. Variable length notation time zones list (continued) Long Name Europe/Vaduz Europe/Vatican Europe/Vienna Europe/Vilnius Description Central European Time Central European Time Central European Time Eastern European Time Moscow Standard Time Central European Time Central European Time Eastern European Time Central European Time Greenwich Mean Time Greenwich Mean Time Greenwich Mean Time Greenwich Mean Time Greenwich Mean Time Greenwich Mean Time Greenwich Mean Time Hong Kong Time Hawaii Standard Time Greenwich Mean Time Eastern Standard Time Eastern African Time Indian Ocean Territory Time Christmas Island Time Cocos Islands Time Eastern African Time French Southern and Antarctic Lands Time Seychelles Time Maldives Time Mauritius Time Eastern African Time Reunion Time Iran Standard Time Israel Standard Time India Standard Time Eastern Standard Time Japan Standard Time Japan Standard Time Marshall Islands Time Eastern European Time Relative to GMT GMT+1 GMT+1 GMT+1 GMT+2 GMT+3 GMT+1 GMT+1 GMT+2 GMT+1 GMT GMT GMT GMT GMT GMT GMT GMT+8 GMT-10 GMT GMT-5 GMT+3 GMT+6 GMT+7 GMT+6 GMT+3 GMT+5 GMT+4 GMT+5 GMT+4 GMT+3 GMT+4 GMT+3 GMT+2 GMT+5 GMT-5 GMT+9 GMT+9 GMT+12 GMT+2
Europe/Volgograd Europe/Warsaw Europe/Zagreb Europe/Zaporozhye Europe/Zurich GB GB-Eire GMT
| | | |
GMT-0 GMT+0 GMT0 Greenwich Hongkong HST Iceland IET Indian/Antananarivo Indian/Chagos Indian/Christmas Indian/Cocos Indian/Comoro Indian/Kerguelen Indian/Mahe Indian/Maldives Indian/Mauritius Indian/Mayotte Indian/Reunion Iran Israel IST Jamaica Japan JST Kwajalein Libya
479

Table 72. Variable length notation time zones list (continued) Long Name MET Mexico/BajaNorte Mexico/BajaSur Mexico/General Description Middle Europe Time Pacific Standard Time Mountain Standard Time Central Standard Time Arabia Standard Time Arabia Standard Time Arabia Standard Time West Samoa Time Mountain Standard Time Mountain Standard Time Mountain Standard Time Armenia Time New Zealand Standard Time New Zealand Standard Time Chatham Standard Time West Samoa Time New Zealand Standard Time Chatham Standard Time Easter Is. Time Vanuatu Time Phoenix Is. Time Tokelau Time Fiji Time Tuvalu Time Galapagos Time Gambier Time Solomon Is. Time Chamorro Standard Time Hawaii Standard Time Hawaii Standard Time Line Is. Time Kosrae Time Marshall Islands Time Marshall Islands Time Marquesas Time Samoa Standard Time Nauru Time Niue Time Norfolk Time Relative to GMT GMT+1 GMT-8 GMT-7 GMT-6 GMT+3 GMT+3 GMT+3 GMT-11 GMT-7 GMT-7 GMT-7 GMT+4 GMT+13 GMT+13 GMT+13 GMT-11 GMT+13 GMT+13 GMT-5 GMT+11 GMT+13 GMT-10 GMT+12 GMT+12 GMT-6 GMT-9 GMT+11 GMT+10 GMT-10 GMT-10 GMT+14 GMT+11 GMT+12 GMT+12 GMT-9 GMT-11 GMT+12 GMT-11 GMT+11
| | |
Mideast/Riyadh87 Mideast/Riyadh88 Mideast/Riyadh89 MIT MST MST7MDT Navajo NET NST NZ NZ-CHAT Pacific/Apia Pacific/Auckland Pacific/Chatham Pacific/Easter Pacific/Efate Pacific/Enderbury Pacific/Fakaofo Pacific/Fiji Pacific/Funafuti Pacific/Galapagos Pacific/Gambier Pacific/Guadalcanal Pacific/Guam Pacific/Honolulu Pacific/Johnston Pacific/Kiritimati Pacific/Kosrae Pacific/Kwajalein Pacific/Majuro Pacific/Marquesas Pacific/Midway Pacific/Nauru Pacific/Niue Pacific/Norfolk
480

Table 72. Variable length notation time zones list (continued) Long Name Pacific/Noumea Pacific/Pago_Pago Pacific/Palau Pacific/Pitcairn Pacific/Ponape Pacific/Port_Moresby Pacific/Rarotonga Pacific/Saipan Pacific/Samoa Pacific/Tahiti Pacific/Tarawa Pacific/Tongatapu Pacific/Truk Pacific/Wake Pacific/Wallis Pacific/Yap PLT PNT Poland Portugal PRC PRT PST PST8PDT Description New Caledonia Time Samoa Standard Time Palau Time Pitcairn Standard Time Ponape Time Papua New Guinea Time Cook Is. Time Chamorro Standard Time Samoa Standard Time Tahiti Time Gilbert Is. Time Tonga Time Truk Time Wake Time Wallis & Futuna Time Yap Time Pakistan Time Mountain Standard Time Central European Time Western European Time China Standard Time Atlantic Standard Time Pacific Standard Time Pacific Standard Time China Standard Time Korea Standard Time Singapore Time Solomon Is. Time Eastern European Time Coordinated Universal Time Alaska Standard Time Hawaii-Aleutian Standard Time Mountain Standard Time Central Standard Time Eastern Standard Time Eastern Standard Time Hawaii Standard Time Eastern Standard Time Eastern Standard Time Relative to GMT GMT+11 GMT-11 GMT+9 GMT-8 GMT+11 GMT+10 GMT-10 GMT+10 GMT-11 GMT-10 GMT+12 GMT+13 GMT+10 GMT+12 GMT+12 GMT+10 GMT+5 GMT-7 GMT+1 GMT GMT+8 GMT-4 GMT-8 GMT-8 GMT+8 GMT+9 GMT+8 GMT+11 GMT+2 GMT GMT-9 GMT-10 GMT-7 GMT-6 GMT-5 GMT-5 GMT-10 GMT-5 GMT-5
ROC ROK Singapore SST Turkey
Universal US/Alaska US/Aleutian US/Arizona US/Central US/Eastern US/East-Indiana US/Hawaii US/Indiana-Starke US/Michigan
481

Table 72. Variable length notation time zones list (continued) Long Name US/Mountain US/Pacific US/Pacific-New US/Samoa UTC VST WET W-SU Description Mountain Standard Time Pacific Standard Time Pacific Standard Time Samoa Standard Time Coordinated Universal Time Indochina Time Western European Time Moscow Standard Time Central African Time Relative to GMT GMT-7 GMT-8 GMT-8 GMT-11 GMT GMT+7 GMT GMT+3 GMT+2
Zulu
482
Chapter 13. The auditing feature

Tivoli Workload Scheduler provides you with an auditing feature to track changes applied to the database and to the plan. By default the auditing feature is disabled. This chapter is divided into the following sections: v Auditing overview v Enabling the auditing feature v Audit log format on page 484 v Sample audit log files on page 487
Auditing overview
Tivoli Workload Scheduler provides you with two types of audit log files: Plan audit log file Logs all user action performed against the plan. Actions are logged whether or not they are successful. Database audit log file Logs all actions against scheduling objects, even if an object is opened and saved without changing it. The auditing logs are created once a day at 00:00:00 GMT in the following directories:
TWS_home/audit/plan TWS_home/audit/database
on each workstation in the Tivoli Workload Scheduler network to minimize the risk of audit failure due to network problems.
Enabling the auditing feature

Auditing is disabled by default when the product is installed. You can enable or disable the auditing feature by setting the value of these two global options:
plan audit level database audit level
using the optman command line on the master domain manager. Set the value to yes to enable auditing or to no to disable auditing. If these options are not present among the global options then auditing is disabled. For information on the optman command line, refer to IBM Tivoli Workload Scheduler: Planning and Installation Guide. Plan auditing settings take effect when JnextPlan is run.
483
Audit log format
Audit log format

The audit log formats are basically the same for both the plan and the database audit log files. They consist of a header portion containing information about when the log was created, the workstation it relates to, and whether it is a plan or a database audit log, and a body containing a record for each action performed. All data is stored in normal text and formatted to be readable and editable from a text editor such as vi or notepad. In the audit log files: The format for dates is yyyymmdd where: v yyyy is the year v mm is the month v dd is the day The format for times is hhmmss where: v hh is the hour v mm is the minutes v ss is the seconds The formats of the audit log files header and body are described in the following sections.
Audit log header format

The header contains the following set of information ordered in fields separated by vertical bars ( | ): Fields Log Type GMT Date GMT Time Local Date Local Time Object Type Contents HEADER The GMT date when the log file was created. The GMT time when the log file was created. The local date when the log file was created. The local date is defined by the time zone option of the workstation. The local time when the log file was created. The local time is defined by the time zone option of the workstation. DATABASE for a database log file and PLAN for a plan log file.
Workstation Name The Tivoli Workload Scheduler workstation name for which this file was created. Each workstation in the Tivoli Workload Scheduler network creates its own log. User ID Version Level The Tivoli Workload Scheduler user ID that created the log file. The version of the file. The logging level.
Audit log body format

The log contains, for each action logged, the following set of information ordered in fields separated by vertical bars ( | ):
484

Log Type An eight-character value indicating the source of the log record. The following log types are supported: HEADER conman PLAN STAGEMAN RELEASE DATABASE PARMS MAKESEC GMT Date GMT Time Local Date Local Time Object Type The log file header conman command text Plan action stageman run release command text Database action Parameter command text makesec run
The GMT date when the action was performed. The GMT time when the action was performed. The local date when the action was performed. The local date is defined by the time zone option of the workstation. The local time when the action was performed. The local time is defined by the time zone option of the workstation. The type of the object that the action was performed on. It is one of the following: DATABASE DBWKSTN DBWKCLS DBDOMAIN DBUSER DBJBSTRM DBJOB DBCAL DBPROMPT DBPARM DBRES DBSEC PLAN PLWKSTN PLDOMAIN PLJBSTRM PLJOB PLPROMPT PLRES PLFILE Database definition Database workstation definition Database workstation class definition Database domain definition Database user definition Database job stream definition Database job definition Database calendar definition Database prompt definition Database parameter definition Database resource definition Database security Plan Plan workstation Plan domain Plan job stream Plan job Plan prompt Plan resource Plan file
Action Type
The action taken against the object. Valid action types are add,
485

delete, modify, expand, and install. The appropriate values for this field depend on the action being taken. For database audit logs Tivoli Workload Scheduler records add, delete, and modify actions for workstation, workstation classes, domains, users, jobs, job streams, calendars, prompts, resources, and parameters in the database. For plan audit log Tivoli Workload Scheduler records add, delete, modify, expand, and install. The install action is recorded when the makesec command is run to install a new security file. List and display actions for objects are not logged. For parameters, the command line with arguments is logged. Workstation Name The Tivoli Workload Scheduler workstation on which the user performs the action. User ID The logon user who performed the particular action. On Windows operating systems, if the user who installed WebSphere Application Server was domain user, for Log Type stageman and conman this field contains the fully qualified user name domain\user. The fully qualified name of the object. The format of this field depends on the object type as follows: DBWKSTN DBWKCLS DBDOMAIN DBUSER DBJBSTRM DBJOB DBCAL DBPROMPT DBPARM DBRES PLWKSTN PLDOMAIN PLJBSTRM PLJOB PLPROMPT PLRES PLFILE workstation workstation_class domain [workstation#]user workstation#jobstream workstation#job calendar prompt workstation#parameter workstation#resource workstation domain workstation#jobstream_instance workstation#jobstream_instance.job [workstation#]prompt workstation#resource workstation#path(qualifier)
Object Name
Action Dependent Data The action-specific data fields. The format of this data is dependent on the Action Type field.
486
Sample audit log files

This is a sample database audit log: HEADER |20060207|084124|20060207|094124|DATABASE| DATABASE|20060207|084124|20060207|094124|DBRES |ADD |WK1| | | |Version=A1.0| Level=1 | | | | | | | | | |
|WK1|operator1| |res=WK1#RESOURCE
DATABASE|20060207|100524|20060207|110524|DBWKSTN |MODIFY|WK1|operator1| |ws=TIVOLI10 DATABASE|20060207|100525|20060207|110525|DBWKSTN |MODIFY|WK1|operator1| |ws=ASLUTRI1 DATABASE|20060207|100525|20060207|110525|DBWKSTN |MODIFY|WK1|operator1| |ws=WK1 DATABASE|20060207|100526|20060207|110526|DBDOMAIN|MODIFY|WK1|operator1| |dom=MASTERDM DATABASE|20060207|100610|20060207|110610|DBWKSTN |MODIFY|WK1|operator1| |ws=TIVOLI10 DATABASE|20060207|100610|20060207|110610|DBWKSTN |MODIFY|WK1|operator1| |ws=ASLUTRI1 DATABASE|20060207|100611|20060207|110611|DBWKSTN |MODIFY|WK1|operator1| |ws=WK1 DATABASE|20060207|100611|20060207|110611|DBWKSTN |ADD |WK1|operator1| |ws=WK2
DATABASE|20060207|100612|20060207|110612|DBDOMAIN|MODIFY|WK1|operator1| |dom=MASTERDM
This is a sample plan audit log: HEADER |20060207|100758|20060207|110758|PLAN |
|WK1|admin| |
|Version=A1.0|Level=1
STAGEMAN|20060207|100758|20060207|110758|PLAN |INSTALL|WK1|admin| |C:\IBM\TWS\oper1\Symphony| AWSBHV030I The new Symphony file is installed. STAGEMAN|20060207|100758|20060207|110758|PLAN |INSTALL|WK1|admin| |C:\IBM\TWS\oper1\Sinfonia| AWSBHV036I Multi-workstation Symphony file copied to C:\IBM\TWS\oper1\Sinfonia STAGEMAN|20060207|100758|20060207|110758|ADITLEVL|MODIFY |WK1|admin| | AWSBHV077I Audit level changing from 0 to 1. CONMAN |20060207|100800|20060207|110800|PLWKSTN |MODIFY | continue & start CONMAN |20060207|100941|20060207|110941|PLWKSTN |MODIFY | limit cpu=slutri1;10 PLAN PLAN |admin| |WK1 |admin| |SLUTRI1 | | | | |
|20060207|101018|20060207|111018|PLWKSTN |MODIFY |WK1|oper1| |WK1 limit cpu=SLUTRI1;20 |20060207|101028|20060207|111028|PLDOMAIN|MODIFY |WK1|oper1| |ECCOLO reply ECCOLO;yes
A ResetPlan command run against the current production plan is stored in the plan audit log file as follows: STAGEMAN|20060207|100758|20060207|110758|PLAN|DELETE|WK1|admin| |/home/WK1/schedlog/M200603140127| AWSBHV025I The old Symphony file renamed /home/WK1/schedlog/M200603140127
487
488
Chapter 14. Managing extended agents

Workstations are generally physical assets (that is computers) but they might also be logical definitions, hosted by a physical workstation, representing operating systems or applications where you want to run jobs or job streams. In this case they are defined as extended agents. This chapter describes the extended agents, their interface and provides information for programmers who want to create custom access methods. Extended Agents are used to extend the job scheduling functions of IBM Tivoli Workload Scheduler to other systems and applications such as: local or remote UNIX operating systems, Peoplesoft, SAP R/3, z/OS, CA-7, JES, OPC, Oracle EBS, and VMS. This chapter is divided into the following sections: v What are extended agents? v Access method interface on page 490 v Method running on page 494 v Troubleshooting on page 496 The following example shows a definition for a z/OS extended agent workstation named MVSCPU that uses the mvsjes access method.
cpuname MVSCPU description "zOS extended agent" os other node mvsesa36.rome.tivoli.com tcpaddr 5000 domain masterdm for maestro type x-agent host ROCIOUS access mvsjes end
The following example describes a Tivoli Workload Scheduler job named orajob2 that runs in an Oracle Applications extended agent workstation named ora002. It logs on to UNIX as orajobs and launches a job under Oracle Applications. The Oracle Applications job is named poxacr and its owner is global. If recovery is needed, Tivoli Workload Scheduler will run job recov2 and then continue processing.
ora002#orajob2 streamlogon orajobs scriptname "-user global -job fnd application developer po poxacr -prn ps4 2 -v1 abc" description "oracle apps job #2" recovery continue after recov2
The arguments of scriptname differ by application. For additional information, refer to IBM Tivoli Workload Scheduler for Applications: User's Guide
What are extended agents?

Extended agents are used to extend the job scheduling functions of Tivoli Workload Scheduler to other systems and applications.
489
What are extended agents?

An extended agent is defined as a workstation that has a host and an access method. The host is any other workstation, except another extended agent. The access method is an IBM-supplied or user-supplied script or program that is run by the host whenever the extended agent is referenced in the production plan. For example, to launch a job on an extended agent, the host runs the access method, passing it job details as command line options. The access method communicates with the external system or application to launch the job and return the status of the job.
Each extended agent must have a logical workstation definition. This logical workstation must be hosted by an Tivoli Workload Scheduler physical workstation, either a master domain manager, domain manager, FTA workstation. The extended agent workstation definition references the name of the access method and the host workstation. When jobs are launched on the extended agent workstation, the access method is called and passes the job information to the external system.
Access method interface

The interface between Tivoli Workload Scheduler and an access method consists of information passed to the method on the command line, and of messages returned to Tivoli Workload Scheduler in stdout.
Method command line syntax

The Tivoli Workload Scheduler host runs an access method using the following command line syntax: methodname -t task options -- taskstring where: methodname Specifies the file name of the access method. All access methods must be stored in the directory: TWS_home/methods -t task Specifies the task to be performed, where task is one of the following: LJ MJ CF GS Launches a job. Manages a previously launched job. Use this option to resynchronize if a prior LJ task ended unexpectedly. Checks the availability of a file. Use this option to check file opens dependencies. Gets the status of a job. Use this option to check job follows dependencies.
options Specifies the options associated with the task. See Task options for more information. taskstring A string of up to 255 characters associated with the task. See Task options.
Task options
The task options are listed in Table 73 on page 491. An X means that the option is valid for the task.
490

Table 73. Method command task options Task LJ MJ CF GS -c X X X X -n X X X X -p X X X X X X -r X X -s X X -d X X -l X X -o X X -j X X X X -q -w -S X Task String ljstring mjstring cfstring gsstring
-c xagent,host,master Specifies the names of the extended agent, the host, and the master domain manager separated by commas. -n nodename Specifies the node name of the computer associated with the extended agent, if any. This is defined in the extended agents workstation definition Node field. -p portnumber Specifies the TCP/IP port number associated with the extended agent, if any. This is defined in the extended agents workstation definition TCP Address field. -r currentrun,specificrun Specifies the current run number of Tivoli Workload Scheduler and the specific run number associated with the job separated by a comma. The current and specific run numbers might be different if the job was carried forward from an earlier run. -s jstream Specifies the name of the jobs job stream. -d scheddate,epoch Specifies the job stream date (yymmdd) and the epoch equivalent, separated by a comma. -l user Specifies the jobs user name. This is defined in the job definition Logon field. -o stdlist Specifies the full path name of the jobs standard list file. Any output from the job must be written to this file. -j jobname,id Specifies the jobs name and the unique identifier assigned by Tivoli Workload Scheduler, separated by a comma. The name is defined in the job definition Job Name field. -q qualifier Specifies the qualifier to be used in a test command issued by the method against the file. -w timeout Specifies the amount of time, in seconds, that Tivoli Workload Scheduler waits to get a reply on an external job before sending a SIGTERM signal to the access method. The default is 300. -S new name Specifies that the job is rerun using this name in place of the original job
491

name. Within a job script, you can use the jobinfo command to return the job name and run the script differently for each iteration. -- ljstring Used with the LJ task. The string from the Script File or Command field of the job definition. -- mjstring Used with the MJ task. The information provided to the Tivoli Workload Scheduler by the method in a message indicating a job state change %CJ (see Method response messages for additional details on messages indicating job state change) following to a LJ task. Usually, this identifies the job that was launched. For example, a UNIX method can provide the process identification (PID) of the job it launched, which is then sent by the Tivoli Workload Scheduler as part of an MJ task. -- cfstring Used with the CF task. For a file opens dependency, the string from the Opens Files field of the job stream definition. -- gsstring Used with the GS task. Specifies the job whose status is checked. The format is as follows: followsjob[,jobid] where: followsjob The string from the Follows Sched/Job list of the job stream definition. jobid An optional job identifier received by Tivoli Workload Scheduler in a %CJ response to a previous GS task.
Method response messages

Methods return information to Tivoli Workload Scheduler in messages written to stdout. Each line starting with a percent sign (%) and ending with a new line is interpreted as a message. The messages have the following format: %CJ state [mjstring | jobid] %JS [cputime] %RC rc %UT [errormessage] where: CJ Changes the job state. state The state to which the job is changed. All Tivoli Workload Scheduler job states are valid except HOLD and READY. For the GS task, the following states are also valid: ERROR EXTRN An error occurred. Status is unknown.
492
Method response messages

mjstring A string of up to 255 characters that Tivoli Workload Scheduler will include in any MJ task associated with the job. See 492. jobid A string of up to 64 characters that Tivoli Workload Scheduler will include in any GS task associated with the job. See 492.
JS [cputime] Indicates successful completion of a job and provides its elapsed run time in seconds. RC rc rc is a number that is interpreted by Tivoli Workload Scheduler as the return code of the extended agent job. The return code is taken into account only if a return code condition was specified in the definition of the extended agent job. Otherwise, it is ignored and the successful completion of the extended agent job is indicated by the presence of message %JS [cputime]. Likewise, if the method does not send the %RC message, then the successful completion of the extended agent job is indicated by the presence of message %JS [cputime].
UT [errormessage] Indicates that the requested task is not supported by the method. Displays a string of up to 255 characters that Tivoli Workload Scheduler will include in its error message.
Method options file

You can use a method options file to specify special login information and other options. Tivoli Workload Scheduler reads the file, if it exists, before running a method. If the file is modified after Tivoli Workload Scheduler is started, the changes only take effect when it is stopped and restarted. The file can contain Tivoli Workload Scheduler options and any other method information. The options recognized by Tivoli Workload Scheduler are as follows: LJuser=username CFuser=username GSuser=username GStimeout=seconds where: LJuser=username Specifies the login to use for the LJ and MJ tasks. The default is the login from the job definition. CFuser=username Specifies the login to use for the CF task. The default for UNIX is root, and for Windows is the user name of the account in which Tivoli Workload Scheduler was installed. GSuser=username Specifies the login to use for the GS tasks. The default for UNIX is root, and for Windows is the user name of the account in which Tivoli Workload Scheduler was installed.
493
Method options file

GStimeout=seconds Specifies the amount of time, in seconds, Tivoli Workload Scheduler waits for a response before killing the access method. The default is 300 seconds. Note: If the extended agents host is a Windows computer, these users must be defined as Tivoli Workload Scheduler user objects. The options file must have the same path name as its access method, with an .opts file extension. For example, the Windows path name of an options file for a method named netmeth is
TWS_home\methods\netmth.opts
Method running
The following subsections describe the interchange between Tivoli Workload Scheduler and an access method.
Launch job task (LJ)

The LJ task instructs the extended agent method to launch a job on an external system or application. Before running the method, Tivoli Workload Scheduler establishes a run environment. The LJuser parameter is read from the method options file to determine the user account with which to run the method. If the parameter is not present or the options file does not exist, the user account specified in the Logon field of the jobs definition is used. In addition, the following environment variables are set: HOME The login users home directory. LOGNAME The login users name. PATH For UNIX, it is set to/bin:/usr/bin. For Windows, it is set to%SYSTEM%\SYSTEM32. TZ The time zone.
If the method cannot be run, the job is placed in the FAIL state. Once a method is running, it writes messages to its stdout that indicate the state of the job on the external system. The messages are summarized in Table 74.
Table 74. Launch job task (LJ) messages Task LJ and MJ Method Response %CJ state [mjstring] %JS [cputime] Exit code=non-zero %UT [errormessage] and Exit code=2 Tivoli Workload Scheduler Action Sets job state to state. Includes mjstring in any subsequent MJ task. Sets job state to SUCC. Sets job state to ABEND. Sets job state to ABEND and displays errormessage.
A typical sequence consists of one or more %CJ messages indicating changes to the job state and then a %JS message before the method exits to indicate that the job ended successfully. If the job is unsuccessful, the method must exit without writing
494
Launch job task (LJ)

the %JS message. A method that does not support the LJ task, writes a %UT message to stdout and exits with an exit code of 2.
Manage job task (MJ)

The MJ task is used to synchronize with a previously launched job if Tivoli Workload Scheduler determines that the LJ task ended unexpectedly. Tivoli Workload Scheduler sets up the environment in the same manner as for the LJ task and passes it the mjstring. See Launch job task (LJ) on page 494 for more information. If the method locates the specified job, it responds with the same messages as an LJ task. If the method is unable to locate the job, it exits with a nonzero exit code, causing Tivoli Workload Scheduler to place the job in the ABEND state.
Killing a job
While an LJ or MJ task is running, the method must trap a SIGTERM signal (signal 15). The signal is sent when an operator issues a kill command from Tivoli Workload Scheduler console manager. Upon receiving the signal, the method must attempt to stop (kill) the job and then exit without writing a %JS message.
Check file task (CF)

The CF task requests the extended agent method to check the availability of a file on the external system. Before running the method, Tivoli Workload Scheduler establishes a run environment. The CFuser parameter is read from the method options file to determine the user account with which to run the method. If the parameter is not present or the options file does not exist, on UNIX the root user is used and, on Windows, the user name of the account in which Tivoli Workload Scheduler was installed is used. If the method cannot be run, the file opens dependency is marked as failed, that is, the file status is set to NO and any dependent job or job stream is not allowed to run. Once it is running, the method runs a test command, or the equivalent, against the file using the qualifier passed to it in the -q command line option. If the file test is true, the method exits with an exit code of zero. If the file test is false, the method exits with a nonzero exit code. This is summarized in Table 75.
Table 75. Check file task (CF) messages Task CF Method Response Exit code=0 Exit code=nonzero %UT [errormessage] and Exit code=2 Tivoli Workload Scheduler Action Set file state to YES. Set file state to NO. Set file state to NO.
A method that does not support the CF task writes a %UT message to stdout and exits with an exit code of 2.
Get status task (GS)

The GS task tells the extended agents method to check the status of a job. This is necessary when another job is dependent on the successful completion of an external job. Before running the method, the GSuser parameter is read from the method options file to determine the user account with which to run the method. If the parameter is not present or the options file does not exist, on UNIX the root user is used, and, on Windows, the user name of the account in which Tivoli
495
Get status task (GS)

Workload Scheduler was installed is used. If the method cannot be run, the dependent job or job stream is not allowed to run. If a jobid is available from a prior GS task, it is passed to the method. The method checks the state of the specified job, and returns it in a %CJ message written to stdout. It then exits with an exit code of zero. At a rate set by the bm check status local option, the method is re-run with a GS task until one of the following job states is returned: abend The job ended abnormally. succ cancl done fail error extrn The job completed successfully. The job was cancelled. The job is ended, but its success or failure is not known. The job could not be run. An error occurred in the method while checking job status. The job check failed or the job status could not be determined.
Note that GStimeout in the method options file specifies how long Tivoli Workload Scheduler will wait for a response before killing the method. See Method options file on page 493 for more information. Method responses are summarized in Table 76:
Table 76. Get status task (GS) messages Task GS Method Response %CJ state [jobid] %UT [errormessage] and Exit code=2 Tivoli Workload Scheduler Action Sets job state to state and includes jobid in any subsequent GS task. Job state is unchanged.
A method that does not support the GS task writes a %UT message to stdout and exits with an exit code of 2.
Cpuinfo command
The cpuinfo command can be used in an access method to return information from a workstation definition. See cpuinfo on page 378 for complete command information.
Troubleshooting
The following topics are provided to help troubleshoot and debug extended agent and access method problems.
Job standard list error messages

All output messages from an access method, except those that start with a percent sign (%), are written to the jobs standard list (stdlist) file. For GS and CF tasks that are not associated Tivoli Workload Scheduler jobs, messages are written to Tivoli Workload Scheduler standard list file. For information about a problem of any kind, check these files.
496
Method not executable
Method not executable

If an access method cannot be run, the following occurs: v For LJ and MJ tasks, the job is placed in the FAIL state. v For the CF task, the file dependency is unresolved and the dependent job remains in the HOLD state. v For the GS task, the job dependency is unresolved and the dependent job remains in the HOLD state. To get more information, review the standard list files (stdlist) for the job and for Tivoli Workload Scheduler.
Console Manager messages

This error message is displayed if you issue a start, stop, link, or unlink command for an extended agent:
AWSBHU058E The command issued for workstation: workstation_name, cannot be performed, because the workstation is an extended agent, where the command is not supported.
Composer and compiler messages

The following error messages are generated when composer encounters invalid syntax in a workstation definition:
AWSDEM045E There is an error in the workstation definition. The ACCESS keyword was not followed by a valid method. Valid methods correspond with the name of a file in the TWS_home/methods directory (the file need not be present when the access method is defined). AWSDEM046E There is an error in the workstation definition. The ACCESS keyword has been specified more than once. AWSDEM047E There is an error in the workstation definition. The ACCESS keyword was not followed by a valid method. Valid methods correspond with the name of a file in the TWS_home/methods directory (the file need not be present when the access method is defined).
If an extended agent is defined with an access method but without a host, the following message is displayed:
AWSBIA140E For an extended agent you must specify the host and the access method.
Jobman messages
For extended agents, error, warning, and information messages are written to jobmans stdlist file. A successful job launch generates the following message:
AWSBDW019I Launched job job_name, #Jrun_number for user user_ID.
Failure to launch a job generates the following message:

AWSBDW057E The job job_name was not launched for this reason: error_message
Failure of a check file task generates the following message:

AWSBDW062E Jobman was unable to invoke the following method file method_name for the extended agent. The operating system error is: system_error
Failure of a manage job task generates the following message:
497
Jobman messages
AWSBDW066E Planman has asked jobman to run a task that is not supported on the targeted agent. The following method options file was used: method_options_file. The job identifier and monitor PID are as follows: job, #Jmonitor_pid
When a method sends a message to jobman that is not recognized, the following message is generated:
AWSBDW064E A job that jobman is monitoring has returned the following unrecognizable message: incorrect_message. The job identifier, monitor PID and method file are as follows: job_name, #Jmonitor_pid using method file.
498
Chapter 15. Managing internetwork dependencies

Tivoli Workload Scheduler internetwork dependencies allow jobs and job streams in the local network to use jobs and job streams in a remote network as follows dependencies. This chapter describes how to customize your environment to be able to define internetwork dependencies and how to manage the internetwork dependencies. The chapter is divided into the following sections: v What is new about internetwork dependencies v Internetwork dependencies overview v Configuring a network agent on page 501 v Defining an internetwork dependency on page 503 v Managing internetwork dependencies on page 504 v Internetwork dependencies in a mixed environment on page 507
What is new about internetwork dependencies

The concept of run cycles for job streams and the possibility to schedule more than one instance of the same job stream with the same name and different scheduled date and time within the same production plan introduce the need to link each internetwork dependency to specific instances of a job stream. To do this the following rules are applied in defining and managing internetwork dependencies: v A job is created in the EXTERNAL job stream for each day the referring job stream is scheduled to run. v A job in the EXTERNAL job stream is identified by the script name and the date the referring job stream is planned to run. These rules also apply when dealing with depending jobs defined within job streams scheduled to run for multiple days. These enhancements are described in more detail in the following sections.
Internetwork dependencies overview

Before you specify an internetwork dependency, you must create a workstation definition for the network agent. A network agent is a Tivoli Workload Scheduler workstation that handles follows dependencies between its local network and a remote Tivoli Workload Scheduler network. In the local Tivoli Workload Scheduler network there can be more than one network agent, each representing a specific Tivoli Workload Scheduler remote network where jobs and job streams referring to locally defined internetwork dependencies are defined. Internetwork dependencies are assigned to jobs and job streams in the same way as local follows dependencies, with the exception that the network agents name is included to identify the followed job or job stream. A special job stream named EXTERNAL is automatically created by Tivoli Workload Scheduler for each network agent in the local network. It contains placeholder jobs to represent each internetwork dependency.
499

An EXTERNAL job is created for each internetwork dependency belonging to job streams planned to start in different days with different schedule dates. This means that an EXTERNAL job differs from another one by: v The script file name, which identifies the remote job or job stream the local job or job stream is dependent on. v The date the local job stream containing the internetwork dependency is planned to start. If the dependency is defined in a job within the job stream the date the job stream is planned to start is taken into account. The check of the internetwork dependency check does not start until the job stream matches its time dependency or it is released. In case of two jobs belonging to different job streams and referring to the same internetwork dependency, as one of their job streams is released and the job starts the internetwork dependency is checked and possibly released. In this case when the second job starts to check its internetwork dependency it finds the dependency already solved but not necessarily on the expected day. If you want to prevent this situation from occurring you must rerun the job representing the internetwork dependency after it is solved the first time. Tivoli Workload Scheduler checks the status of the referred jobs and job streams in the remote network and maps their status in the jobs representing the internetwork dependencies in the EXTERNAL job stream. The status of these jobs and job streams is checked over a fixed time interval until the remote job or job stream reaches the SUCC, CANCL, or ERROR state.
Understanding how an internetwork dependency is shown

This section describes a sample scenario about internetwork dependencies and how to link the job representing the internetwork dependency to the job stream where the dependency is defined. Assume that: v You defined a job stream named ELISCHED running on workstation TWS206 containing a job named ELI with an internetwork dependency from a job stream TWS207#FINAL.MAKEPLAN running in a different Tivoli Workload Scheduler network. v XA_MAST is the network agent defined in the local network to manage internetwork dependencies from jobs and job streams defined in that remote network. Use the conman sj command to see the internetwork dependency set:
CPU (Est) (Est) Schedule SchedTime Job State Pr Start Elapse RetCode Deps XA-MAST::"TWS207#MYJS.JOB1"
TWS206#ELISCHE 0600 03/31 **** HOLD 10 (03/31) ELI HOLD 10
where (03/31) represents the at time restriction set in TWS206#ELISCHE. Starting from (03/31) the status of TWS207#MYJS.JOB1 is checked in the remote network to see if the internetwork dependency XA-MAST::"TWS207#MYJS.JOB1" is satisfied. If you run the command:
%sj XA-MAST#EXTERNAL;info
you see the list of jobs representing internetwork dependencies defined in jobs and job streams running in the local network from jobs and job streams defined in the remote network reachable through the network agent XA-MAST:
500

CPU Schedule SchedTime Job JobFile Prompt XA-MAST #EXTERNAL E8802332 TWS207#MYJS.JOB1 Opt Job
You can see the details about the job or job stream depending on TWS207#MYJS.JOB1 in the internetwork dependency represented by job E8802332 in the EXTERNAL job stream, by running the following command:
%sj @#EXTERNAL.E8802332;deps
The output shows the link between the dependent job and the internetwork dependency:
CPU (Est) (Est) Schedule SchedTime Job State Pr Start Elapse RetCode Deps
XA-MAST#EXTERNAL.E8802332 Dependencies are: TWS206#ELISCHE 0600 03/31 **** HOLD 10 (03/31) ELI HOLD 10
XA-MAST::"TWS207#MYJS.JOB1"
The internetwork dependency check does not start until the job stream TWS206#ELISCHE matches its time dependency, (03/31), or is released. If there is another job defined within another job stream in the local network that has a dependency on TWS2007#MYJS.JOB1 and the local job stream is planned to start on the same day, 03/31/06, then also the dependency of this other job on TWS2007#MYJS.JOB1 will be listed in the job E8802332 within the XA-MAST#EXTERNAL job stream.
Configuring a network agent

Network agent workstations are defined as extended agents and require a hosting physical workstation and an access method. The access method for network agents is named netmth. The batchman process on the master domain manager queries the netmth on the network agent at fixed time intervals to get the status of the remote predecessor job or job stream. You can customize the time interval between two consecutive checks by setting the global option bm check status in the localopts file on the master domain manager. The Tivoli Workload Scheduler continues checking until the remote job or job stream reaches the SUCC, CANCL, or ERROR state. An options file named netmth.opts is created on the workstation where the network agent runs. In this file are defined the user under which the access method runs and the time to wait to get a response from the access method before shutting it down. This options file must have the same path as the access method:
TWS_home/methods/netmth.opts
The content of the netmth.opts file has the following structure:

GSuser=login_name GStimeout=seconds
where:
501

login_name Is the login used to run the method. If the network agents host is a Windows computer, this user must be defined in Tivoli Workload Scheduler. seconds Is the number of seconds, Tivoli Workload Scheduler waits for a response before shutting down the access method. The default setting is 300 seconds. The next time batchman needs to check the status of the remote predecessor job or job stream, the access method starts up automatically. Changes to this file do not take effect until you stop and restart Tivoli Workload Scheduler.
A sample network agent definition

The following example shows how to define a network agent workstation for a remote network, Network A, that allows local network, Network B, to use jobs and job streams in the remote network as internetwork dependencies.
Remote Network A
Local Network B
MasterA
MasterB
Network Agent
Figure 16. Local and remote networks
Assuming that: v MasterA is the master domain manager of the remote network, Network A, and that: tws_masterA is the TWS_user defined on MasterA. The TCP port number for MasterA as 12345. The node where MasterA is defined is MasterA.rome.tivoli.com. v MasterB is the master domain manager of the local network, Network B, and that: tws_masterB is the TWS_user defined on MasterB. The node where MasterB is defined is MasterB.rome.tivoli.com. A network agent workstation named NetAgt, defined on MasterB to manage internetwork dependencies on jobs or job streams defined in Network A can be the following:
502

CPUNAME NETAGT DESCRIPTION "NETWORK AGENT" OS OTHER NODE MASTERA.ROME.TIVOLI.COM TCPADDR 12345 FOR maestro HOST MASTERB ACCESS NETMTH END
The options file, netmth.opts defined on MasterB can be:

GSuser=tws_masterB GStimeout=600
Note: The network agent can be defined on either the master domain manager or a fault-tolerant agent.
Defining an internetwork dependency

The syntax used to specify an internetwork dependency within a job stream definition is the following:
follows Network_agent_name::remote_workstation#jobstreamname(time [date]).jobname
where the (time [date]) are specific to the time zone used on the workstation of the remote network the network agent is connected to; in our sample the time zone of MasterA. If (time [date]) is not specified in this syntax or if there is more than one job stream with the same (time [date]), the first job stream found is taken into account.
A sample internetwork dependency definition

Assuming that: v schedA is a job stream defined in the MasterA database. v jobA is a job defined in the MasterA database. v schedB is a job stream defined in the MasterB database. v jobB is a job defined in the MasterB database. you can define internetwork dependencies using the following follows statements: To define an internetwork dependency of schedB from the job stream instance schedA(1100) Use the following statement:
schedule schedB on everyday follows NetAgt::MasterA#schedA(1100) : end
To define an internetwork dependency of jobB from jobA contained in the job stream instance schedA(1100) Use the following statement:
schedule schedB on everyday : jobB : follows NetAgt::MasterA#schedA(1100).jobA
503
Defining an internetwork dependency

: end : end
You can also define internetwork dependencies of a job on a job stream or a job stream on a job.
See Also
For the equivalent Job Scheduling Console task, see Creating Job Streams in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
Managing internetwork dependencies

Internetwork dependencies are managed in the plan from the conman command line by managing the EXTERNAL job stream. Within the EXTERNAL job stream the internetwork dependencies are listed as jobs regardless of whether they are defined for jobs or job streams. There is an EXTERNAL job stream for every network agent in the plan. Within the EXTERNAL job stream, unique job names representing internetwork dependencies are generated as follows:
Ennnmmss
where: nnn mm ss Is a random number. Is the current minutes. Is the current seconds.
The actual name of the job or job stream is stored in the script files specification of the job record. Note: Remote jobs and job streams are defined and run on their local network in the standard manner. Their use as internetwork dependencies has no effect on their local behavior.
States of jobs defined in the EXTERNAL job stream

The status of the jobs defined in the EXTERNAL job stream is determined by the access method and listed in the Release Status field of the EXTERNAL job stream. The reported status refers to the last time the remote network was checked. Jobs might appear to skip states when states change in between two different checks. All states for jobs and job streams, except FENCE, are listed. In addition to these there are two states that are specific to the EXTERNAL jobs, they are: ERROR An error occurred while checking for the remote status. EXTRN The initial state. If the job is not found in the remote network the EXTERNAL job state remains EXTRN. If it isan EXTERNAL job it returns to state EXTRN. Note: If you cancel in the local network the instances of jobs or job streams dependent on the same instance of a job or job stream defined in a remote network, make sure you manually cancel also the job, representing that
504

internetwork dependency in the EXTERNAL job stream, to prevent the EXTERNAL job stream from being continuously carried forward.The same consideration applies when the local job stream dependent on the job or job stream defined in the remote network is not carried forward to the new plan.
Working with jobs defined in the EXTERNAL job stream

These are the available actions you can perform against jobs in an EXTERNAL job stream: Cancel Cancels the EXTERNAL job, releasing the internetwork dependency for all local jobs and job streams. The status of the dependency is no longer checked. Rerun Instructs conman to restart checking the state of the EXTERNAL job. The job state is set to EXTRN immediately after a rerun is performed. Rerun is useful for EXTERNAL jobs in the ERROR state. For example, if an EXTERNAL job cannot be launched because the network access method does not grant execute permission, the job enters the ERROR state and its status ceases to be checked. After you correct the permissions, the method can start but conman will not start checking the EXTERNAL job state until you perform a rerun. Confirm SUCC / ABEND Sets the status of the EXTERNAL job to SUCC or ABEND, releasing the dependency for all depending local jobs and job streams. The status of the dependency in no longer checked. Note: None of these commands has any effect on the remote job or job stream in the remote network. They simply manipulate the dependency for the local network.
Sample internetwork dependency management scenarios

This section provides sample scenarios describing how you can manage internetwork dependency in production using the conman command line commands. Assuming that you have already defined the following: v A local workstation called local1 v A job stream defined for the local workstation local1 called sched1 v A job defined in local1#sched1 called job1 v A network agent called netagt defined in the local network to manage internetwork dependency from jobs and job streams defined in the remote network. v A workstation in the remote network called remote1 v A job stream defined for the remote workstation remote1 called rcshed v A job in defined in remote1#rsched called rjob You can perform the following actions from the conman command line in the local network: Adding an internetwork dependency from a remote job to a local job. For example, to add the remote job rjob as an internetwork dependency for job1, run the following command:
505

adj local1#sched1.job1;follows=netagt::remote1#rsched.rjob
Adding an internetwork dependency from a remote job stream to a local job stream. For example, to add the remote job stream rsched as an internetwork dependency for job stream sched1, run the following command:
ads local1#sched1;follows=netagt::remote1#rsched
Cancelling internetwork dependencies managed by a network agent. For example, to cancel all EXTERNAL jobs for a network agent netagt, run one of the following two commands:
cj netagt#EXTERNAL.@ cj netagt::@
Confirming the successful completion of an internetwork dependency. For example, to confirm that the remote job remote1#rsched.rjob completed successfully and so release the corresponding internetwork dependency, run the following command:
confirm netagt::remote1#rsched.rjob;succ
Deleting an internetwork dependency from a job for a job. For example, to delete the internetwork dependency from the remote job remote1#rsched.rjob for the local job local1#sched1.job1, run the following command:
ddj local1#sched1.job1;follows=netagt::remote1#rsched.rjob
Deleting an internetwork dependency from a job for a job stream. For example, to delete the internetwork dependency from the remote job remote1#rsched.rjob for the local job stream local1#sched1, run the following command:
dds local1#sched1;follows=netagt::remote1#rsched.rjob
Releasing a local job from an internetwork dependency from a remote job. For example, to release a job from an internetwork dependency from a remote job, run the following command:
rj local1#sched1.job1;follows=netagt::remote1#rsched.rjob
Releasing a local job stream from an internetwork dependency from a remote job. For example, to release a job stream from an internetwork dependency from a remote job, run the following command:
rs local1#sched1;follows=netagt::remote1#rsched.rjob
Rerunning a job in the EXTERNAL job stream to restart checking a dependency. For example, to rerun a job belonging to the EXTERNAL job stream to restart checking the internetwork dependency from the remote job remote1#rsched.rjob, run one of the following two commands:
rr netagt#EXTERNAL.rjob rr netagt::remote1#rsched.rjob
Displaying internetwork dependencies from jobs and job streams defined in a remote network. For example, to display all the internetwork dependencies defined for a network agent with their original names and their generated job names, run the following command:
sj netagt#EXTERNAL.@;info
506

Submitting a job with an internetwork dependency from a job stream defined in a remote network For example, to submit a rm command into the JOBS job stream with an internetwork dependency on a remote job stream, run the following command:
sbd "rm apfile";follows=netagt::remote1#rsched
See Also
For the equivalent Job Scheduling Console task, see Creating Job Streams in the IBM Tivoli Workload Scheduler Job Scheduling Console Users Guide.
Internetwork dependencies in a mixed environment

Table 77 shows the supported configuration for internetwork dependencies defined in a mixed version 8.3 environment. The key to the table is as follows: Net_A Wks_B The network agent defined in the local network. The workstation in the remote network that the network agent Net_A is connected to. Wks_B is the workstation that identifies and checks the state of the remote job or job stream specified in the internetwork dependency. The Symphony file processed in the local network. The Symphony file processed in the remote network. Version 8.1, 8.2, or 8.2.1
Net_A 8.3 Sym_A back-level Net_A sends the information to Wks_B as if it had the same version as Wks_B. Net_A back-level Sym_A 8.3 Net_A sends the information to Wks_B in 8.1, 8.2, or 8.2.1 format. The use of the schedtime keyword in the job definition is not supported. Net_A sends the information to Wks_B. If defined, the schedtime keyword in the job definition is automatically removed by Wks_B. Not supported. Net_A sends the information to Wks_B. If defined, the schedtime keyword is parsed by Wks_B. Net_A 8.3 Sym_A 8.3 Net_A sends the information to Wks_B as if it had the same version as Wks_B. If defined, the schedtime keyword in the job definition is automatically removed by Net_A. Net_A sends the information to Wks_B. If defined, the schedtime keyword in the job definition is automatically removed by Wks_B. Not supported. This is a version 8.3 environment.
Sym_A Sym_B back-level
Table 77. Internetwork dependencies in a mixed environment Net_A back-level Sym_A back-level Wks_B back-level Sym_B back-level This is not a mixed version 8.3 environment.
Wks_B 8.3 Sym_B back-level
Wks_B works as if it Net_A sends the had the same version information to Wks_B. as Net_A. If defined, the schedtime keyword in the job definition is automatically removed by Wks_B. Not supported. Not supported. Not supported. Not supported.
Wks_B back-level Sym_B 8.3 Wks_B 8.3 Sym_B 8.3
507
508
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Appendix A. Event-driven workload automation event and action definitions

This appendix documents the event and action providers you can use for event-driven workload automation and gives details on event and action definitions.
Event providers and definitions

This section gives details on the event types of the following event providers: v TWSObjectsMonitor v FileMonitor
TWSObjectsMonitor events
TWSObjectsMonitor events are: v JobStatusChanged v JobUntil v JobSubmit v JobCancel v JobRestart v JobLate v JobStreamStatusChanged v JobStreamCompleted v JobStreamUntil v JobStreamSubmit v JobStreamCancel v JobStreamLate v WorkstationStatusChanged v ApplicationServerStatusChanged v ChildWorkstationLinkChanged v ParentWorkstationLinkChanged v PromptStatusChanged These events are generated by batchman (or mailman for the workstations) and written in a mailbox file named monbox.msg. The scheduling objects are monitored as follows: v Jobs are monitored by the workstation where they run v Job streams are monitored by the master domain manager v Workstations monitor themselves v Local prompts are monitored by the workstation running the job or job stream that have a dependency on the prompt v Global prompts are monitored by the master domain manager The following tables show the parameters of each event type.
JobStatusChanged
This event is sent when the status of a job changes.
509
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 78. Parameters of JobStatusChanged event types.

Property name Description Type Filtering allowed Required Multiple values allowed Multiple filter predicates allowed Wildcard allowed Length Default (minvalue max)
JobWorkstation
The name of the workstation associated with the job instance. The name of the workstation associated with the job stream containing the job instance. The ID of the job stream instance containing the job instance. The name of the job stream instance containing the job instance. The scheduled time of the job stream instance containing the job instance. The name of the job instance. The job priority. True if the job instance is key job. The actual start time of the job instance. Is significant only if the job has already started. The estimated duration of the job. The actual duration of the job. The return code of the job. It is significant only for completed or abended jobs. The value of the until restriction of the job instance. The value of the deadline restriction of the job instance.
string
16
JobStreamWorkstation
string
16
JobStreamID
string
JobStreamName
string
16
JobStreamSchedTime
datetime
JobName Priority Monitored
string numeric (0-101) boolean
U U U
U U
U U U
40
ActualStart
datetime
EstimatedDuration ActualDuration
duration duration
U U
U U
ReturnCode
numeric
LatestStart
datetime
Deadline
datetime string Value can be: Error, Held, Ready, Running, Successful, Undecided, Waiting
Status
The new status of the job instance.
510
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 78. Parameters of JobStatusChanged event types. (continued)

string Value can be: ABEND, ABENP, CANCP, DONE, ERROR, EXEC, EXTRN, FAIL, FENCE, HOLD, INTRO, PEND, READY, RJOB, SCHED, SUCC, SUCCP, SUSP, USER, WAIT, WAITD string duration
InternalStatus
The new internal status of the job instance.
Login EveryFrequency
The login of the user used to run the job. The every frequency of the job instance. A message describing the cause of the job failure. It has significance only when the job instance goes in error (Fail) status. When the event was generated. The fully qualified host name of the computer that sent the event. The IP address of the computer that sent the event. The run number of the Plan running when the event was generated.
U U
U U
ErrorMessage
string
TimeStamp
datetime
Hostname
string
IPAddress
string
PlanNumber
numeric
JobUntil
This event is sent when the latest start time of a job has elapsed.
Table 79. Parameters of JobUntil event types.
JobWorkstation
The name of the workstation associated with the job instance.
string
16
511
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 79. Parameters of JobUntil event types. (continued)

The name of the workstation associated with the job stream containing the job instance. The ID of the job stream instance containing the job instance. The name of the job stream instance containing the job instance. The scheduled time of the job stream instance containing the job instance. The name of the job instance. The job priority. True if the job instance is key job. The estimated duration of the job. The value of the until restriction of the job instance. The value of the deadline restriction of the job instance.
string
16
JobStreamID
string
JobStreamName
string
16
JobStreamSchedTime
datetime
JobName Priority Monitored EstimatedDuration
string numeric (0-101) boolean duration
U U U U
U U
U U U U
40
LatestStart
datetime
Deadline
datetime string Value can be: Cancelled, Error, Held, Ready, Running, Successful, Undecided, Waiting
Status
512
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 79. Parameters of JobUntil event types. (continued)

string Value can be: ABEND, ABENP, CANCL, CANCP, DONE, ERROR, EXEC, EXTRN, FAIL, FENCE, HOLD, INTRO, PEND, READY, RJOB, SCHED, SUCC, SUCCP, SUSP, USER, WAIT, WAITD string duration string The action taken after the until restriction time has elapsed. Value can be: Cancel, Continue, Suppress datetime
InternalStatus
Login EveryFrequency
The login of the user used to run the job. The every frequency of the job instance.
U U
U U
UntilAction
TimeStamp
When the event was generated. The fully qualified host name of the computer that sent the event. The IP address of the computer that sent the event. The run number of the Plan running when the event was generated.
Hostname
string
IPAddress
string
PlanNumber
numeric
JobSubmit
This event is sent when a job is submitted.
Table 80. Parameters of JobSubmit event types.
JobWorkstation
The name of the workstation associated with the job instance.
string
16
513
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 80. Parameters of JobSubmit event types. (continued)

The name of the workstation associated with the job stream containing the job instance. The ID of the job stream instance containing the job instance. The name of the job stream instance containing the job instance. The scheduled time of the job stream instance containing the job instance. The name of the job instance. The job priority. True if the job instance is key job. The estimated duration of the job. The value of the until restriction of the job instance. The value of the deadline restriction of the job instance. The login of the user used to run the job. The every frequency of the job instance. When the event was generated. The fully qualified host name of the computer that sent the event. The IP address of the computer that sent the event. The run number of the Plan running when the event was generated.
string
16
JobStreamID
string
JobStreamName
string
16
JobStreamSchedTime
datetime
JobName Priority Monitored EstimatedDuration
string numeric (0-101) boolean duration
U U U U
U U
U U U U
40
LatestStart
datetime
Deadline
datetime
Login
string
EveryFrequency TimeStamp
duration datetime
Hostname
string
IPAddress
string
PlanNumber
numeric
JobCancel
This event is sent when a job is cancelled.
514
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 81. Parameters of JobCancel event types.

JobWorkstation
The name of the workstation associated with the job instance. The name of the workstation associated with the job stream containing the job instance. The ID of the job stream instance containing the job instance. The name of the job stream instance containing the job instance. The scheduled time of the job stream instance containing the job instance. The name of the job instance. The job priority. True if the job instance is key job. The actual start time of the job instance. Is significant only if the job has already started. The estimated duration of the job. The actual duration of the job. The return code of the job. It is significant only for completed or abended jobs. The value of the until restriction of the job instance. The value of the deadline restriction of the job instance.
string
16
string
16
JobStreamID
string
JobStreamName
string
16
JobStreamSchedTime
datetime
JobName Priority Monitored
U U U
U U
U U U
40
ActualStart
datetime
EstimatedDuration ActualDuration
duration duration
U U
U U
ReturnCode
numeric
LatestStart
datetime
Deadline
datetime string Value can be: Cancelled, Error, Held, Ready, Running, Successful, Undecided, Waiting
Status
515
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 81. Parameters of JobCancel event types. (continued)

string Value can be: ABEND, ABENP, CANCL, CANCP, DONE, ERROR, EXEC, EXTRN, FAIL, FENCE, HOLD, INTRO, PEND, READY, RJOB, SCHED, SUCC, SUCCP, SUSP, USER, WAIT, WAITD string
InternalStatus
Login
The login of the user used to run the job. The every frequency of the job instance. When the event was generated. The fully qualified host name of the computer that sent the event. The IP address of the computer that sent the event. The run number of the Plan running when the event was generated.
EveryFrequency
duration
TimeStamp
datetime
Hostname
string
IPAddress
string
PlanNumber
numeric
JobRestart
This event is sent when a job is restarted.
Table 82. Parameters of JobRestart event types.
Property name Description Type Filtering allowed Required Multiple values allowed Multiple filter predicates allowed Wildcard allowed Length (minmax) Default value
JobWorkstation
The name of the workstation associated with the job instance. The name of the workstation associated with the job stream containing the job instance.
string
16
string
16
516
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 82. Parameters of JobRestart event types. (continued)

JobStreamID
The ID of the job stream instance containing the job instance. The name of the job stream instance containing the job instance. The scheduled time of the job stream instance containing the job instance. The name of the job instance. The job priority. True if the job instance is key job. The actual start time of the job instance. Is significant only if the job has already started. The estimated duration of the job. The actual duration of the job. The return code of the job. It is significant only for completed or abended jobs. The value of the until restriction of the job instance. The value of the deadline restriction of the job instance. The login of the user used to run the job. The every frequency of the job instance. When the event was generated. The fully qualified host name of the computer that sent the event. The IP address of the computer that sent the event.
string
JobStreamName
string
16
JobStreamSchedTime
datetime
JobName Priority
U U
U U
U U
40
Monitored
ActualStart
datetime
EstimatedDuration
duration
ActualDuration
duration
ReturnCode
numeric
LatestStart
datetime
Deadline
datetime
Login
string
EveryFrequency
duration
TimeStamp
datetime
Hostname
string
IPAddress
string
517
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 82. Parameters of JobRestart event types. (continued)

PlanNumber
The run number of the Plan running when the event was generated.
numeric
JobLate
This event is sent when a job becomes late. To properly use this event type and to trigger an action, you must configure local option:
bm check deadline = 300
See the Planning and Installation guide for further reference.

Table 83. Parameters of JobLate event types.
JobWorkstation
The name of the workstation associated with the job instance. The name of the workstation associated with the job stream containing the job instance. The ID of the job stream instance containing the job instance. The name of the job stream instance containing the job instance. The scheduled time of the job stream instance containing the job instance. The name of the job instance. The job priority. True if the job instance is key job. The actual start time of the job instance. Is significant only if the job has already started. The estimated duration of the job.
string
16
string
16
JobStreamID
string
JobStreamName
string
16
JobStreamSchedTime
datetime
JobName Priority
U U
U U
U U
40
Monitored
ActualStart
datetime
EstimatedDuration
duration
518
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 83. Parameters of JobLate event types. (continued)

Property name Description Type Filtering allowed Required Multiple values allowed Multiple filter predicates allowed U Wildcard allowed Length Default (minvalue max)
ActualDuration
The actual duration of the job. The return code of the job. It is significant only for completed or abended jobs. The value of the until restriction of the job instance. The value of the deadline restriction of the job instance.
duration
ReturnCode
numeric
LatestStart
datetime
Deadline
datetime
string Value can be: Cancelled, Error, Held, Ready, Running, Successful, Undecided, Waiting string Value can be: ABEND, ABENP, CANCL, CANCP, DONE, ERROR, EXEC, EXTRN, FAIL, FENCE, HOLD, INTRO, PEND, READY, RJOB, SCHED, SUCC, SUCCP, SUSP, USER, WAIT, WAITD string
Status
InternalStatus
Login
The login of the user used to run the job. The every frequency of the job instance. When the event was generated. The fully qualified host name of the computer that sent the event.
EveryFrequency
duration
TimeStamp
datetime
Hostname
string
519
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 83. Parameters of JobLate event types. (continued)

IPAddress
The IP address of the computer that sent the event. The run number of the Plan running when the event was generated.
string
PlanNumber
numeric
JobStreamStatusChanged
This event is sent when the status of a job stream changes.
Table 84. Parameters of JobStreamStatusChanged event types.
Workstation
The name of the workstation associated with the job stream instance. This is the same value as the Job Stream Workstation property, but is used for correlation with other events. The name of the workstation associated with the job stream instance (same value as in Workstation. The ID of the job stream instance. The name of the job stream instance. The scheduled time of the job stream instance. The job stream priority. True if the job stream instance contains key jobs. The value of the until restriction of the job stream instance. The value of the deadline restriction of the job stream instance.
string
string
16
JobStreamID
string
JobStreamName
string
16
JobStreamSchedTime
datetime numeric (0-101)
Priority
Monitored
boolean
LatestStart
datetime
Deadline
datetime
520
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 84. Parameters of JobStreamStatusChanged event types. (continued)

string Value can be: Blocked, The new status Cancelled, of the job stream Error, instance. Held, Ready, Running, Successful, Undecided, Waiting string Value can be: ABEND, ABENP, CANCP, DONE, ERROR, EXEC, EXTRN, FAIL, FENCE, HOLD, INTRO, PEND, READY, RJOB, SCHED, SUCC, SUCCP, SUSP, USER, WAIT, WAITD datetime
Status
InternalStatus
The new internal status of the job stream instance.
TimeStamp
Hostname
string
IPAddress
string
PlanNumber
numeric
JobStreamCompleted
This event is sent when a job stream has completed.
521
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 85. Parameters of JobStreamCompleted event types.

Workstation
string
string
16
JobStreamID
string
JobStreamName
string
16
JobStreamSchedTime
datetime numeric (0-101)
Priority
Monitored
boolean
LatestStart
datetime
Deadline
datetime
string The new status of the job stream instance. Value can be: Cancelled, Error, Successful string The new internal status of the job stream instance. Value can be: ABEND, CANCL, SUCC datetime
Status
InternalStatus
TimeStamp
When the event was generated. The fully qualified host name of the computer that sent the event.
Hostname
string
522
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 85. Parameters of JobStreamCompleted event types. (continued)

IPAddress
The IP address of the computer that sent the event. The run number of the Plan running when the event was generated.
string
PlanNumber
numeric
JobStreamUntil
This event is sent when the latest start time of a job stream has elapsed.
Table 86. Parameters of JobStreamUntil event types.
Property name Description Type Filtering allowed Required Multiple Multiple filter values predicates allowed allowed Wildcard allowed Length (min-max) Default value
Workstation
string
string
16
JobStreamID JobStreamName
string string U U U U U 1 16 *
JobStreamSchedTime
datetime numeric (0-101) boolean
Priority
Monitored
LatestStart
datetime
Deadline
datetime
523
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 86. Parameters of JobStreamUntil event types. (continued)

Property name Description Type Filtering allowed Required Multiple Multiple filter values predicates allowed allowed Wildcard allowed Length (min-max) Default value
string Value can be: Blocked, The new status of Cancelled, the job stream Error, instance. Held, Ready, Running, Successful, Undecided, Waiting string Value can be: ABEND, ABENP, CANCL, CANCP, DONE, ERROR, EXEC, EXTRN, FAIL, FENCE, HOLD, INTRO, PEND, READY, RJOB, SCHED, SUCC, SUCCP, SUSP, USER, WAIT, WAITD string The action taken after the until restriction time has elapsed. Value can be: Cancel, Continue, Suppress datetime
Status
InternalStatus
UntilAction
TimeStamp
Hostname
string
IPAddress
string
PlanNumber
numeric
JobStreamSubmit
This event is sent when a job stream is submitted.
524
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 87. Parameters of JobStreamSubmit event types.

Property name Description Type Filtering allowed Required Multiple Multiple filter values predicates allowed allowed Wildcard allowed Length (minmax) Default value
Workstation
The name of the workstation associated with the job stream instance. This is the same value as the Job Stream Workstation property, but is used for correlation with other events. The name of the workstation associated with the job stream instance (same value as in Workstation. The ID of the job stream instance. The name of the job stream instance. The scheduled time of the job stream instance. The job stream priority. True if the job stream instance contains key jobs. The value of the until restriction of the job stream instance. The value of the deadline restriction of the job stream instance. When the event was generated. The fully qualified host name of the computer that sent the event. The IP address of the computer that sent the event. The run number of the Plan running when the event was generated.
string
string
16
JobStreamSchedTime
Priority
Monitored
LatestStart
datetime
Deadline
datetime
TimeStamp
datetime
Hostname
string
IPAddress
string
PlanNumber
numeric
JobStreamCancel
This event is sent when a job stream is cancelled.
525
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 88. Parameters of JobStreamCancel event types.

Workstation
string
string
16
JobStreamSchedTime
Priority
Monitored
LatestStart
datetime
Deadline
datetime
string Value can be: Blocked, Cancelled, Error, Held, Ready, Running, Successful, Undecided, Waiting
Status
The new status of the job stream instance.
526
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 88. Parameters of JobStreamCancel event types. (continued)

string Value can be: ABEND, ABENP, CANCL, CANCP, DONE, ERROR, EXEC, EXTRN, FAIL, FENCE, HOLD, INTRO, PEND, READY, RJOB, SCHED, SUCC, SUCCP, SUSP, USER, WAIT, WAITD datetime
InternalStatus
TimeStamp
Hostname
string
IPAddress
string
PlanNumber
numeric
JobStreamLate
This event is sent when a job stream becomes late. To properly use this event type and to trigger an action, you must configure local option:
bm check deadline = 300
See the Planning and Installation guide for further reference.

Table 89. Parameters of JobStreamLate event types.
Workstation
The name of the workstation associated with the job stream instance.
string
527
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 89. Parameters of JobStreamLate event types. (continued)

The name of the workstation associated with the job stream instance (same value as in Workstation. The ID of the job stream instance. The name of the job stream instance. The scheduled time of the job stream instance. The job stream priority. True if the job stream instance contains key jobs. The value of the until restriction of the job stream instance. The value of the deadline restriction of the job stream instance.
string
16
JobStreamSchedTime
Priority
Monitored
LatestStart
datetime
Deadline
datetime
string Value can be: Blocked, Cancelled, Error, Held, Ready, Running, Successful, Undecided, Waiting string Value can be: ABEND, ABENP, CANCL, CANCP, DONE, ERROR, EXEC, EXTRN, FAIL, FENCE, HOLD, INTRO, PEND, READY, RJOB, SCHED, SUCC, SUCCP, SUSP, USER, WAIT, WAITD datetime
Status
The new status of the job stream instance.
InternalStatus
TimeStamp
When the event was generated.
528
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 89. Parameters of JobStreamLate event types. (continued)

Hostname
The fully qualified host name of the computer that sent the event. The IP address of the computer that sent the event. The run number of the Plan running when the event was generated.
string
IPAddress
string
PlanNumber
numeric
WorkstationStatusChanged
This event is sent when a workstation is started or stopped.
Table 90. Parameters of WorkstationStatusChanged event types.
Property name Description Type Filtering allowed Required Multiple values allowed U Multiple filter predicates allowed U Wildcard allowed Length (minmax) 1 16 Default value
Workstation
The name of the workstation. TRUE if the workstation is running. FALSE if it is stopped. The reason why batchman (or jobman) was terminated. Significant only if one of them is not running. The date and time when the event was generated. The fully qualified host name of the computer that sent the event. The IP address of the computer that sent the event.
string
Running
boolean
string Value can be: Abend, Stop 1
StopReason
TimeStamp
datetime
Hostname
string
IPAddress
string
PlanNumber
The run number of the Plan running when the numeric event was generated.
ApplicationServerStatusChanged
This event is sent when the embedded WebSphere Application Server has stopped or is restarting.
529
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 91. Parameters of ApplicationServerStatusChanged event types.

Property name Description Type Filtering allowed Required Multiple values allowed U Multiple filter predicates allowed U Wildcard allowed Length (minmax) 1 16 Default value
Workstation
The name of the workstation True if the application server on the workstation is running, False if stopped. The reason why the application server was terminated. Significant only if it is not running. True if the system will retry automatically to start the application server. Significant only if the application server is not running. The reason why the system will not automatically start the application server. Is significant only if the application server is not running and Restarting is false. The date and time when the event was generated. The fully qualified hostname of the computer that sent the event. The IP address of the computer that sent the event. The run number of the Plan running when the event was generated.
string
Running
boolean
string Value can be: Unexpected end, Stop U 1
StopReason
Restarting
boolean
string Value can be: No auto start, Maximum restart exceeded, Terminated too quickly
NoRestartReason
TimeStamp
datetime
Hostname
string
IPAddress
string
PlanNumber
numeric
ChildWorkstationLinkChanged
This event is sent when the workstation defined in the event rule links or unlinks one of its child workstations.
530
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 92. Parameters of ChildWorkstationLinkChanged event types.

Workstation
The name of the child workstation that is changing link status. The name of the workstation that is sending the event.
string
16
ParentWorkstation
string
16
string LinkStatus The new link status of the workstation. Value can be: Linked, Unlinked U 1
UnlinkReason
Shows the string reason why the workstation Value was unlinked. can be: Available only Broken, if LinkStatus is Dropped Unlinked. When the event datetime was generated. The fully qualified hostname of the computer that sent the event. The IP address of the computer that sent the event. The run number of the Plan running when the event was generated.
TimeStamp
Hostname
string
IPAddress
string
PlanNumber
numeric
ParentWorkstationLinkChanged
This event is sent when the parent workstation of the workstation defined in the event rule is linked or unlinked. The parent workstation will send a ChildWorkstationLinkChanged event when the link in the other direction is established or lost.
Table 93. Parameters of ParentWorkstationLinkChanged event types.
Property name Description Type Filtering Required allowed Multiple values allowed Multiple filter predicates allowed Wildcard allowed Length (min-max) Default value
Workstation
The name of the workstation that is sending the event. The name of the parent workstation that is changing link status.
string
16
ParentWorkstation
string
16
531
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 93. Parameters of ParentWorkstationLinkChanged event types. (continued)

Property name Description Type Filtering Required allowed Multiple values allowed Multiple filter predicates allowed Wildcard allowed Length (min-max) Default value
string LinkStatus The new link status of the workstation. Value can be: Linked, Unlinked U 1
UnlinkReason
Shows the reason string why the workstation was Value unlinked. can be: Available only if Broken, LinkStatus is Dropped Unlinked. When the event was generated. The fully qualified host name of the computer that sent the event. The IP address of the computer that sent the event. The run number of the Plan running when the event was generated. datetime
TimeStamp
Hostname
string
IPAddress
string
PlanNumber
numeric
PromptStatusChanged
This event is sent when a prompt is asked or replied.
Table 94. Parameters of PromptStatusChanged event types.
Property name Description Type Filtering allowed Required Multiple values allowed Multiple filter predicates allowed U Wildcard allowed Length (minmax) Default value
Name
The name or the number of the prompt. The text of the prompt.
string
Text
string string
Status
The status of the prompt.
Value can be: Asked, RepliedNo, RepliedYes string
Type
The type of the prompt.
Value can be: Global, JobLocal, JobStreamLocal
RecoveryPrompt
Indicates if the prompt is a recovery prompt. Available only when the status is asked.
boolean
532
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 94. Parameters of PromptStatusChanged event types. (continued)

Workstation
The name of the workstation associated with the job instance or job stream instance that owns the prompt. Available only for local prompts. The name of the workstation associated with the job stream instance that owns the prompt (or that contains the job instance that owns the prompt). Available only for local prompts. The ID of the job stream instance that owns the prompt (or that contains the job instance that owns the prompt). Available only for local prompts. The name of the job stream instance that owns the prompt (or that contains the job instance that owns the prompt). Available only for local prompts. The scheduled time of the job stream instance that owns the prompt (or that contains the job instance that owns the prompt). Available only for local prompts. The name of the job instance that owns the prompt. Available only for local prompts owned by jobs.
string
string
JobStreamID
string
JobStreamName
string
JobStreamSchedTime
datetime
JobName
string
533
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 94. Parameters of PromptStatusChanged event types. (continued)

TimeStamp
datetime
Hostname
string
IPAddress
string
PlanNumber
numeric
FileMonitor events
FileMonitor events are: v FileCreated v FileDeleted v ModificationCompleted v LogMessageWritten The following tables show the parameters of each event type.
FileCreated
This event is sent when a specified file is created.
Table 95. Parameters of FileCreated event types.
Property name Description The absolute path and filename(s) of the specified file(s). The interval (in seconds) with which the specified file is monitored. numeric The name of the workstation for which the event is generated. The time when the event is sent. The fully qualified host name of the computer that sends the event. The IP address of the computer that sends the event. The identifier of the event rule. Type Filtering allowed Required Multiple values allowed Multiple filter predicates allowed Wildcard allowed Length (minmax) 1 Default value
FileName
string
SampleInterval
numeric
60
Workstation
string
16
TimeStamp
datetime
Hostname
string
IPAddress
string
EventRuleId
string
FileDeleted
This event is sent when a specified file is deleted.
534
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 96. Parameters of FileDeleted event types.

Property name Description The absolute path and filename(s) of the specified file(s). The interval (in seconds) with which the specified file is monitored. numeric The name of the workstation for which the event is generated. The time when the event is sent. The fully qualified host name of the computer that sends the event. The IP address of the computer that sends the event. The identifier of the event rule. Type Filtering allowed Required Multiple values allowed Multiple filter predicates allowed Wildcard allowed Length (minmax) 1 Default value
FileName
string
SampleInterval
numeric
60
Workstation
string
16
TimeStamp
datetime
Hostname
string
IPAddress
string
EventRuleId
string
ModificationCompleted
This event is sent when a specified file has not been modified in two consecutive monitoring cycles after any of the following: v Its creation v A detected modification.
Table 97. Parameters of ModificationCompleted event types.
Property name Description The absolute path and filename(s) of the specified file(s). The interval (in seconds) with which the specified file is monitored. numeric The time when the specified file was last modified. The name of the workstation for which the event is generated. The time when the event is sent. The fully qualified host name of the computer that sends the event. The IP address of the computer that sends the event. The identifier of the event rule. Type Filtering allowed Required Multiple values allowed Multiple filter predicates allowed Wildcard allowed Length (minmax) 1 Default value
FileName
string
SampleInterval
numeric
60
LastWriteTime
datetime
Workstation
string
16
TimeStamp
datetime
Hostname
string
IPAddress
string
EventRuleId
string
535
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
LogMessageWritten
This event is sent when a specific string is found in a file. Be aware of the following when you change or delete and create the file again during the monitoring activity: v The matches parameter counts the total number of matches found since monitoring started. It does not report the number of matches currently in the file. If you change the file while monitoring is in progress, there may be a discrepancy between the number of matches recorded and the ones presently shown in the file. v The scanning mechanism is such that at each sample period, scanning is picked up from the last know position. Already scanned portions of the file are not checked again. If you make changes to a file section that has already undergone scanning, these changes will not be detected in the current monitoring process.
Table 98. Parameters of LogMessageWritten event types.
FileName
The absolute path and filename(s) of the specified file(s). The number of matches found since monitoring started. The string to look for in the log file(s) being monitored. The time when the specified file was last modified. The size of the log file (in bytes) when the most recent matching log file entry was found. The interval (in seconds) with which the specified file is monitored. numeric The name of the workstation for which the event is generated. The time when the event is sent. The fully qualified host name of the computer that sends the event. The IP address of the computer that sends the event. The contents of the line where the search string was found. The identifier of the event rule.
string
Matches
numeric
MatchExpression
string
LastWriteTime
datetime
Size
filesize
SampleInterval
numeric
60
Workstation
string
16
TimeStamp
datetime
Hostname
string
IPAddress
string
Linetext
string
EventRuleId
string
Datetime Contains both date and time. You can specify either one or both values in the filter.
536
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
LOB Severity
Multiple filter predicates allowed You can specify multiple filter predicates for this property. The event will match the event condition if all the predicates are satisfied. Multiple values allowed You can specify multiple values for this property within a single filter predicate. The filter will be satisfied when one of the values is matched. Wildcard allowed Supported wildcards are asterisk (*) and question mark (?).
Action providers and definitions

This section gives details on the action types of the following action providers: v TECEventForwarder v MailSender v MessageLogger v TWSAction v GenericAction
TECEventForwarder actions
This provider implements a single action named TECFWD that forwards the event to an external TEC (Tivoli Enterprise Console) server (or any other application capable of listening to events in TEC format). The provider uses a default TEC server whose host name and port can be defined with optman. The TEC used as recipient can be overridden by action settings. The following table lists the parameters of TECFWD:
Table 99. Parameters of TECFWD action types. Property name Host Port Message Description Host name or IP of the TEC recipient Port number of the TEC recipient The event message The severity of the event message The line of business impacted by the situation reported by the event Type string numeric string string Value can be: Critical, Fatal, Normal, Warning string U 1 U Required Length (min-max) 1 1 1 Default value
537
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 99. Parameters of TECFWD action types. (continued) Property name Parm_1 Parm_2 Parm_3 Parm_4 Parm_5 Parm_6 Parm_7 Parm_8 Parm_9 Parm_10 Custom parameters Description Type string string string string string string string string string string Required Length (min-max) 1 1 1 1 1 1 1 1 1 1 Default value
MailSender actions
This provider implements a single action named SendMail that connects to an SMTP server to send an e-mail. You can use optman to customize the following related attributes: v Mail sender v SMTP server v SMTP port number v Mail user name v Mail user password v SSL The following table lists the parameters of SendMail:
Table 100. Parameters of SendMail action types. Property name Description The main receiver list. Multiple addresses can be specified using commas as separators. The copied receiver list. Multiple addresses can be specified using commas as separators. The blank copied receiver list. Multiple addresses can be specified using commas as separators. The subject of the mail. The body of the mail. Type Required Length (min-max) Default value
To
string
Cc
string
Bcc
string
Subject Body
string string
1 1
538
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
MessageLogger actions
This provider implements a single action named MSGLOG that logs the occurrence of a situation in an internal auditing database. The number of entries within the auditing database is configurable. There is an automatic cleanup based on a FIFO policy. The following table lists the parameters of MSGLOG:
Table 101. Parameters of MSGLOG action types. Property name Message Description The message Type string string The severity of the message Value can be: Info, Warning, Error Default is Info ObjectKey A key identifying the object to which the message pertains A custom string that identifies the source The line of business impacted by the situation reported by the message The group of operators in whose queue the message is placed string U 1 Required U Length (min-max) 1 Default value
Severity
Info
Source
string
LOB
string
Group
string
TWSAction actions
TWSAction actions are: v SubmitJobStream v SubmitJob v SubmitAdHocJob v ReplyPrompt The following tables show the parameters of each action type.
SubmitJobStream
This action submits a job stream.
Table 102. Parameters of SubmitJobStream action types. Property name JobStreamName Description The name of the job stream The name of the workstation associated with the job streami Type string string JobStreamWorkstationName Value can be: Info, Warning, Error U 1 16 Required U Length (min-max) 1 16 Default value
539
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 102. Parameters of SubmitJobStream action types. (continued) Property name JobStreamSchedTime JobStreamAlias Parm_1 Parm_2 Parm_3 Parm_4 Parm_5 Parm_6 Parm_7 Parm_8 Parm_9 Parm_10 Custom parameters Description The scheduled time of the job stream instance The job stream alias Type datetime string string string string string string string string string string string 1 1 1 1 1 1 1 1 1 1 1 16 Required Length (min-max) Default value
SubmitJob
This action submits a job.
Table 103. Parameters of SubmitJob action types. Property name Description The name of the job as defined in the database Type Required Length (minmax) 1 40 Default value
JobDefinitionName
string
The name of the workstation associated JobDefinitionWorkstationName with the job as defined in the database JobJStreamName The name of the job stream that contains the job The name of the workstation associated with the job stream
string
16
string
16
JobJStreamWorkstationName
string string
16
SchedTimeResolutionCriteria
Value can be: Previous (closest The resolution criteria for the scheduled time of the previous job stream), Next (closest next job job stream instance stream), Any (closest previous or closest next job stream) The job alias Generate a unique alias for the job string boolean U 1 40 true
JobAlias JobUseUniqueAlias
540
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 103. Parameters of SubmitJob action types. (continued) Property name Parm_1 Parm_2 Parm_3 Parm_4 Parm_5 Parm_6 Parm_7 Parm_8 Parm_9 Parm_10 Custom parameters Description Type string string string string string string string string string string Required Length (minmax) 1 1 1 1 1 1 1 1 1 1 Default value
SubmitAdHocJob
This action submits an ad hoc job.
Table 104. Parameters of SubmitAdHocJob action types. Property name JobTask JobLogin JobPriority Description The task to execute The login name the job priority The name of the workstation associated with the job The name of the job stream that contains the job The name of the workstation associated with the job stream Type string string numeric 0-101 Default is 10 string string string string Value can be: Previous (closest previous job stream), Next (closest next job stream), Any (closest previous or closest next job stream) string boolean U 1 40 true U Required U U Length (min-max) 1 1 1 10 Default value
JobWorkstationName JobJStreamName JobJStreamWorkstationName
1 1 1
16 16 16
SchedTimeResolutionCriteria
The resolution criteria for the scheduled time of the job stream instance
JobAlias JobUseUniqueAlias
The job alias Generate a unique alias for the job
541
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 104. Parameters of SubmitAdHocJob action types. (continued) Property name Description Type string JobType The job type Value can be: Script or Command U 1 Script Required Length (min-max) Default value
ReplyPrompt
This action replies to a prompt.
Table 105. Parameters of ReplyPrompt action types. Property name PromptName Description The name of the prompt Type string string PromptAnswer The reply to the prompt Value can be: ReplyYes or ReplyNo U 1 Required U Length (min-max) 1 8 Default value
GenericAction actions
This provider implements a single action named RunCommand that runs non-Tivoli Workload Scheduler commands. Commands are run on the same computer where the event processor runs. The following table lists the parameters of RunCommand:
Table 106. Parameters of RunCommand action types. Property name Command Description The command that must be run The location where the command is to be run Type string string WorkingDir Value can be: Info, Warning, Error Required U Length (min-max) Default value
542
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Table 106. Parameters of RunCommand action types. (continued) Property name Param1 Param2 Param3 Param4 Param5 Param6 Param7 Param8 Param9 Param10 Param11 Param12 Param13 Param14 Param15 Env1 Env2 Env3 Env4 Env5 Env6 Env7 Env8 Env9 Env10 Env11 Env12 Env13 Env14 Env15 Environment parameters for the command Command parameters Description Type string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string Required Length (min-max) Default value
543
544
Appendix B. Web services interface

Using the Web Services Interface you can use the Web Services access mechanism to create your own client application to perform a subset of Tivoli Workload Scheduler functions to manage jobs and job streams in the plan. Whenever you install a Tivoli Workload Scheduler workstation the following WSDL files:
SchedulingFactory.wsdl JobService.wsdl JobstreamService.wsdl
are automatically installed on the machine in the directory where the Tivoli Workload Scheduler is installed under the following path:
.\appserver\profiles\twsprofile\installedApps\DefaultNode\ TWSEngineModel.ear\PlanServicesWeb.war\WEB-INF
These WSDL files provide you with: v The server part interfacing the master domain manager to perform the supported subset of scheduling operations against jobs and job streams in production. v A means of creating your own client interface from where service requesters can request to perform a subset of operations from any system in your environment by accessing the following location:
https://localhost:31116/PlanServicesWeb/services/service_name for distributed environment https://localhost:31126/PlanServicesWeb/services/service_name for z/OS environment
where localhost must be replaced manually with the hostname of the master domain manager, and service_name is the name of the service you invoke, that is SchedulingFactory, JobService, or JobStreamService. You can also modify the port number to use when binding to the master domain manager, 31116 for distributed environment or 31126 for z/OS environment. Service requesters can create job streams and jobs in the plan by submitting actions (submitJobStream, submitJob, submitJobAdHoc), to monitor the submitted objects by getting actions (queryJobStreams, queryJobs, getJobsList, getProperties, getJobOutput), and to manage them by setting actions (setProperties, cancel, kill, releaseAllDependencies). Neither database actions nor other plan actions can be implemented and invoked using this interface. Table 107 on page 546 shows, for each of the three services provided, the messages implementing the JAVA methods invoked when performing actions and an explanation of the action you need to perform.
545
Web services interface

Table 107. Available messages in the Web services interface Services SchedulingFactory Messages submitJobStream submitJob submitAdHocJob queryJobs queryJobStreams JobStreamService getProperties setProperties getJobsList cancel releaseAllDependencies JobService getProperties setProperties getOutput kill cancel releaseAllDependencies Actions performed Submits job streams. Submits jobs. Submits jobs in production. Lists all job instances matching the filtering criteria. Lists all job stream instances matching the filtering criteria. Displays job stream properties. Sets specified properties for a job stream instance. Lists all jobs contained in a job stream. Cancels a job stream instance. Releases all dependencies for a job stream instance. Displays job properties. Sets specified properties for a job instance. Gets a job instance output. Kills a job instance. Cancels a job instance. Releases all dependencies for a job instance.
For more information on how to manage WSDL files to create your own Web Services-based user interface you can refer to the IBM redbook WebSphere Version 5.1 Application Developer 5.1.1 Web Services Handbook.
546
Appendix C. Quick reference for commands

This appendix is divided into four sections: v Managing the plan v Managing objects in the database on page 548 v Managing objects in the plan on page 557 v Utility commands on page 561 v Report commands on page 563
Managing the plan

This section describes the operations you can perform against the plan using the JnextPlan script and the planman command line:
Table 108. Commands used against the plan Command or script syntax JnextPlan [-from mm/dd/[yy]yy[hhmm[tz | timezone tzname]]] {-to mm/dd/[yy]yy[hhmm[tz | timezone tzname]] | -for [h]hhmm [-days n] | -days n} planman [connection_parameters] crt [from mm/dd/[yy]yy [hhmm [tz | timezone tzname]] ] {-to mm/dd/[yy]yy[hhmm[tz | timezone tzname]] | -for [h]hhmm [-days n] | -days n} Creates an intermediate production plan. Action performed Creates or extends the production plan.
| |
planman [connection_parameters] deploy [-scratch] planman [connection_parameters] ext {-to mm/dd/[yy]yy[hhmm[tz | timezone tzname]] | -for [h]hhmm [-days n] | -days n} planman [connection_parameters] showinfo planman [connection_parameters] crttrial file_name [ from mm/dd/[yy]yy [hhmm [tz | timezone tzname]]] {-to mm/dd/[yy]yy[hhmm[tz | timezone tzname]] | -for [h]hhmm [-days n] | -days n} planman [connection_parameters] exttrial file_name {-to mm/dd/[yy]yy[hhmm[tz | timezone tzname]] | -for [h]hhmm [-days n] | -days n}
Deploys all rules that are not in draft state. Creates an intermediate plan for a plan extension.
Retrieves the production plan information. Creates a trial plan.
Creates a trial plan of a production plan extension.
547
Managing the plan

Table 108. Commands used against the plan (continued) Command or script syntax planman [connection_parameters] crtfc file_name [ from mm/dd/[yy]yy [hhmm [tz | timezone tzname]]] {-to mm/dd/[yy]yy[hhmm[tz | timezone tzname]] | -for [h]hhmm [-days n] | -days n} planman [connection_parameters] unlock ResetPlan [connection_parameters] [-scratch] Unlocks the production plan. Resets the production plan. Action performed Creates a forecast plan.
where connection_parameters are the following:

[-file filename] [-host hostname] [-port port_name] [-protocol protocol_name][-proxy proxy_name] [-proxyport proxy_port_number] [-password user_password] [-timeout seconds] [-username user_name]
Managing objects in the database

The section is divided into the following subsections: v General purpose commands v Scheduling objects on page 549 v Composer commands on page 553
General purpose commands

This section describes the names, the syntax of general purpose commands that are run from the composer program, and the user authorization, when needed, that is necessary to run them.
Table 109. General purpose commands Command continue edit exit help redo validate version Syntax composer "continue&command argument&command argument" composer ed[it]filename e[xit] help commandname composer redo directives validate filename [;syntax] v[ersion] User Authorization Authorization for using composer Authorization for using composer Authorization for using composer Authorization for using composer Authorization for using composer Authorization for using composer Authorization for using composer
548
Scheduling objects
Scheduling objects
This section contains all scheduling objects definition syntax. In the table displaying the list of commands that can be used against the scheduling object, filename indicates an existing file when used in the syntax for the add and replace commands, it indicates a not existing file when used in the syntax for the create/extract command.
Calendar
File definition syntax: $calendar calendarname [description] date [...]
Domain
File definition syntax: domain domainname[description description] * manager workstation [parent domainname | ismaster] end | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Event rule
XML definition syntax: v <eventRule name=" " ruleType=" " isDraft=" "> (1, 1) <description> (0, 1) <timeZone> (0, 1) <validity from=" " to=" "> (0, 1) <activeTime start=" " end=" "> (0, 1) <timeInterval amount=" " unit=" "> (0, 1) <eventCondition eventProvider=" " eventType=" "> (1, n) - <scope> (0, 1) - <filteringPredicate> (0, 1) v <attributeFilter name=" " operator="eq"> (0, n) <value> (1, n) v <attributeFilter name=" " operator="ne"> (0, n) <value> (1, n) v <attributeFilter name=" " operator="le"> (0, n) <value> (1, 1) v <attributeFilter name=" " operator="ge"> (0, n) <value> (1, 1) v <attributeFilter name=" " operator="range"> (0, 1) <value> (1, 2) <correlationAttributes> (0, 1) - <attribute name=" "> (1, n) <action actionProvider=" " actionType=" " responseType=" "> (0, n) - <description> (0, 1) - <scope> (0, 1) - <parameter name=" ">(1, n) - <value> (1, 1)
Job
File definition syntax: $jobs [workstation#]jobname
549
Scheduling objects
{scriptname filename | docommand command} streamlogon username [description description] [tasktype tasktype] [interactive]1 [rccondsucc Success Condition] [recovery {stop | continue | rerun} [after [workstation#]jobname] [abendprompt text] ] Notes: 1. This keyword is available on Windows platforms only.
| |
Job stream
File definition syntax: schedule [workstation#]jobstreamname # comment [validfrom date] [timezone|tz tzname] [description text] [draft] [freedays calendarname [-sa] [-su]] [on [runcycle name] [validfrom date] [validto date] [description text] {date|day|calendar|request|icalendar} [,...] [fdignore|fdnext|fdprev] [({at time [+n day[s]] | schedtime time [+n day[s]]} [until time [+n day[s]] [onuntil action]] [deadline time [+n day[s]]])]] [,...] [except [runcycle name] [validfrom date] [validto date] [description text] {date|day|calendar|request|icalendar} [,...] [fdignore|fdnext|fdprev] [{(at time [+n day[s]])] | (schedtime time [+n day[s]])}]] [,...] [{at time [timezone|tz tzname] [+n day[s]] | schedtime time [timezone|tz tzname] [+n day[s]]}] [until time [timezone|tz tzname] [+n day[s]] [onuntil action]] [deadline time [timezone|tz tzname] [+n day[s]]] [carryforward] [matching {previous|sameday|relative from [+|] time to [+|] time| from time [+|n day[s]] to time [+n day[s]] [,...]}] [follows {[netagent::][workstation#]jobstreamname[.jobname |@] [previous| sameday|relative from [+|] time to [+|] time| from time [+|n day[s]] to time [+|n day[s]] [,...]]} [keysched] [limit joblimit] [needs [n] [workstation#]resourcename [,...]] [opens [workstation#]filename [(qualifier)] [,...]]
550
Scheduling objects
[priority number | hi | go] [prompt {promptname|[:|!]text}] : job-statement # comment [{at time [timezone|tz tzname] [+n day[s]] | schedtime time [timezone|tz tzname] [+n day[s]]}][,...] [until time [timezone|tz tzname] [+n day[s]] [onuntil action] [deadline time [timezone|tz tzname] [+n day[s]]] [,...] [every rate] [follows {[netagent::][workstation#]jobstreamname{.jobname | @} [previous| sameday|relative from [+|] time to [+|] time | from time [+|n day[s]] to time [+|n day[s]] [,...]]} [confirmed] [keyjob] [needs [n] [workstation#]resourcename [,...]] [opens [workstation#]filename [(qualifier)] [,...]] [priority number | hi | go] [prompt {promptname |[:|!]text}] [job-statement...] end
Parameter
File definition syntax: $parm parametername value
Prompt
File definition syntax: $prompt promptname [: | !]text
Resource
File definition syntax: $resource workstation#resourcename units [description ]
Workstation
File definition syntax: cpuname workstation [description description] os os-type node hostname [tcpaddr port] [secureaddr port][timezone|tz tzname] [domain domainname] [for maestro [host host-workstation [access method]] [type fta | s-agent | x-agent | manager] [ignore] [autolink on | off] [behindfirewall on | off] [securitylevel enabled | on | force] [fullstatus on | off] [server serverid]] end
551
Scheduling objects
Workstation class
File definition syntax: cpuclass workstationclass [description description] [ignore] members [workstation | @] [...] end
User definition
File definition syntax: username[workstation#][domain\]username password passwordend
552
Scheduling objects
Composer commands
This section describes the operations you can perform in the database using the composer command line interface program with syntax:
composer [-file filename][connection_parameters] [-defaultws twscpu] ["command[&[command]][...]"]

[-file filename] [-host hostname] [-port port_name] [-protocol protocol_name] [-proxy proxy_name] [-proxyport proxy_port_number] [-password user_password] [-timeout seconds] [-username user_name]
These operations can only be run from any composer client command line installed. In Table 110 displaying the list of commands that can be used against the scheduling object, filename indicates an existing file when used in the syntax for the add and replace commands, it indicates a not existing file when used in the syntax for the create/extract command.
Table 110. Commands used against scheduling objects in the database
Command add authenticate Syntax a[dd] filename [;unlock] authenticate [username=username password=password] create | extract filename from {[calendars | {calendar | cal}=calname] | [{eventrule | erule | er}=eventrulename]} | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [validfrom date|validto date |validin date date] [full]] | [{users | user}=[workstationame#]username]} ;lock display User Authorization add or modify
| | | | | | | | | | | | | | | |
create extract
553
Scheduling objects
Table 110. Commands used against scheduling objects in the database (continued)
Command Syntax delete {[calendars | {calendar | cal}=calname] | [{eventrule | erule | er}=eventrulename]} | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [validfrom date|validto date |validin date date] [full]] | [{users | user}=[workstationame#]username]} [;noask] display {[calendars | {calendar | cal}=calname] | [{eventrule | erule | er}=eventrulename]} | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [validfrom date|validto date |validin date date] [full]] | [{users | user}=[workstationame#]username]} ;offline list {[calendars | {calendar | cal}=calname] | [{eventrule | erule | er}=eventrulename]} | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [validfrom date| validto date |validin date date]] | [{users | user}=[workstationame#]username]} ;offline lock {[calendars | {calendar | cal}=calname] | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [validfrom date|validto date |validin date date] [full]] | [{users | user}=[workstationame#]username]} User Authorization delete
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
delete
display
display
list
display
lock
modify
554
Scheduling objects
Command modify Syntax modify {[calendars | {calendar | cal}=calname] | [{eventrule | erule | er}=eventrulename]} | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [validfrom date|validto date |validin date date] [full]] | [{users | user}=[workstationame#]username]} composer n[ew] print {[calendars | {calendar | cal}=calname] | [{eventrule | erule | er}=eventrulename]} | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [validfrom date|validto date |validin date date] [full]] | [{users | user}=[workstationame#]username]} ;offline rename {calendars|calendar|cal | eventrule | erule | er | parms|parm | prompts|prom | resorces|resource|res | workstation|ws | workstationclass|wscl | domain|dom | jobs|jobdefinition|jd | jobsched|jb sched|jobstream|js | users|user } old_object_identifier new_object_identifier rep[lace] filename;unlock User Authorization modify or add
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
new print
add or replace display
rename
add or modify
replace
replace or add
555
Scheduling objects
Command Syntax unlock {[calendars | {calendar | cal}=calname] | [{eventrule | erule | er}=eventrulename]} | [parms | [parm=parmname]] | [prompts | [prom=promptname]] | [resources | {resource | res}=resourcename] | [[cpu={workstationame | workstationclassname | domainame}] | [{workstation | ws}=workstationame] | [{workstationclass | wscl}=workstationclassname] | [{domain | dom}=domainame]] | [{jobs | jobdefinition | jd}=[workstationame#]jobname] | [{sched|jobstream|js}= [workstationame#]jstreamname [validfrom date|validto date |validin date date] [full]] | [{users | user}=[workstationame#]username]} [;forced] User Authorization modify and unlock
| | | | | | | | | | | | | | | |
unlock
556
Managing objects in the plan
Managing objects in the plan

This section describes the operations you can perform against the plan using the conman command line interface program with syntax:
conman ["command[&[command]...] [&]"]
Conman commands
This section lists the commands you can run from the conman program. This is how you access to the conman command line:
conman [connection_parameters] ["command[&[command]...] [&]"]

[-file filename] [-host hostname] [-port port_name] [-protocol protocol_name] [-proxy proxy_name] [-proxyport proxy_port_number] [-password user_password] [-timeout seconds] [-username user_name]
This is how you select jobs in commands:

[workstation#] {jobstreamname(hhmm[ date]) job|jobnumber} [{+|~}jobqualifier[...]]
or:
[workstation#] jobstream_id. job [{+|~]jobqualifier[...]] ;schedid
This is how you select job streams in commands:

[workstation#] jobstreamname(hhmm[ date]) [{+|~}jobstreamqualifier[...]]
or:
[workstation#] jobstream_id ;schedid
You can run these commands from different types of workstations. In this table: F S stands for domain managers and fault-tolerant agents. stands for standard agents.
For each command you find the name, the syntax, the type of workstations from where you can issue the command, and the needed authorization, if any.
557
Conman commands
Table 111. Commands that can be run from conman
Command adddep job Syntax adj jobselect[;dependency[;...]][;noask] Workstation types F User Authorization adddep - (use when using prompts and needs) adddep - (use when using prompts and needs) altpass altpri display cancel cancel confirm console
adddep sched
ads jstreamselect[;dependency[;...]][;noask]
altpass altpri
altpass [workstation#]username[;password] ap jobselect | jstreamselect[;pri][;noask] bulk cj jobselect[;pend][;noask] cs jstreamselect[;pend][;noask] confirm jobselect;{succ | abend}[;noask] console [sess | sys][;level=msglevel] conman "continue&command argument&command argument" ddj jobselect;dependency[;...][;noask] dds jstreamselect;dependency[;...][;noask] deployconf [domain!]workstation
F F F F F F F-S F-S F F F,S
bulk_discovery cancel job cancel sched confirm console continue deldep job deldep sched
deldep deldep Permission to start actions on cpu objects display
| | |
deployconf
display
df filename [;offline] dj jobselect [;offline] ds jstreamselect [valid {at date | in date date}[;offline]
F-S1
exit fence help (UNIX only) kill limit cpu limit sched link
e[xit] fence workstation;pri[;noask] help command kill jobselect[;noask] lc workstation;limit[;noask] ls jstreamselect;limit[;noask] lk [domain!]workstation[;noask] listsym [trial | forecast] [;offline] rc [workstation][;offline] redo rj jobselect[;dependency[;...]][;noask] rs jstreamselect[;dependency[;...]][;noask] reply { promptname | [workstation#]msgnum};reply[;noask] rr jobselect[;from=[wkstat#]job[;at=time] [;pri=pri]] [;noask] rr jobselect[;step=step][;noask]
F-S F F-S F F F F-S F F F-S F F F F release release reply rerun display kill limit limit link fence
listsym recall redo release job release sched reply rerun
resource setsym showcpus
resource [workstation#]resource;num[;noask] setsym [trial | forecast] [filenum] sc [[domain!]workstation][;info|;link][;offline]
F F F-S
resource list2
558
Conman commands
Table 111. Commands that can be run from conman (continued)
Command showdomain showfiles Syntax showdomain [domain][;info][;offline] sf [[workstation#]file][;state[;...]][;keys][;offline] sf [[workstation#]file][;state[;...]][;deps[;keys|info |logon]][;offline] showjobs sj [jobselect] [;keys | info | step | logon | keys retcod][;short | single][;offline] [;showid] sj [jobselect] [;deps[;keys | info | logon]][;short | single][;offline] [;showid] sj [jobselect | [workstation#]jobnumber.hhmm] [;stdlist[;keys]][;short | single][;offline] [;showid] showprompts sp [promptselect][;keys][;offline] sp [promptselect] [;deps[;keys | info | logon]][;offline] showresources sr [[workstation#]resourcename][;keys][;offline] sr [[workstation#]resourcename][;deps[;keys|info | logon]][;offline] showschedules ss [jstreamselect][;keys][;offline][;showid] ss [jstreamselect][;deps[;keys | info | logon]][;offline][;showid] shutdown start shut [down] [;wait] start [domain!]workstation[;mgr][;noask][;demgr] startappserver[domain!]workstation [;wait] F-S F-S F-S shutdown start Permission to start actions on cpu objects Permission to start actions on cpu objects Permission to start actions on cpu objects appserver stop stop F-S Permission to stop actions on cpu objects Permission to stop actions on cpu objects Permission to stop actions on cpu objects submit - (use when using prompts and needs) F list2 F list2 F list2 F list2 Workstation types F-S F User Authorization list2
| | | | | | | | |
startappserver
startevtp
starteventprocessor [domain!]workstation
M4
startmon
startmon [domain!]workstation [;noask]
F-S
status stop stop ;progressive
status stop [domain!]workstation[;wait][;noask] stop ;progressive stopappserver[domain!]workstation [;wait]
F-S F-S
| | | | | | | | |
stopappserver
stopevtp
stopeventprocessor [domain!][workstation]
M4
stopmon
stopmon [domain!]workstation [;wait] [;noask]
F-S
submit docommand
sbd [workstation#]cmd[;alias[=name]] [;into=[workstation#]{jobstream_id;schedid | jobstreamname (hhmm[ date])}] [;joboption[;...]]
F-S
559
Conman commands
Table 111. Commands that can be run from conman (continued)
Command submit file Syntax sbf filename[;alias[=name]] [;into=[workstation#]{jobstream_id ;schedid | jobstreamname (hhmm[ date])}] [;joboption[;...]][;noask] submit job sbj [workstation#]jobname[;alias[=name]] [;into=[workstation#]{jobstream_id ;schedid | jobstreamname(hhmm[ date])}] [;joboption[;...]][;noask] submit sched sbs [workstation#]jstreamname[;alias[=name]] [;jstreamoption[;...]][;noask] F-S3 submit - (use when using prompts and needs) Permission to start and stop actions on cpu objects start stop F-S3 submit - (use when using prompts and needs) Workstation types F-S User Authorization submit - (use when using prompts and needs)
switchevtp
switcheventprocessor workstation
M4
switchmgr system tellop unlink version
switchmgr domain;newmgr [: | !] sys-command to [text] unlink [domain!]workstation[;noask] v[ersion]
F F-S F-S F-S F-S
unlink
where: (1) (2) Indicates that you can only display files on a standard agent. You must have list access to the object being shown if the enListSecChk option was set to yes on the master domain manager when the production plan was created or extended. Indicates that you can use submit job (sbj) and submit sched (sbs) on a standard agent by using the connection parameters or specifying the settings in the useropts file when invoking the conman command line. You can use this command on master domain managers and backup masters as well as on workstations installed as backup masters but used as ordinary fault-tolerant agents.
(3)
(4)
560
Utility commands
Utility commands
This section contains the list of the utility commands that you can run from the operating system command prompt. The utility commands are divided into three groups, those you can run on both UNIX and Windows operating systems, those you can run only on UNIX, and those you can run only on Windows. Utility commands available for both UNIX and Windows operating systems
Table 112. Utility commands available for both UNIX and Windows Command at Syntax at -v | -u at -s jstream | -q queue time-spec batch batch -v | -u batch [-s jstream] cpuinfo cpuinfo -v | -u cpuinfo workstation [infotype] [...] datecalc datecalc -V | -U datecalc base-date [offset] [pic format][freedays Calendar_Name [-sa] [-su]] datecalc -t time [base-date] [offset] [pic format] datecalc yyyymmddhhtt [offset] [pic format] delete delete -v | -u delete filename
| | |
evtdef
evtdef -U | -V evtdef [connection parameters] dumpdef file-path evtdef [connection parameters] loaddef file-path
evtsize
evtsize -V | -U evtsize filename size evtsize -show filename
jobinfo
jobinfo -v | -u jobinfo job-option [...]
jobstdl
jobstdl -v | -u jobstdl [-day num] [{-first | -last | -num n | -all}] [-twslog] [{-name ["jobstreamname [(hhmm date),(jobstream_id)].]jobname"|jobnum | -schedid jobstream_id.jobname}] maestro [-v | -u] makecal [-c name] -d n | -e | {-f 1 | 2 | 3 -s date} | -l | -m | -p n | {-r n -s date} | -w n [-i n] [-x | -z][-freedays Calendar_Name [-sa] [-su]]
maestro makecal
metronome.pl morestdl morestdl -v | -u morestdl [-day num] [-first | -last | -num n | -all] [-twslog] [{-name ["jobstreamname [(hhmm date),(jobstream_id)].]jobname"|jobnum | -schedid jobstream_id.jobname}]
561
Utility commands
Table 112. Utility commands available for both UNIX and Windows (continued) Command parms Syntax parms {[-V | -u] | -build} parms {-replace | -extract} filename parms [-d]parameternameparms -c parametername value release -v | -u release [-s] [workstation#]resourcename [count] rmstdlist rmstdlist -v | -u rmstdlist [-p] [age]
release
| | |
sendevent
sendevent -V | ? | -help | -u | -usage sendevent [-hostname hostname][-port port] eventType source [[attribute=value]...]
showexec
showexec [-v | -u | INFO] StartUp [-v | -u]
StartUp
Utility commands available for UNIX operating system only

Table 113. Utility commands available for UNIX only Command at Syntax at -v | -u at -sjstream | -qqueuetime-spec batch batch -v | -u batch [-s jstream] showexec version showexec [-v | -u | -info] version -V | -u | -h version [-a] [-f vfile] [file [...]]
Utility commands available for Windows operating system only

Table 114. Utility commands available for Windows only Command listproc (UNSUPPORTED) killproc (UNSUPPORTED) shutdown shutdown [-v | -u] [-appsrv] killproc pid Syntax listproc
562
Report commands
Report commands
This section contains a list and syntax of report commands and report extract programs. These commands are run from the operating system command prompt. Report commands
Table 115. Report commands Name rep1 rep2 rep3 rep4a rep4b rep7 Output produced Syntax
Reports 01 - Job Details rep[x] [-v|-u] Listing Report 02 - Prompt Listing Report 03 - Calendar Listing rep[x] [-v|-u] rep[x] [-v|-u]
Report 04A - Parameter rep[x] [-v|-u] Listing Report 04B - Resource Listing Report 07 - Job History Listing rep[x] [-v|-u] rep7 -v|-u rep7 [-c wkstat] [-s jstream_name] [-j job] [-f date -t date] [-l] rep8 -v|-u rep8 [-f date -b time -t date -e time] [-i file] [-p ] rep8 [-b time -e time] [-i file] [-p ]
rep8
Report 08 - Job Histogram
rep11
rep11 -v|-u rep11 [-m mm[yy] [...]] [-c wkstat [...]] [-s jstream_name] [-o file] reptr [-v|-u] reptr -pre [-{summary | detail}] [symfile] reptr -post [-{summary | detail}] [logfile]
reptr
Report 09A - Planned Production Summary Report 09B - Planned Production Detail Report 10A - Actual Production Summary Report 10B - Actual Production Detail
xref
xref [-V|-U] xref [-cpu wkstat] [-s jstream_name] [-depends|-files|jobs|-prompts|-resource|-schedules|-when [...]]
563
Report commands
Table 116. Report extract programs Extract Program jbxtract Used to generate Report 01 Report 07 prxtract Report 02 prxtract [-v | -u] [-o file] prxtract [-v | -u] [-m mm[yyyy]] [-c wkstat] [-o file] caxtract paxtract rextract r11xtr xrxtrct Report 03 Report 04A caxtract [-v | -u] [-o file] paxtract [-v | -u] [-o file] Syntax jbxtract [-v | -u] [-j job] [-c wkstat] [-o file]
Report 04B rextract [-v | -u] [-o file] Report 11 Report 12 r11xtr [-v | -u] [-m mm[yyyy]] [-c wkstat] [-o file] [-s jstream_name] xrxtrct [-v | -u]
564
Appendix D. Support information

If you have a problem with your IBM software, you want to resolve it quickly. This section describes the following options for obtaining support for IBM software products: v Using IBM Support Assistant v v v v Searching knowledge bases on page 566 Obtaining fixes on page 567 Receiving weekly support updates on page 567 Contacting IBM Software Support on page 569
Using IBM Support Assistant

The IBM Support Assistant is a free, stand-alone application that you can install on any workstation. You can then enhance the application by installing product-specific plug-in modules for the IBM products you use. The IBM Support Assistant saves you time searching product, support, and educational resources. The IBM Support Assistant helps you gather support information when you need to open a problem management record (PMR), which you can then use to track the problem. The product-specific plug-in modules provide you with the following resources: v Support links v Education links v Ability to submit problem management reports The IBM Support Assistant Web site is at http://www.ibm.com/software/support/ isa/. Use this site for the following: v Obtain general information about the IBM Support Assistant v Download and install the IBM Support Assistant application. Full instructions are provided. v Determine if a plug-in is available for a specific product (or go direct to the plug-ins page at http://www.ibm.com/software/support/isa/plugins.html) To locate and download the plug-in for a product, use the IBM Support Assistant's interface. Full instructions on how to use the application and plugin are provided within the interface. For example, on version 3.0.1 of the IBM Support Assistant, click Updater, click New products and tools, expand Tivoli, select the plug-in, and click Install. If you cannot find the solution to your problem in the IBM Support Assistant, see Searching knowledge bases on page 566.
Tivoli Workload Scheduler IBM Support Assistant plug-in version and upgrade issues
The IBM Tivoli Workload Scheduler plug-in for the IBM Support Assistant has not changed since version 8.3. If you have already installed it in the IBM Support Assistant you need take no further action. If you are planning to install it for the first time with version 8.4 you should be aware that the plug-in name and many
565
Support information
other references in the plug-in have "8.3" as the product version number. This does not mean that it will not work with version 8.4. The plug-in is fully compatible with version 8.4 and performs in exactly the same way as it does in version 8.3.
Searching knowledge bases

You can search the available knowledge bases to determine whether your problem was already encountered and is already documented.
Searching the local information center

IBM provides extensive documentation that you can install on your local computer or on an intranet server. You can use the search function of this information center to query conceptual information, instructions for completing tasks, and reference information. The information center is included on the separate Quick Start CD available as part of the product bundle. Insert the CD in a CD drive on a Windows computer, and the information centre automatically opens.
Searching the Internet

If you cannot find an answer to your question in the information center, search the Internet for the latest, most complete information that might help you resolve your problem. To search multiple Internet resources for your product, use the Web search topic in your information center. In the navigation frame, click Troubleshooting and support Searching knowledge bases and select Web search. From this topic, you can search a variety of resources, including the following: v IBM technotes v IBM downloads v IBM Redbooks v IBM developerWorks v Forums and newsgroups v Google
Search the IBM support Web site

The IBM software support Web site has many publications available online, one or more of which might provide the information you require: 1. Go to the IBM Software Support Web site (http://www.ibm.com/software/ support). 2. Select Tivoli under the Select a brand and/or product heading. 3. Select IBM Tivoli Workload Scheduler under Select a product 4. Click Go. 5. Under the Primary support resources heading and Learn subheading, choose from the list of different types of product support publications: v Information center v Support Technical Exchange v IBM Tivoli software training v Manuals v Redbooks
566
Searching knowledge bases

A search for the selected documentation type is performed, and the results displayed. 6. Use the on-screen navigation to look through the displayed list for the document you require, or use the options in the Search within results for section to narrow the search criteria. You can add Additional search terms or select a specific Document type. You can also change the sort order of the to start the search. results (Sort results by). Then click To access some of the publications you need to register (indicated by a key icon beside the publication title). To register, select the publication you want to look at, and when asked to sign in follow the links to register yourself. There is also a FAQ available on the advantages of registering.
Obtaining fixes
A product fix might be available to resolve your problem. To determine what fixes are available for your IBM software product, follow these steps: 1. Go to the IBM Software Support Web site (http://www.ibm.com/software/ support). 2. Select Tivoli under the Select a brand and/or product heading. 3. Select IBM Tivoli Workload Scheduler under Select a product 4. Click Go. 5. Under the Primary support resources heading and Download, subheading, either choose one of the displayed most-popular downloads, or click View all downloads. A search for the downloads is performed, and the results displayed. 6. Use the on-screen navigation to look through the displayed list for the download you require, or use the options in the Search within results for section to narrow the search criteria. You can add Additional search terms, or select a specific Download type, Platform/Operating system, and Versions, and then click to start the search. 7. Click the name of a fix to read the description of the fix and to optionally download the fix. For more information about the types of fixes that are available, see the IBM Software Support Handbook at http://techsupport.services.ibm.com/guides/ handbook.html.
Receiving weekly support updates

To receive weekly e-mail notifications about fixes and other software support news, follow these steps: 1. Go to the IBM Software Support Web site at http://www.ibm.com/software/ support. 2. Click My support under the Personalized support heading in the upper-right corner of the page. 3. If you have already registered for My support, sign in and skip to the next step. If you have not registered, click register now. Complete the registration form using your e-mail address as your IBM ID and click Submit.
567
Receiving support updates

4. Click Edit profile. 5. In the Products list, select Software. A second list is displayed. 6. In the second list, select a product segment, for example, Systems Management. A third list is displayed. 7. In the third list, select a product sub-segment, for example, Job Scheduling. A list of applicable products is displayed. 8. Select the products for which you want to receive updates, for example, IBM Tivoli Workload Scheduler and IBM Tivoli Management Framework. 9. Click Add products. 10. After selecting all products that are of interest to you, click Subscribe to email on the Edit profile page. 11. In the Documents list, select Software. 12. Select Please send these documents by weekly email from the list. 13. Update your e-mail address as needed. 14. Select the types of documents that you want to receive information about. 15. Click Update. If you experience problems with the My support feature, you can obtain help in one of the following ways: Online Send an e-mail message to erchelp@ca.ibm.com, describing your problem. By phone Call 1-800-IBM-4You (1-800-426-4968).
568
Contacting IBM Software Support

IBM Software Support provides assistance with product defects. Before contacting IBM Software Support, your company must have an active IBM software maintenance contract, and you must be authorized to submit problems to IBM. The type of software maintenance contract that you need depends on the type of product you have: v For IBM distributed software products (including, but not limited to, Tivoli, Lotus, and Rational products, as well as DB2 and WebSphere products that run on Windows, or UNIX operating systems), enroll in Passport Advantage in one of the following ways: Online Go to the Passport Advantage Web site at http://www.lotus.com/ services/passport.nsf/ WebDocs/Passport_Advantage_Home and click How to Enroll. By phone For the phone number to call in your country, go to the IBM Software Support Web site at http://techsupport.services.ibm.com/guides/ contacts.html and click the name of your geographic region. v For customers with Subscription and Support (S & S) contracts, go to the Software Service Request Web site at https://techsupport.services.ibm.com/ssr/ login. v For customers with IBMLink, CATIA, Linux, S/390, iSeries, pSeries, zSeries, and other support agreements, go to the IBM Support Line Web site at http://www.ibm.com/services/us/index.wss/so/its/a1000030/dt006. v For IBM eServer software products (including, but not limited to, DB2 and WebSphere products that run in zSeries, pSeries, and iSeries environments), you can purchase a software maintenance agreement by working directly with an IBM sales representative or an IBM Business Partner. For more information about support for eServer software products, go to the IBM Technical Support Advantage Web site at http://www.ibm.com/servers/eserver/techsupport.html. If you are not sure what type of software maintenance contract you need, call 1-800-IBMSERV (1-800-426-7378) in the United States. From other countries, go to the contacts page of the IBM Software Support Handbook on the Web at http://techsupport.services.ibm.com/guides/contacts.html and click the name of your geographic region for phone numbers of people who provide support for your location. To contact IBM Software support, follow these steps: 1. Determining the business impact on page 570 2. Describing problems and gathering information on page 570 3. Submitting problems on page 570
569
Determining the business impact

When you report a problem to IBM, you are asked to supply a severity level. Therefore, you need to understand and assess the business impact of the problem that you are reporting. Use the following criteria: Severity 1 The problem has a critical business impact. You are unable to use the program, resulting in a critical impact on operations. This condition requires an immediate solution. Severity 2 The problem has a significant business impact. The program is usable, but it is severely limited. Severity 3 The problem has some business impact. The program is usable, but less significant features (not critical to operations) are unavailable. Severity 4 The problem has minimal business impact. The problem causes little impact on operations, or a reasonable circumvention to the problem was implemented.
Describing problems and gathering information

When describing a problem to IBM, be as specific as possible. Include all relevant background information so that IBM Software Support specialists can help you solve the problem efficiently. To save time, know the answers to these questions: v What software versions were you running when the problem occurred? v Do you have logs, traces, and messages that are related to the problem symptoms? IBM Software Support is likely to ask for this information. v Can you re-create the problem? If so, what steps were performed to re-create the problem? v Did you make any changes to the system? For example, did you make changes to the hardware, operating system, networking software, and so on. v Are you currently using a workaround for the problem? If so, be prepared to explain the workaround when you report the problem.
Submitting problems
You can submit your problem to IBM Software Support in one of two ways: Online Click Submit and track problems on the IBM Software Support site athttp://www.ibm.com/software/support/probsub.html. Type your information into the appropriate problem submission form. By phone For the phone number to call in your country, go to the contacts page of the IBM Software Support Handbook at http://techsupport.services.ibm.com/ guides/contacts.html and click the name of your geographic region. If the problem you submit is for a software defect or for missing or inaccurate documentation, IBM Software Support creates an Authorized Program Analysis Report (APAR). The APAR describes the problem in detail. Whenever possible, IBM Software Support provides a workaround that you can implement until the APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the
570

Software Support Web site daily, so that other users who experience the same problem can benefit from the same resolution.
571
572
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 publication in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the users responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this publication. The furnishing of this publication does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS 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 might 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.
573
Notices
IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation 2Z4A/101 11400 Burnet Road Austin, TX 78758 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases payment of a fee. The licensed program described in this publication and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. 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. 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.
Trademarks
IBM, IBMLink, the IBM logo, BookManager, DB2, DB2 Universal Database, developerWorks, eServer, Hiperbatch, i5/OS, iSeries, LoadLeveler, Lotus, NetView, OS/390, Passport Advantage, pSeries, RACF, Rational, Redbooks, S/390, Tivoli, Tivoli Enterprise Console, TME, VTAM, WebSphere, xSeries, z/OS, and zSeries are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. Adobe, and all Adobe-based trademarks are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, other countries, or both. Intel, and Itanium, are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.
574
Notices
Microsoft and Windows are registered trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Other company, product, and service names might be trademarks or service marks of others.
Notices
575
576
Glossary A
access method. An executable file used by extended agents to connect to and control jobs on other operating systems (for example, z/OS) and applications (for example, Oracle Applications, PeopleSoft, and SAP R/3). The access method is specified in the workstation definition for the extended agent. See also "extended agent". actual start time. The time that a Tivoli Workload Scheduler job instance or job stream instance actually starts. See also: v "earliest start time" v latest start time v "planned start time" v "scheduled time" ad hoc job. A job that is inserted into the current production plan. These jobs are unique to the plan, and are not saved in the database. See also: v "database" v "plan" ad hoc prompt dependency. A prompt dependency that is defined within the properties of a job or job stream and is unique to that job or job stream. See also "prompt dependency". agent. An installed component that enables jobs to be run on a computer or a computer partition, provided that the computer or computer partition is also defined as a workstation in the Tivoli Workload Scheduler database. Agents can be standard, fault-tolerant, extended, or network. Specially configured agents are also used as backups for domain managers and the master domain manager. See also: v "backup domain manager" v "backup master domain manager" v "fault-tolerant agent" v "network agent" v "standard agent" v "extended agent" audit. A process that logs modifications to the database and plan. and updates it, resolving dependencies. It is the only process that can update the Symphony file. See also: v "processes" v "production period" v "symphony file" backup domain manager. An agent in a distributed Tivoli Workload Scheduler network that can assume the responsibilities of its domain manager. It is installed as a full status, fault-tolerant agent. See also: v "fault-tolerant agent" v "full status" v "domain manager" backup master domain manager. An agent in a distributed Tivoli Workload Scheduler network that can assume the responsibilities of the master domain manager. It is installed as a full status, fault-tolerant agent. See also: v "fault-tolerant agent" v "full status" v "master domain manager"
C
calendar. A list of scheduling dates. Calendars are defined in the database and are mostly assigned to run cycles. Calendars can be used either to identify the dates when job streams or jobs can be run (when used with inclusive run cycles), or when they cannot be run (when used with exclusive run cycles). A calendar can also be designated for use as a freedays calendar in a job stream. See also: v "exclusive run cycle" v "freedays calendar" v "inclusive run cycle" carry forward. If a job stream is not completed before the end of the current production period it can be carried forward to the next and then to subsequent periods, until the latest start time is reached or the job completes. See also "latest start time". command-line client. A component you use to run selected Tivoli Workload Scheduler master domain manager commands from any workstation where it is installed. It communicates by TCP/IP with the command-line server, which is part of the master domain manager. The command-line client does not need to be installed on the master domain manager, and is a selectable option for installation on other nodes in the network. For details of the supported
B
batchman. A production control process that interacts directly with a copy of the Symphony file distributed to workstations at the beginning of the production period
577
command-line server engine

commands see the Tivoli Workload Scheduler: Planning and Installation Guide. See also "master domain manager". command-line server. See "command line client". conman. A command-line program for monitoring and managing the production environment. See also "processes". composer. A command-line program for managing the definitions of scheduling objects in the database. See also "database". connector. An installed component that provides the interface between the Job Scheduling Console and the engine. See also: v "engine" v "job scheduling console" CPU. See "workstation". cpu time. The processor time used by a job. See also "duration". distributed workstation. A workstation on which jobs and job streams are run using the distributed engine. See also: v "engine" v "workstation" domain. A named group of workstations in a distributed Tivoli Workload Scheduler network, consisting of one or more agents and a domain manager acting as the management hub. All domains have a parent domain except for the master domain. See also: v "domain manager" v master domain manager" domain manager. An installed component in a distributed Tivoli Workload Scheduler network that is the management hub in a domain. All communication to and from the agents in the domain is routed through the domain manager. See also "workstation" duration. The elapsed time that a job is expected to take to complete (estimated duration) and actually takes (actual duration). See also: v "cpu time" v "time restriction" database. Contains definitions for scheduling objects (such as jobs, job streams, resources, and workstations). The database also contains data such as job and job stream statistics, user data, and the last time an object was modified. See also "plan". deadline. The time by which a job or job stream is set to complete. When a job or job stream passes the deadline, notifications are sent to users and integrated applications, but the job or job stream is not prevented from running if all time restrictions and dependencies are satisfied. Jobs or job streams that have not yet started or that are still running after the deadline time has expired are considered late in the plan. See also "plan". dependency. A prerequisite that must be satisfied before a job or job stream can start. See also: v "external dependency" v "file dependency" v "follows dependency" v "prompt dependency" v "resource dependency" distributed network. A connected group of workstations that use the Tivoli Workload Scheduler distributed engine to perform workload scheduling. See also: v "engine" v "workstation"
E
earliest start time. The time before which a job or job stream cannot start. The job or job stream can start after the earliest start time provided that all other time restrictions and dependencies are satisfied. It is set using the at Job Scheduling Console option or in the command-line scheduling language using the at keyword . See also: v actual start time v latest start time v planned start time v "scheduled time" end-to-end network. A network obtained by connecting one or more Tivoli Workload Scheduler fault-tolerant agents in a distributed network to a Tivoli Workload Scheduler for z/OS node in a z/OS network using TCP/IP, to perform workload scheduling. In this configuration, the Tivoli Workload Scheduler for z/OS node becomes the master domain manager of the fault-tolerant agents to schedule and manage jobs in the distributed network. See also: v "engine" v "workstation" engine. The core software for the scheduling environment. The engine can be either a z/OS engine (installed as part of the product "Tivoli Workload Scheduler for z/OS") or a distributed engine (installed as part of the product "Tivoli Workload Scheduler").
578
exclusive run cycle iCalendar

exclusive run cycle. A run cycle that specifies the days and times that a job stream cannot be run. Exclusive run cycles take precedence over inclusive run cycles. See also "run cycle. explorer view. A graphical view in the Job Scheduling Console used to modify and maintain job streams in the database and the plan. See also: v "database" v "plan" v "views" extended agent. An agent used to integrate Tivoli Workload Scheduler job control features with other operating systems (for example, z/OS) and applications (for example, Oracle Applications, PeopleSoft, and SAP R/3). Extended agents must be hosted by a master domain manager, domain manager, or an agent (not another extended agent), and use access methods to communicate with external systems. See also "access method. external dependency. A dependency defined in one job or job stream that refers to another job stream or to a job in another job stream. external job. A job referred to in an external dependency. See also "external dependency. v "plan" freedays calendar. A calendar assigned to a job stream to represent the non-working days when job streams and jobs are not to be run. It can also be used to designate Saturdays or Sundays, or both, as workdays. See also: v calendar" v holidays calendar" FTA. See "fault-tolerant agent" full status. An attribute of an agent that enables it to be updated with the status of jobs and job streams running on all other workstations in its domain and in subordinate domains, but not on peer or parent domains. A backup domain manager or master domain manager must be full status. See also: v backup domain manager" v domain" v master domain manager"
G
global options. Configuration options defined on the master domain manager using optman. These options apply to all workstations in the Tivoli Workload Scheduler network. See also: v local options v optman v user options graph view. A graphical view in the Job Scheduling Console used to modify and maintain job streams in the database and the plan. See also: v "database" v "plan" v "views"
F
fault-tolerant agent. A installed agent component in a distributed Tivoli Workload Scheduler network capable of resolving local dependencies and launching its jobs in the absence of a domain manager. fence. Regulates whether a job can be run on a workstation. The job fence is a priority level that the priority of a job must exceed before it can run. file dependency. A dependency where a job or job stream cannot start until it finds a specific file is present in a specific path on a specific workstation. Sometimes called an opens file dependency. See also "dependency". final job stream. The last job stream that is run in a production period. It contains scripts that generate the next production plan. See also: v "production period v "production plan follows dependency. A dependency where a job or job stream cannot start until other jobs or job streams have completed successfully. See also "dependency". forecast plan. A projection over a selected timeframe based on the job streams and dependencies defined in the database. See also v "database"
H
holidays calendar. The default freedays calendar for all job streams. It is called "holidays". See also: v calendar" v freedays calendar" host. A workstation required by extended agents. It can be any Tivoli Workload Scheduler workstation except another extended agent.
I
iCalendar. A standard (RFC 2445) for calendar data exchange. Specific iCalendars can be supplied in place of Tivoli Workload Scheduler calendars to determine the dates on which jobs or job streams should run. See also "calendar".
Glossary
579
impact view local options

impact view. A graphical view in the Job Scheduling Console used to modify and maintain job stream instance dependencies in the plan. See also: v "plan" v "views" inclusive run cycle. A run cycle that specifies the days and times that a job stream is scheduled to be run. Exclusive run cycles take precedence over inclusive run cycles. See also "run cycle. interactive jobs. A job that runs interactively on a Windows desktop. internal status. The current status of jobs and job streams in the Tivoli Workload Scheduler engine. The internal status is unique to Tivoli Workload Scheduler. See also "status. internetwork dependencies. A dependency between jobs or job streams in separate Tivoli Workload Scheduler networks. See also "network agent. internetwork job or job stream. A job or job stream in a remote Tivoli Workload Scheduler network that is referenced by an internetwork dependency defined for a job or job stream in the local network. See also "network agent. times, priorities, and other dependencies that determine the exact order in which the jobs run. job stream instance. A job stream that is scheduled for a specific run date in the plan. See also "job stream. jobman. A job management process that controls the launching of jobs under the direction of batchman and reports job status back to mailman. The jobman process is responsible for tracking job states and for setting the environment as defined in jobmanrc and .jobmanrc when requesting job launches. See also: v batchman" v jobmon" v mailman" jobmon. A job management and monitoring process in the Windows version of Tivoli Workload Scheduler. A separate jobmon process is spawned to launch and monitor each job. It reports job status back to jobman. See also: v jobman" v processes" JSC. See "job scheduling console".
L
latest start time. The time before which the job or job stream must start. The job or job stream can start before the latest start time provided that all other dependencies are satisfied. It is set in the command-line scheduling language using the until keyword. See also: v actual start time v earliest start time v planned start time v "scheduled time" limit. A means of allocating a specific number of job slots into which Tivoli Workload Scheduler is allowed to launch jobs. A job limit can be set for each job stream, and for each workstation. For example, setting the workstation job limit to 25 permits Tivoli Workload Scheduler to have no more than 25 jobs running concurrently on the workstation. list. A means of filtering plan and database objects and presenting them in a table. local options. Configuration options defined on each workstation in the localopts file. Each workstation in the Tivoli Workload Scheduler network must have a localopts file. The settings in this file are changed using a text editor, and apply only to that workstation. See also: v global options v user options
J
Jnextday. The previously used term for: JnextPlan. Jnextplan. A job that creates or extends the production plan. See also production plan. job. A unit of work that is processed at a workstation. The job definition consists of a unique job name in the database along with other information necessary to run the job. See also "job definition". job definition. A definition of a unit of work that resides in the database of the distributed Tivoli Workload Scheduler engine and can be added to a job stream. Job definitions can be created before creating a job stream, or can be created as part of the creation or modification of a job stream. See also "job stream". job instance. A job scheduled for a specific run date in the plan. See also "job. job scheduling console. A Java graphical user interface used to create, modify, and maintain job scheduling objects, and to manage the production environment. See also "views on page 583". job limit. See "limit" job status. See status. job stream. A list of jobs that run as a unit (such as a weekly backup application), along with run cycles,
580
logman predefined prompt dependency

logman. A command that produces job statistics from the previous production plan log file, and updates the preproduction plan.
O
offset-based run cycle. A run cycle that uses a combination of user-defined periods and offsets. For example, an offset of 3 in a period of 15 days is the third day from the beginning of the period. It is more practical to use offset-based run cycles when the cycle is based on cyclic periods. This term is only used as such in Tivoli Workload Scheduler for z/OS, but the concept applies also to the distributed product. See also: v "rule-based run cycle" v "run cycle" opens file dependency. See file dependency. optman. A command-line program that maintains the global options in the product database.
M
makesec. A command-line utility that compiles the security file. See also "security file". mailman. A mail management process. It routes messages to local and remote workstations. Additional mailman processes named ServerIDs are created on domain managers to divide the load on mailman and improve the efficiency of message handling. When the domain manager starts up, it creates a separate mailman process instance for each ServerID specified in the workstation definitions of the agents it manages. Each workstation then contacts its own ServerID on the domain manager instead of contacting the main mailman process. See also "processes". master domain manager. An installed component that performs the role of management hub of the top-level domain in the Tivoli Workload Scheduler network. It maintains the database of all scheduling objects in the domain and the central configuration files. The master domain manager generates the plan and creates and distributes the Symphony file. In addition, logs and reports for the network are maintained on the master domain manager. See also: v backup master domain manager v database v domain v plan MDM. See master domain manager". metronome. An application that takes a snapshot of the Tivoli Workload Scheduler configuration and generates an HTML report. It is used in problem determination to provide information to IBM Software Support. mozart. The previously used term for the "database".
P
parameter. An entity that enables job instance-specific values to be substituted in job and job stream scripts, either from values in the database or at run time. Parameters cannot be used when scripting extended agent jobs. plan. The means of scheduling jobs. Objects in the database become instances in the plan. See also: v "database" v final job stream v "forecast plan" v JnextPlan v "planman" v "preproduction plan" v "production plan" v "trial plan" planman. An application you use to create, extend, and reset plans of all types. See also "plan". planned start time. The time that Tivoli Workload Scheduler estimates a job instance will start. This estimate is based on start times of previous instances of the job. See also: v actual start time v earliest start time v latest start time v "scheduled time" predecessor. A job or job stream that must complete successfully before successor jobs or job streams can be started. See also "successor. predefined prompt dependency. A prompt dependency that is defined in the database and can be associated to any job or job stream. See also "prompt dependency.
Glossary
N
netman. A network management process that is started by the Startup script in UNIX, or as a service in Windows. Netman behaves like a network listener program which receives conman start, stop, link or unlink requests from the network. The netman process examines each request received and either implements the request itself or spawns a local Tivoli Workload Scheduler process to do so. See also "processes". network agent. A logical extended agent used to create dependencies between jobs and job streams on separate Tivoli Workload Scheduler networks. See also "internetwork dependencies.
581
priority Symphony file

priority. A way of determining the order in which jobs and job streams start. Priorities for each job and job stream range from 0 to 101. A job or job stream with a priority of 0 does not run. preproduction plan. A high-level plan of system activity containing job streams and dependencies. It is created automatically when the production plan is created for the first time. It is extended if the production plan is extended. It is similar to the long-term plan used in Tivoli Workload Scheduler for z/OS. See also "plan". production period. The time frame covered by the production plan. See also "production plan". production plan. Contains all job scheduling activity planned for a period. The plan is created or extended by the Jnextplan job or by planman. It is stored in the Symphony file, and consists of all the jobs, job streams, and dependency objects that are scheduled to run for that period, including any jobs or job streams carried forward from the previous plan. See also: v "carry forward" v "JnextPlan" v "plan" processes. Network processes that control the production environment and network traffic. See also: v "batchman" v "jobman" v "jobmon" v "mailman" v "netman" v "writer" prompt dependency. A dependency where an operator must respond affirmatively to a prompt so that the dependent job or job stream can run. See also: v "ad hoc prompt dependency" v "predefined prompt dependency" Tivoli Workload Scheduler for z/OS, run cycles can also be based on periods that you define, such as a semester. This term is only used as such in Tivoli Workload Scheduler for z/OS, but the concept applies also to the distributed product. See also: v "offset-based run cycle" v "run cycle" run cycle. Specifies the days that a job stream is scheduled to run. See also: v "calendar" v "exclusive run cycle" v "iCalendar" v "inclusive run cycle" v "rule-based run cycle" v "simple run cycle" v "weekly run cycle"
S
schedule. See job stream. scheduled time. The time when a job or job stream is scheduled to run. See also: v actual start time v earliest start time v latest start time v "planned start time" security file. The file where access rights of users to objects in the database and the plan are defined. It is created by makesec. See also "makesec". simple run cycle. A specific set of user-defined days a job stream is run. A simple run cycle is defined for a specific job stream and cannot be used by other job streams. See also "run cycle. standard agent. An installed agent component in a distributed Tivoli Workload Scheduler network that runs jobs, but requires a domain manager to resolve local dependencies and launch the jobs. status. The current job or job stream status within the Job Scheduling Console. The Job Scheduling Console status is common to Tivoli Workload Scheduler and Tivoli Workload Scheduler for z/OS. See also "internal status. successor. A job that cannot start until all of the predecessor jobs or job streams on which it is dependent are completed successfully. See also: "predecessor. Symphony file. A file containing the scheduling information needed by the production control process (batchman) to run the plan. The file is built and loaded when the production plan is created or extended on the
R
resource. Either physical or logical system resources. Resources are used as dependencies for jobs and job streams. See also "resource dependency. resource dependency. A dependency where a job or job stream cannot start until the required quantity of the defined resource is available. See also "resource. rule-based run cycle. A run cycle that uses rules based on lists of ordinal numbers, types of days, and common calendar intervals (or period names in Tivoli Workload Scheduler for z/OS). For example, the last Thursday of every month. Rule-based run cycles are based on conventional periods, such as calendar months, weeks of the year, and days of the week. In
582
table view z/OS network

master domain manager. During the production phase, it is continually updated to indicate the current status of production processing: work completed, work in progress, and work to be done. To manage production processing, the contents of the Symphony file (plan) can be displayed and altered using conman or the Job Scheduling Console. See also: v batchman" v conman" v "job scheduling console" v "plan"
V
views. Elements of the graphical user interface of the Job Scheduling Console used for viewing and modifying scheduling objects. See also: v "explorer view" v "graph view" v "impact view" v "table view" v "timeline view"
T
table view. A graphical view in the Job Scheduling Console used to display database and plan object data in tabular format. See also: v "database" v "job scheduling console" v "plan" v "views" timeline view. A graphical view in the Job Scheduling Console used to modify and maintain job stream instance time restrictions. See also: v "job scheduling console" v "time restriction" v "views" time restriction. Determines the times before which, after which, or both, that a job or job stream cannot be run. Specifying both defines a time frame within which a job or job stream runs. Jobs can also have a repetition rate. For example, Tivoli Workload Scheduler can launch the same job every 30 minutes between the hours of 8:30 a.m. and 1:30 p.m. trial plan. A projection of the current production plan for a different period, using the same start date. It is used to determine the effect of different plan decisions. See also "plan".
W
weekly run cycle. A run cycle that specifies the days of the week that a job stream is run. For example, a job stream can be specified to run every Monday, Wednesday, and Friday using a weekly run cycle. A weekly run cycle is defined for a specific job stream and cannot be used by multiple job streams. See also "run cycle. workstation. A definition of an individual computer or computer partition on which jobs and job streams are run. Types of workstation vary depending on the type of engine. See also: v "distributed workstation" v z/OS workstation" workstation class. A workstation class is a group of workstations with similar job-scheduling characteristics. Any number of workstations can be placed in a class. Job streams and jobs can be assigned to run on a workstation class. This makes replication of a job or job stream across many workstations easy. See also "workstation" writer. A process started by netman. The writer process passes incoming messages to the local mailman process. The writer processes (there may be more than one on a domain manager workstation) are started by link requests and are stopped by unlink requests or when the communicating mailman process ends. See also "processes".
U
user options. Configuration options defined for each user on a workstation, in a useropts file for each user on a workstation. The settings in this file apply only to that user on that workstation. See also: v local options v global options utility commands. A set of utilities invoked from the operating system's command line for managing Tivoli Workload Scheduler.
X
x-agent. See extended agent.
Z
z/OS network. A connected group of workstations that use the Tivoli Workload Scheduler z/OS engine to perform workload scheduling. See also: v "engine" v "workstation"
Glossary
583
z/OS workstation
z/OS workstation. A representation of system configuration elements in the Tivoli Workload Scheduler for z/OS network. For the z/OS engine, workstations can be: v Computer v General v Printer See also "workstation".
584
Index Special characters

.jobmanrc configuration script 27
C
calendar run cycle 161 calendar definition 127 cancel command 274 cancel sched command 276 carryforward customizing 61 job stream keywords 61 stageman 61 variable 83 carryforward keyword 139 carryStates variable 61, 65 caxtract command 444 centralized security 32 closest preceding follows 150 follows previous 59 matching criteria 59 command stageman 82, 85 command line composer 6 conman 6 optman 6 command line interface setting 29 commands adddep job 267 adddep sched 269 altpass 271 altpri 272 at 375 batch 375 bulk_discovery 273 cancel job 274 cancel sched 276 caxtract 444 confirm 278 console 279 continue 280 cpuinfo 378 datecalc 380 deldep job 281 deldep sched 283 delete 384 deployconf 285 display 286 dumpsec 34 evtdef 385 evtsize 388 exit 289 fence 290 getmon 312 help 291 jbxtract 441 jobinfo 390 jobstdl 392 kill 292 limit cpu 293
Numerics
5601-453, program number 5601-454, program number 5765-086, program number xxii xxii xxii
A
abend job state 255 job stream state 262 abenp job state 255 access extended and network agents 111 workstation definition 111 accessibility xxiii disability xxiii keyboard xxiii add job state 256 job stream state 262 add command 203 adddep job command 267 adddep sched command 269 altpass command 271 altpri command 272 architecture 11 at command 375 ATSCRIPT variable 375 at keyword 134, 138 auditing body format 484 enabling 483 feature 483 header format 484 log format 484 overview 483 sample log file 487 authenticate command 205 autolink workstation definition 111 automating plan processing final job stream 87 automating processing production plan 87 autostart monman 354
B
batch command 375 batchman process 12 behindfirewall workstation definition 111 BookManager xxii bulk_discovery command 273 Copyright IBM Corp. 1999, 2007
585
commands (continued) limit sched 294 link 295 listsym 297 maestro 394 makecal 395 makesec 35 metronome.pl 397 morestdl 398 parms 400 paxtract 445 prxtract 443 r11xtr 447 recall 299 redo 300 release 403 release job 302 release sched 304 rep1 416 rep11 421 rep2 416 rep3 416 rep4a 416 rep4b1 416 rep7 417 rep8 419 reply 306 reptr 422 rerun 307 resource 310 rextract 446 rmstdlist 404 sendevent 405 setsym 311 showcpus 312 showdomain 317 showexec 407 showfiles 319 showjobs 321 showprompts 332 showresources 335 showschedules 337 shutdown 341 start 342 startappserver 345 starteventprocessor 346 startmon 347 StartUp 409 status 348 stop 349 stop ;progressive 351 stopappserver 352 stopeventprocessor 353 stopmon 354 submit docommand 355 submit file 358 submit job 361 submit sched 363 switcheventprocessor 366 switchmgr 367 tellop 369 unlink 370 version 372, 410 xref 424 xrxtrct 449 comment keyword 140
composer command line 6 composer program 190 connection parameters 191 control characters 194 delimiters 196 editor 191 filters 194 list of commands 197 offline output 190 prompt 191 running commands 191 setup 190 variables 413 variables on UNIX 190 variables on Windows 190 special characters 196 terminal output 190 wild cards 194 XML editor 191 composer reference 105 COMPUTERNAME variable 22 configuration scripts .jobmanrc 27 jobmanrc 25 configuring local properties 21 confirm command 278 confirmed keyword 141 conman command line 6 conman program 243 control characters 246 delimiters 248 list of commands 264 offline output 244 processing 249 prompt 244 running commands 245, 247 selecting job 249 arguments 249 jobstream_ID 250 jobstreamname 249 schedid 250 using at 251 using confirm 251 using deadline 251 using every 252 using finished 252 using follows 253 using logon 253 using needs 254 using opens 254 using priority 254 using prompt 254 using recovery 255 using scriptname 255 using started 255 using state 255 using until 256 selecting job streams 257 arguments 257 jobstream_id 258 jobstreamname 257 schedid 258 using at 258 using carriedforward 259
586
conman program (continued) selecting job streams (continued) using carryforward 259 using finished 259 using follows 259 using limit 260 using needs 260 using opens 261 using priority 261 using prompt 261 using started 262 using state 262 using until 263 setup 243 set variables 244 special characters 248 terminal output 244 user prompting 247 wildcards 248 conman reference 243 conman startappserver JnextPlan 70 connection parameters setting 29 console command 279 continue command 206, 280 conventions, typeface xxiv Courier.msg 17 cpuclass workstation class definition 115 cpuinfo command 378 cpuname workstation definition 109 create command 207 CreatePostReports JnextPlan 71 creating forecast planman command line 78 creating trial planman command line 76 custom events defining 103, 385 sending 103, 405 customer support See Software Support
D
database objects add command 203 authenticate command 205 calendars 127 continue command 206 create command 207 delete command 210 display command 213 displaying composer banner domains 117 edit command 217 event rules 178 exit command 218 extract command 207 help command 219 job stream 133 jobs 119 list command 220 lock command 224
242
database objects (continued) modify command 227 new command 231 parameters 128 print command 220 prompts 130 redo command 232 rename command 234 replace command 236 resources 132 unlock command 238 validate command 241 windows users 125 workstation classes 115 workstations 108 date run cycle 161 datecalc command 380 day run cycle 161 deadline keyword 142 defining database objects calendars 127 domains 117 event rules 178 job stream 133 jobs 119 parameters 128 prompts 130 resources 132 windows users 125 workstation classes 115 workstations 108 dependencies follows 150 needs 160 opens 167 prompts 170 Defining objects in the database 105 deldep job command 281 deldep sched command 283 delete command 210, 384 dependencies orphaned 61 dependency internetwork 499, 504 deployconf command 285 Deploying rules planman command line 79 description keyword 143 directory names, notation xxiv disability accessibility xxiii display command 213, 286 docommand job definition 120 domain workstation definition 110 domain definition 117 ismaster 117 manager 117 parent 117 done job state 256 draft keyword 144 Index
587
dumpsec command
34
E
edit command 217 education xxiii, 565 enabling SSL communication 112 time zone 461 enCarryForward variable 61, 65 enCFInterNetworkDeps variable 65 enCFResourceQuantity variable 66 end keyword 145 enLegacyId variable 66 enLegacyStartOfDayEvaluation variable 68, 462 enPreventStart variable 66 enTimeZone variable 68, 461 environment variables, notation xxiv error job state 256 event rule definition 178 eventRules.xsd 178 keywords actionProvider 183 actionType 184 activeTime 180 correlationAttributes 183 daylight saving time 180 description 180, 184 eventCondition 181 eventProvider 181 eventRule 179 eventType 181 filteringPredicate 182 isDraft 180 name 179 onDetection 184 onTimeOut 184 operator 183 responseType 184 ruleType 179 scope 182, 184 timeInterval 181 timeZone 180 validity 180 event rules instances 103 sample scenarios 90, 97 timeout option 96 variable substitution 97 every keyword 146 evtdef command 385 evtsize command 388 except keyword 148 exec job state 256 job stream state 262 exec+ job state 256 exit command 218, 289
extended agent access method 490 option file 493 response messages 492 running 494 syntax 490 troubleshooting 496 definition 490 overview 489 reference 489 workstation definition 111 EXTERNAL job stream 504 jobs 505 extract command 207 extrn job state 256
F
fail job state 256 fdignore except 148 on 164 fdnext except 148 on 164 fdprev except 148 on 164 fence job state 256 fence command 290 files at.allow 376 at.deny 376 Courier.msg 17 Intercom.msg 17 Mailbox.msg 17 NetReq.msg 17 filters composer 194 final job stream automating plan processing 87 fix packs obtaining 567 fixes See fix packs FNCJSI preproduction plan 57 follows matching criteria 150 follows absolute to matching criteria 59 within an absolute interval 59 follows keyword 150 follows previous closest preceding 59 matching criteria 59 follows relative to matching criteria 59 within a relative interval 59 follows sameday matching criteria 59 same day 59
588
forecast plan creating 78 description 64 freedays keyword 152 fta workstation definition 111 fullstatus workstation definition 112
G
global option database audit variable 483 plan audit variable 483 global options carryforward variable 83 carryStates 61 carryStates variable 65 enCarryForward variable 61, 65 enCFInterNetworkDeps variable 65 enCFResourceQuantity variable 66 enLegacyId variable 66 enLegacyStartOfDayEvaluation variable 68, 462 enPreventStart variable 66 enTimeZone variable 68, 461 logmanMinMaxPolicy variable 67 logmanSmoothPolicy variable 67 maxLen variable 65 minLen variable 65 startOfDay variable 65, 462 global parameter definition 128 glossary See terminology
Integration with IBM Tivoli Monitoring 6.1 bulk_discovery 273 interactive job definition 120 Intercom.msg 17 intermediate plan extending with 75 generating 73 Internet, searching for problem resolution 566 internetwork dependency creating 503 managing using conman 504 intro job state 256 intro+ job state 256 ismaster domain definition 117
J
jbxtract command 441 JnextPlan conman startappserver 70 CreatePostReports 71 MakePlan 70 SwitchPlan 71 UpdateStats 71 job definition 119 docommand 120 interactive 120 recovery option 122 scriptname 119 streamlogon 120 success condition 120 tasktype 120 using parameters 123 job statement in job streams 154 job states abend 255 abenp 255 add 256 done 256 error 256 exec 256 exec+ 256 extrn 256 fail 256 fence 256 hold 256 intro 256 intro+ 256 pend 256 ready 256 sched 256 succ 256 succp 256 wait 256 job stream EXTERNAL 504 job stream definition 133 job stream keywords at 138 carryforward 61, 139 comment 140 confirmed 141 Index
H
help command 219, 291 hold job state 256 job stream state 262 HOME variable 23 HOMEDRIVE variable 22 HOMEPATH variable 22 host extended agents 110 workstation definition 110
I
IBM Redbooks 565 IBM support assistant 565 icalendar run cycle 162 identifying job stream instances in the plan 58 at 58 scheddateandtime 58 preproduction plan 58 ignore workstation class definition 115 information centers at IBM support Web site, searching for problem resolution 566 local, searching for problem resolution 566
589
job stream keywords (continued) deadline 142 description 143 draft 144 end 145 every 146 except 148 follows 150 freedays 152 job statement 154 keyjob 156 keysched 157 limit 158 matching 159 needs 160 on 161 opens 167 priority 169 prompt 170 schedtime 171 schedule 173 until 175 validfrom 177 job stream states abend 262 add 262 exec 262 hold 262 ready 262 stuck 262 succ 262 job streams keywords at 134 onuntil 175 jobinfo command 390 jobman environment variables 22 jobman process 13 limit cpu 13 jobmanrc configuration script 25 jobstdl command 392, 398
keywords (continued) opens 167 priority 169 prompt 170 schedtime 171 schedule 173 until 175 validfrom 177 kill command 292 knowledge bases, searching for problem resolution 566
L
LANG variable 22, 23 late status 142 LD_LIBRARY_PATH variable 23 LD_RUN_PATH variable 23 library xv limit cpu jobman process 13 limit cpu command 293 limit keyword 158 limit sched command 294 link command 295 list command 220 listsym command 297 local option mm retry link variable 87 local parameter database 400 definition 128 exporting 400 importing 400 managing 400 local properties 21 local security 32 LOCAL_RC_OK variable 25 lock command 224 logmanMinMaxPolicy variable 67 logmanSmoothPolicy variable 67 LOGNAME variable 22, 23 long term plan preproduction plan 57 LookAt message retrieval tool xxii
K
keyboard accessibility xxiii keyjob keyword 156 keysched keyword 157 keywords at 134, 138 carryforward 139 comment 140 confirmed 141 deadline 142 description 143 draft 144 end 145 every 146 except 148 follows 150 freedays 152 keyjob 156 keysched 157 limit 158 matching 159 needs 160 on 161
M
maestro command 394 MAESTRO_OUTPUT_STYLE variable 22, 23 MAIL_ON_ABEND variable 26 mailbox files Courier.msg 17 Intercom.msg 17 Mailbox.msg 17 NetReq.msg 17 setting size 388 Mailbox.msg 17 mailman process 12 ServerID 12 makecal command 395 MakePlan JnextPlan 70 makesec command 35
590
manager workstation definition 111 managing external follows dependencies 59 matching criteria 59 objects in the database 105 production cycle 55 managing events starting the event processing server 346 starting the monitoring engine 347 stopping the event processing server 353 stopping the monitoring engine 354 switching the event processing server 366 managing objects in plan 243 in the database 189 managing plan adding dependency to job streams 269 adding dependency to jobs 267 altering priority 272 altering user password 271 assigning console 279 cancelling job streams 276 cancelling jobs 274 confirming job completion 278 deleting dependency to job streams 283 deleting dependency to jobs 281 displaying conman banner 372 displaying help information 291 displaying jobs or job streams 286 displaying production plan status 348 displaying workstation information 312 exiting conman 289 get active monitors 312 ignoring command 280 limiting jobs running in job stream 294 linking workstations 295 listing processed plans 297 listing unresolved prompts 299 modifying job fence 290 modifying jobs running on workstation 293 modifying resource units 310 releasing job streams from dependency 304 releasing jobs from dependency 302 replying to prompts 306 requesting a bulk_discovery 273 rerunning commands 300 rerunning jobs 307 selecting processed plan 311 sending messages to operator 369 setting message level 279 showing domain information 317 showing file dependencies 319 showing job information 321 showing job streams information 337 showing prompts information 332 showing resource information 335 shutting down workstation processes 341 starting the application server 345 starting workstation processes 342 stopping behindfirewall workstation processes 351 stopping jobs 292 stopping the application server 352 stopping workstation processes 349 submitting commands as jobs 355 submitting file as jobs 358 submitting job streams 363
managing plan (continued) submitting jobs 361 switching domain management 367 unlinking workstations 370 updating the monitoring configuration file 285 managing time zone 461 time zone name with variable length 461, 466 time zone table all supported 466 backward compatibility 465 matching criteria closest preceding 59, 159 follows 150 follows absolute to 59 follows previous 59 follows relative to 59 follows sameday 59 pending predecessor 60 predecessor 60 same day 59, 159 successor 60 within a relative interval 59, 159 within an absolute interval 59, 159 matching keyword 159 maxLen variable 65 members workstation class definition 115 message retrieval tool, LookAt xxii metronome.pl command 397 minLen variable 65 modify command 227 monman process 12
N
needs keyword 160 netman process 12 netmth access method 501 NetReq.msg 17 network agent access method options file 501 access method netmth 501 definition 501 EXTERNAL 504 EXTERNAL state ERROR 504 EXTRN 504 internetwork dependency 499 creating 503 managing using conman 504 overview 499 reference 499 sample scenario 502 network communication 18 job processing 18 start of day 18 new command 231 node workstation definition 110 notation environment variables xxiv path names xxiv typeface xxiv Index
591
O
on run cycle 161 on keyword 161 run cycle 161 online publications accessing xxi onuntil keyword 175 opens keyword 167 optman command line 6 ordering publications xxii orphaned dependencies 61 os type workstation definition 110
P
parameter in job definitions 123 parameter definition 128 parent domain definition 117 parms command 400 path names, notation xxiv PATH variable 23 paxtract command 445 pend job state 256 pending predecessor matching criteria 60 orphaned dependencies 61 successor 60 plan quick start 8 plan management basic concepts 55 customizing 61, 65 stageman 82, 85 planman command line connection parameters 72 creating forecast 78 creating trial 76 Deploying rules 79 intermediate plan 73, 75 resetting plan 81 retrieving plan info 75 trial extension 78 unlocking plan 80 predecessor matching criteria 60 successor 57, 60 preproduction plan description 57 FNCJSI 57 long term plan 57 print command 220 priority keyword 169 problem determination describing problems 570 determining business impact 570 submitting problems 570 problem resolution 565 processes batchman 12
processes (continued) jobman 13 mailman 12 monman 12 netman 12 ssmagent 12 writer 12 product library xv production cycle 55 identifying job stream instances 58 managing 55 planman command line 72 production plan automating processing 87 description 61 generating 69 JnextPlan 55, 69 resetting plan 81 retrieving info 75 starting processing 87 Symphony file 55, 69 unlocking plan 80 program numbers 5601-453 xxii 5601-454 xxii 5765-086 xxii prompt definition 130 prompt keyword 170 prxtract command 443 publications accessing online xxi library xv online xxii ordering xxii
R
r11xtract command 447 ready job state 256 job stream state 262 recall command 299 recovery job definition 122 Redbooks, IBM 565 redo command 232, 300 referential integrity check 198 release command 403 release job command 302, 306 release sched command 304 rename command 234 rep1 command 416 rep11 command 421 rep2 command 416 rep3 command 416 rep4a command 416 rep4b command 416 rep7 command 417 rep8 command 419 replace command 236 report commands 413 Actual Production Detail sample output 435 Actual Production Details 422 Actual Production Summary 422 Calendar Listing 416
592
report commands (continued) sample output 429 changing date format 414 Cross Reference 424 sample output 438 extract programs 440 caxtract 444 jbxtract 441 paxtract 445 prxtract 443 r11xtr 447 rextract 446 xrxtract 449 Job Details Listing 416 sample output 425 Job Histogram 419 sample output 433 Job History Listing sample output 432 Parameter Listing sample output 430 Parameters Listing 416 Planned Production Detail sample output 434 Planned Production Details 422 Planned Production Schedule 421 sample output 436 Planned Production Summary 422 Prompt Listing 416 sample output 428 Resource Listing 416 sample output 431 sample outputs 425 setup 413 reports commands Job History Listing 417 list of commands 414 reptr command 422 rerun command 307 reserved words for job streams 106 for user definitions 107 for workstations 106 resetting plan planman command line 81 resource command 310 resource definition 132 rextract command 446 rmstdlist command 404 rrcondsucc job definition 120 run cycle calendar 161 date 161 day 161 icalendar 162 on 161 running system commands from composer 237 from conman 247, 368
S
same day follows 150 follows sameday 59 matching criteria 59
sched job state 256 schedtime keyword 171 schedule keyword 173 scheduling language 133 scriptname job definition 119 secureaddr workstation definition 110 security centralized 32 local 32 overview 31 specifying accesses 43 specifying objects 40 specifying users 38 template file 36 security file, template 36 securitylevel 112 workstation definition 112 sendevent command 405 ServerID mailman process 12 workstation definition 113 setsym command 311 setting connection parameters 29 SHELL_TYPE variable 26 showcpus command 312 showdomain command 317 showexec command 407 showfiles command 319 showjobs command 321 showprompts command 332 showresources command 335 showschedules command 337 shutdown utility command 408 shutdown command 341 softcopy books xxii software support 565 Software Support contacting 569 describing problems 570 determining business impact 570 receiving weekly updates 567 submitting problems 570 SSL communication enabling 112 stageman carryforward 61 SwitchPlan 82 standard agent workstation definition 111 start command 342 start of day establishing communication 19 startappserver command 345 starteventprocessor command 346 starting WebSphere Application Server 16 workstation processes 16 starting processing production plan 87 startmon command 347 startOfDay variable 65, 462 Index
593
StartUp command 409 status late 142 status command 348 stop command 349 stop; progressive command 351 stopappserver command 352 stopeventprocessor command 353 stopmon command 354 stopping WebSphere Application Server 16 workstation processes 16 streamlogon job definition 120 windows user definition 125 stuck job stream state 262 submit docommand command 355 submit file command 358 submit job command 361 submit sched command 363 succ job state 256 job stream state 262 successor matching criteria 60 pending predecessor 60 predecessor 57, 60 succp job state 256 support 565 support assistant 565 support Web site, searching to find software problem resolution 566 switcheventprocessor command 366 switchmgr command 367 SwitchPlan JnextPlan 71 Symphony file JnextPlan 69 production plan 61, 69 SystemDrive variable 22 SystemRoot variable 22
Tivoli Workload Scheduler (continued) managing production 5 network 1 overview 1 processes 11 quick start 8 running event management 6 runtime environment 2 user interfaces 6, 7 TIVOLI_JOB_DATE variable 22, 23 TMPDIR variable 22 TMPTEMP variable 22 training technical xxiii trial extension planman command line 78 trial plan creating 76 description 63 extension 78 trialsked forecast plan 64 trial plan 63 TWS_TISDIR variable 23 type workstation definition 111 typeface conventions xxiv TZ variable 22, 23
U
UNISON_CPU variable 22, 23 UNISON_DATE variable 22 UNISON_DATE_FORMAT variable 24 UNISON_DIR variable 22, 23 UNISON_EXEC_PATH variable 22, 23 UNISON_EXIT variable 25 UNISON_HOST variable 22, 23 UNISON_JCL variable 25 UNISON_JOB variable 22, 24 UNISON_JOBNUM variable 22, 24 UNISON_MASTER variable 22, 24 UNISON_RUN variable 22, 24 UNISON_SCHED variable 22, 24 UNISON_SCHED_DATE variable 24 UNISON_SCHED_EPOCH variable 23, 24 UNISON_SCHED_IA variable 23 UNISON_SCHED_ID variable 23 UNISON_SHELL variable 23, 24 UNISON_STDLIST variable 23, 24, 25 UNISON_SYM variable 23, 24 UNISONHOME variable 22, 23 UNIXTASK 120 UNKNOWN 120 unlink command 370 unlock command 238 unlocking plan planman command line 80 until keyword 175 UpdateStats JnextPlan 71 USE_EXEC variable 26 user definition 125 trusted domain 126 user interfaces composer 7 conman 7
T
tasktype job definition 120 tcpaddr workstation definition 110 technical training xxiii tellop command 369 TEMP variable 22 terminology accessing Web site xx time zone enabling 461 timezone workstation definition 110 Tivoli Software Glossary xx Tivoli software information center xxi Tivoli technical training xxiii Tivoli Workload Scheduler architecture 11 basic concepts 1 controlling job processing 4 defining activities 2
594
user interfaces (continued) Dynamic Workload Console 7 Java API 7 Job Scheduling Console 7 optman 7 planman 8 Web Services Interface 8 user security commands dumpsec 34 makesec 35 local security 32 security file access capabilities 43 modifying 33 object qualification 43 sample 51 syntax 36 user qualification 39 variables 41 wildcards 37 security files 33 setting 29 USERDOMAIN variable 23 USERNAME variable 23 USERPROFILE variable 23 utility commands 373 at 375 at.allow file 376 at.deny file 376 ATSCRIPT variable 375 batch 375 changing date format 380 creating calendars 395 defining custom events 385 deleting files 384 displaying content of standard list files 398 displaying product version 410 displaying running jobs 407 displaying standard list files 404 getting HTML reports 397 getting job information 390 getting TWS_home path 394 getting workstation information 378 list of commands 373 listing standard list files 392 managing parameters locally 400 releasing resource units 403 removing standard list files 404 sending custom events 405 setting mailbox file size 388 shutdown 408 starting up netman 409
V
validate command 241 validfrom keyword 177 variables ATSCRIPT 375 carryforward 83 carryStates 61, 65 COMPUTERNAME 22 enCarryForward 61, 65 enCFInterNetworkDeps 65 enCFResourceQuantity 66 enLegacyId 66
variables (continued) enLegacyStartOfDayEvaluation 68, 462 enPreventStart 66 enTimeZone 68, 461 exported locally by .jobmanrc 25, 27 exported on UNIX 23 HOME 23 HOMEDRIVE 22 HOMEPATH 22 LANG 22, 23 LD_LIBRARY_PATH 23 LD_RUN_PATH 23 local variables 23, 25, 27, 190, 244 LOCAL_RC_OK 25 logmanMinMaxPolicy 67 logmanSmoothPolicy 67 LOGNAME 22, 23 MAESTRO_OUTPUT_STYLE 22, 23 MAIL_ON_ABEND 26 maxLen 65 minLen 65 PATH 23 SHELL_TYPE 26 startOfDay 65, 462 SystemDrive 22 SystemRoot 22 TEMP 22 TIVOLI_JOB_DATE 22, 23 TMPDIR 22 TMPTEMP 22 TWS_TISDIR 23 TZ 22, 23 UNISON_CPU 22, 23 UNISON_DATE 22 UNISON_DATE_FORMAT 24 UNISON_DIR 22, 23 UNISON_EXEC_PATH 22, 23 UNISON_EXIT 25 UNISON_HOST 22, 23 UNISON_JCL 25 UNISON_JOB 22, 24 UNISON_JOBNUM 22, 24 UNISON_MASTER 22, 24 UNISON_RUN 22, 24 UNISON_SCHED 22, 24 UNISON_SCHED_DATE 24 UNISON_SCHED_EPOCH 23, 24 UNISON_SCHED_IA 23 UNISON_SCHED_ID 23 UNISON_SHELL 23, 24 UNISON_STDLIST 23, 24, 25 UNISON_SYM 23, 24 UNISONHOME 22, 23 USE_EXEC 26 USERDOMAIN 23 USERNAME 23 USERPROFILE 23 variables, environment, notation xxiv version command 242, 372, 410
W
wait job state 256 WebSphere Application Server infrastructure 11 starting 16 Index
595
WebSphere Application Server (continued) stopping 16 wild cards composer 194 Windows OS special characters, handling 30, 72, 85, 192, 246 windows user definition 125 WINDOWSTASK 120 within a relative interval follows 150 follows relative to 59 matching criteria 59 within an absolute interval follows 150 follows absolute to 59 matching criteria 59 workstation mailbox files NetReq.msg 17 processes 11 workstation class definition 115 cpuclass 115 ignore 115 members 115 workstation definition 108, 112 access 111 autolink 111 behinfirewall 111 cpuname 109 domain 110 extended agent 111 fta 111 fullstatus 112 host 110 manager 111 node 110 os type 110 secureaddr 110 ServerID 113 standard agent 111 tcpaddr 110 timezone 110 type 111 workstation processes 12 batchman 12 inter-process communication 17 jobman 13 mailman 12 ServerID 12 managing change of job states 19 monman 12 netman 12 processes tree on UNIX 14 processes tree on Windows 15 start of day establishing communication 19 starting 16 stopping 16 writer 12 writer process 12
X
XATASK 120 xref command 424 xrxtrct command 449
596
Program Number: 5698-WSH
Printed in USA
SC32-1274-06
Spine information:
IBM Tivoli Workload Scheduler
Version 8.4
Reference Guide

TWS 8.4 Reference Guide

Uploaded by

Document Information

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

TWS 8.4 Reference Guide

Uploaded by

Copyright:

Available Formats

Tivoli Workload Scheduler

Tivoli Workload Scheduler

Chapter 4. Setting up command-line authentication and user authorizations . 29

Chapter 5. Managing the production cycle . . . . . . . . . . . . . . . 55

Chapter 1. Tivoli Workload Scheduler overview . . . . . . . . . . . . . . 1

Chapter 2. Understanding workstation processes . . . . . . . . . . . . . 11

Chapter 3. Configuring the job environment . . . . . . . . . . . . 21

system command unlock . . . . validate . . . version . . .

237 238 241 242

Chapter 6. Running event-driven workload automation . . . . . . . . 89

Chapter 9. Managing objects in the plan - conman . . . . . . . . . . . 243

Chapter 7. Defining objects in the database . . . . . . . . . . . . . 105

Chapter 8. Managing objects in the database - composer . . . . . . . . 189

IBM Tivoli Workload Scheduler: Reference Guide

Chapter 10. Using utility commands

Chapter 12. Managing time zones . . . 461

Chapter 13. The auditing feature . . . 483

Chapter 14. Managing extended agents . . . . . . . . . . . . . . 489

Chapter 11. Getting reports and statistics . . . . . . . . . . . . . 413

497 497 497 497

Appendix B. Web services interface

Chapter 15. Managing internetwork dependencies . . . . . . . . . . . 499

Appendix C. Quick reference for commands . . . . . . . . . . . . 547

Appendix D. Support information . . . 565

Appendix A. Event-driven workload automation event and action definitions . . . . . . . . . . . . . 509

Glossary . . . . . . . . . . . . . 577 Index . . . . . . . . . . . . . . . 585

IBM Tivoli Workload Scheduler: Reference Guide

. 463 . 463 . 502

Copyright IBM Corp. 1999, 2007

IBM Tivoli Workload Scheduler: Reference Guide

Copyright IBM Corp. 1999, 2007

IBM Tivoli Workload Scheduler: Reference Guide

About this guide

What is new in this release

What is new in this publication

What is new in this publication for version 8.4

Copyright IBM Corp. 1999, 2007

What is new in this guide

IBM Tivoli Workload Scheduler: Reference Guide

What is new in this guide

Who should read this guide

What this guide contains

About this guide

What this guide contains

IBM Tivoli Workload Scheduler: Reference Guide

What this guide contains

Tivoli Workload Scheduler library

IBM Tivoli Workload Scheduling suite library

IBM Tivoli Workload Scheduler distributed library

IBM Tivoli Workload Scheduler: Reference Guide

IBM Tivoli Workload Scheduler for z/OS library

About this guide

IBM Tivoli Workload Scheduler for Applications library

IBM Tivoli Workload Scheduler for Virtualized Data Centers library

IBM Tivoli Workload Scheduler: Reference Guide

Accessing terminology online

IBM Tivoli Workload Scheduler: Reference Guide

Accessing publications online

About this guide

Tivoli Workload Scheduler online books

Using LookAt to look up message explanations

IBM Tivoli Workload Scheduler: Reference Guide

Tivoli technical training

Conventions used in this publication