Sie sind auf Seite 1von 135

Tivoli Workload Scheduler

Version 8.5.1 (Revised May 2010)

Scheduling Workload Dynamically



SC23-9856-01
Tivoli Workload Scheduler
®

Version 8.5.1 (Revised May 2010)

Scheduling Workload Dynamically



SC23-9856-01
Note
Before using this information and the product it integrations, read the information in “Notices” on page 113.

This edition applies to version 8 release 5 modification level 1, Fix Pack 1 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 SC23-9856-00.
© Copyright IBM Corporation 2009, 2010.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . v Chapter 4. Writing JSDL definitions
with the Job Brokering Definition
Tables . . . . . . . . . . . . . . . vii Console . . . . . . . . . . . . . . 47
Job definitions . . . . . . . . . . . . . 49
About this publication . . . . . . . . ix Resources in the job definition . . . . . . . . 53
What is new in this release . . . . . . .
. ix . Using variables in job definitions . . . . . . . 57
1 What is new in this publication for version 8.5.1.1 . ix Using JSDL job definition templates . . . . . . 57
Who should read this publication . . . . . . . ix Scenarios for creating job definitions . . . . . . 60
What this publication contains . . . . . . . . x Scenario: Creating a job definition using a
Publications . . . . . . . . . . . . . . x computer resource group . . . . . . . . . 61
Accessibility . . . . . . . . . . . . . . x Scenario: Creating a job definition using a logical
Tivoli technical training . . . . . . . . . . xi resource group . . . . . . . . . . . . 62
Support information . . . . . . . . . . . xi Scenario: Creating a job definition for a job to
run on x86 processors . . . . . . . . . . 63
Chapter 1. Understanding dynamic Scenario: Creating a job definition for a script to
run on a specific operating system. . . . . . 64
workload scheduling . . . . . . . . . 1 Scenario: Alternative operating system
Dynamic workload broker architecture . . . . .2 requirements . . . . . . . . . . . . . 65
Authorization and roles. . . . . . . . . . .5
Managing users and roles . . . . . . . . .7
Authorization with WebSphere global security . .8
Chapter 5. Submitting and tracking
Scheduling J2EE jobs . . . . . . . . . . .9 jobs . . . . . . . . . . . . . . . . 69
1 Defining specific job types . . . . . . . . . 11 Submitting jobs . . . . . . . . . . . . . 69
1 TWSExecutable Java interface . . . . . . . 19 Submitting jobs with affinity relationships . . . . 70
A business scenario. . . . . . . . . . . . 20 Submitting a job with affinity from the Tivoli
The business . . . . . . . . . . . . . 20 Dynamic Workload Console . . . . . . . . 71
The challenge. . . . . . . . . . . . . 20 Submitting a job with affinity from the command
The solution . . . . . . . . . . . . . 21 line . . . . . . . . . . . . . . . . 71
Submitting jobs with variables . . . . . . . . 72
Chapter 2. Using dynamic workload Submitting a job with variables from the Tivoli
Dynamic Workload Console . . . . . . . . 72
broker to run Tivoli Workload Submitting a job with variables from the
Scheduler jobs . . . . . . . . . . . 27 command line . . . . . . . . . . . . 73
Modifying your existing workload definitions for Job statuses . . . . . . . . . . . . . . 73
use with dynamic workload broker . . . . . . 28 Monitoring submitted jobs . . . . . . . . . 74
Planning and considerations . . . . . . . . 28
Adapting Tivoli Workload Scheduler jobs for Chapter 6. Using the command line
dynamic workload broker . . . . . . . . 28
Using Tivoli Workload Scheduler variables in
interface . . . . . . . . . . . . . . 77
dynamic workload broker jobs . . . . . . . 31 Command-line configuration file . . . . . . . 78
Creating Tivoli Workload Scheduler jobs managed exportserverdata command - downloading the list
by dynamic workload broker . . . . . . . . 32 of workload broker instances from the database . . 81
Using variables in jobs . . . . . . . . . . 33 importserverdata command - uploading the list of
Defining affinity relationships . . . . . . . . 34 workload broker instances to the database . . . . 83
Alias definition in Tivoli Workload Scheduler . . . 34 jobsubmit command - Submitting jobs . . . . . 84
Scenario: A job exploiting the strengths of Tivoli jobquery command - Performing queries on jobs . . 86
Workload Scheduler and dynamic workload broker . 35 jobdetails command - Viewing details on jobs . . . 90
Monitoring and cancelling jobs . . . . . . . . 36 jobcancel command - Canceling jobs . . . . . . 92
jobstore command - Managing job definitions . . . 93
jobgetexecutionlog command - Viewing job output 95
Chapter 3. Identifying the resources for movehistorydata command - Maintaining the
jobs . . . . . . . . . . . . . . . . 39 database tables . . . . . . . . . . . . . 96
Checking physical resources on computers . . . . 40 resource command - Working with resources . . . 98
Creating logical resources. . . . . . . . . . 42 1 Running the resource command from an agent 105
Creating resource groups . . . . . . . . . . 44
Appendix A. Accessibility . . . . . . 107

© Copyright IBM Corp. 2009, 2010 iii


Navigating the interface using the keyboard . . . 107 Determining the business impact . . . . . . 111
Magnifying what is displayed on the screen . . . 107 Describing problems and gathering information 112
Submitting problems . . . . . . . . . . 112
Appendix B. Support information . . . 109
Searching knowledge bases . . . . . . . . . 109 Notices . . . . . . . . . . . . . . 113
Searching the information center . . . . . . 109 Trademarks . . . . . . . . . . . . . . 115
Searching the Internet . . . . . . . . . 109
Obtaining fixes . . . . . . . . . . . . . 109 Index . . . . . . . . . . . . . . . 117
Receiving weekly support updates . . . . . . 110
Contacting IBM Software Support . . . . . . 110

iv IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Figures
1. The dynamic workload broker components. 3 4. Optimization instructions for a job . . . . . 25
2. Resource requirements for the Inventory item 5. Computer Search Results page . . . . . . 42
update job . . . . . . . . . . . . . 23 6. Job Brokering Definition Console main page 52
3. Matching resources for the day-end jobs 24

© Copyright IBM Corp. 2009, 2010 v


vi IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically
Tables
1. Authorized operations by user groups . . . . 6 1 13. Variables in the PrimeNumber.jsdl sample file 15
2. Tivoli Workload Scheduler roles. . . . . . . 8 1 14. Variables in the UploadFile.jsdl sample file 15
3. Dynamic workload broker roles. . . . . . . 8 1 15. Variables in the WSGeneric.jsdl sample file 16
4. Supported J2EE operations . . . . . . . . 9 16. Day-end jobs and requirements . . . . . . 22
1 5. Variables in the CelsiusToFahrenheit.jsdl 17. Supported Tivoli Workload Scheduler variables
1 sample file . . . . . . . . . . . . . 12 in JSDL definitions. . . . . . . . . . . 31
1 6. Variables in the DBQuery.jsdl sample file 12 18. Status mapping between dynamic workload
1 7. Variables in the DownloadFile.jsdl sample file 13 broker and Tivoli Workload Scheduler . . . 36
1 8. Variables in the GetQuote.jsdl sample file 14 19. Resource types and properties . . . . . . 48
1 9. Variables in the JavaJob.jsdl sample file 14 20. Resource types and properties . . . . . . 53
1 10. Variables in the MSSQLJob.jsdl sample file 15 21. Job status . . . . . . . . . . . . . 70
1 11. Variables in the MSSQLJobQuery.jsdl sample 22. Job statuses and supported operations . . . 73
1 file . . . . . . . . . . . . . . . 15 23. Dynamic workload broker commands. . . . 77
1 12. Variables in the NumberToString.jsdl sample
1 file . . . . . . . . . . . . . . . 15

© Copyright IBM Corp. 2009, 2010 vii


viii IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically
About this publication
This guide explains how to dynamically allocate resources to run your workload
using the services of the dynamic workload broker component of Tivoli Workload
Scheduler.

Dynamic workload broker is an on-demand scheduling infrastructure which


provides dynamic management of your environment.

What is new in this release


For information about the new or changed functions in this release, see Tivoli
Workload Automation: 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=swg24024804, and Tivoli Dynamic Workload Console
Download Documents at http://www.ibm.com/support/docview.wss?rs=672
&uid=swg24024805.

1 What is new in this publication for version 8.5.1.1


1 A new section in chapter 1, “Understanding dynamic workload scheduling”,
1 describes how to define and schedule dynamic jobs to perform specific database,
1 file transfer, Java, and Web services operations. It describes the job types, the
1 provided JSDL samples, and explains the procedure for creating your own jobs.

1 Variable tws.job.interactive was added in table "Supported Tivoli Workload


1 Scheduler variables in JSDL definitions" in section "Using Tivoli Workload
1 Scheduler variables in dynamic workload broker jobs" in chapter 2, "Using
1 dynamic workload broker to run Tivoli Workload Scheduler jobs".

1 The description for the resource command was updated with the addition of
1 section "Running the resource command from an agent" that documents this new
1 feature in chapter 6, "Using the command line interface".

1 All updates are marked with a 1 (one) on the left page margin.

Who should read this publication


This guide is intended for administrators responsible for defining user roles and
performing high-level tasks and for operators responsible for creating and
submitting jobs.

Readers should be familiar with the following topics:


v Working knowledge of IBM Tivoli Workload Scheduler
v PC and UNIX operating systems
v Graphical and command line interfaces

© Copyright IBM Corp. 2009, 2010 ix


What this publication contains
This guide contains the following chapters:
v Chapter 1, “Understanding dynamic workload scheduling”
Describes how dynamic workload scheduling works and how the new dynamic
workload broker component is structured within Tivoli Workload Scheduler.
v Chapter 2, “Using dynamic workload broker to run Tivoli Workload Scheduler
jobs”
Describes how to adjust your existing job definitions to run your workload
dynamically.
v Chapter3, “Identifying the resources for jobs”
Describes how to create physical and logical resources.
v Chapter 4, “Writing JSDL definitions with the Job Brokering Definition Console”
Describes how to use the Job Brokering Definition Console to create JSDL job
definitions, how to simulate "templates" that help you match multiple jobs with
a single JSDL definition, and includes several scenarios that demonstrate how to
configure your jobs to achieve specific objectives.
v Chapter 5, “Submitting and tracking jobs”
Describes how to submit jobs to be run on resources that are automatically
allocated. It also describes how to monitor jobs and their status.
v Chapter 6, “Using the command line interface”
Describes how to manage jobs submitted for dynamic scheduling using the
command line of dynamic workload broker.

Publications
Full details of Tivoli Workload Scheduler publications can be found in Tivoli
Workload Automation: Publications. This document also contains information on the
conventions used in the publications.

A glossary of terms used in the product can be found in Tivoli Workload Automation:
Glossary.

Both of these are in the Information Center as separate publications.

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.

x IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Training

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:
Online
Go to the IBM Software Support site at http://www.ibm.com/software/
support/probsub.html and follow the instructions.
IBM Support Assistant
The IBM Support Assistant (ISA) is a free local software serviceability
workbench that helps you resolve questions and problems with IBM
software products. The ISA provides quick access to support-related
information and serviceability tools for problem determination. To install
the ISA software, go to http://www.ibm.com/software/support/isa.
Troubleshooting Guide
For more information about resolving problems, see the problem
determination information for this product.

About this publication xi


xii IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically
Chapter 1. Understanding dynamic workload scheduling
The dynamic workload broker component of Tivoli Workload Scheduler is an
on-demand scheduling infrastructure which provides dynamic management of
your environment. It improves workload coordination, job throughput, and
operations control, and helps to better align IT with business objectives to improve
performance and reduce costs. It optimizes the use of the IT infrastructure by
constantly analyzing your environment to maintain an up-to-date view of the
resources available and matching them to the requirements defined for each job.

The dynamic workload broker Resource Repository in the Tivoli Workload


Scheduler database stores extensive information about the resources available for
running jobs in your environment, as follows:
Physical resources
Hardware and operating system information is collected by a hardware
scan that is regularly run by the Tivoli Workload Scheduler agents. New
resources are automatically discovered and integrated in the scheduling
environment so that jobs can run automatically on these resources.
Logical resources
Logical resources represent resources in your environment that cannot be
discovered by the scan and that might be required when running a job. For
example, logical resources can be set up to represent software licenses. You
can use a task on the Tivoli Dynamic Workload Console to define the
logical resources that you need to accurately describe the requirements of
jobs in your environment.

To use the dynamic workload broker capability, you must match the Tivoli
Workload Scheduler job definitions with dynamic workload broker job definitions.
A dynamic workload broker job definition contains all the information required to
determine the computer system or systems on which a job could run, any
scheduling and job balancing rules that are to be applied when allocating
resources, timeout limits, and any recovery actions to be taken in case of failure, as
well as the information required to identify and run the application. You write
dynamic workload broker job definitions in Job Submission Description Language
(JSDL) using the Job Brokering Definition Console, an easy-to-use user interface
packaged with the product.

When a job is submitted, dynamic workload broker analyzes job requirements and
evaluates resources based on the job definition. If a job must run on the same
resource as a previously submitted job, you can provide this information during
submission by creating an affinity relationship. After the job is launched, you can
monitor its progress.

Thus, if you do install the dynamic scheduling capability of Tivoli Workload


Scheduler, you successfully enhance the scheduling and choreography capabilities
of Tivoli Workload Scheduler with the dynamic allocation of the best available
resources. The Tivoli Dynamic Workload Console provides a convenient
single-access point to all Tivoli Workload Scheduler features, including dynamic
workload broker, and allows you to have a complete view of the whole lifecycle of
your jobs.

© Copyright IBM Corp. 2009, 2010 1


If a job fails or the required resource does not become available before the timeout
period specified in the job definition expires, the client that submitted it is notified.

Benefits

Dynamic workload broker implements a job scheduling and brokering


infrastructure that provides the following major functions to help you dynamically
manage your business:
v Manages the automatic discovery of computers available in the scheduling
domain with their attributes.
v Manages the matching of jobs to appropriate resources based on job
requirements and resource attributes.
v Manages the job dispatching to target resources, both physical and virtual, that
are capable of running the job.
v Optimizes the use of IT resources.
v Manages resource consumption of a job based on the quantities that it is
planned to use while running.
v Optionally allocates the required quantity exclusively to the job while it is
running.
v Releases the quantity as soon as the job terminates for use by other waiting jobs.
v Provides an easy-to-use Web UI for managing the scheduling activities.
v Integrates scheduling functions and services in the IBM Service Oriented
Architecture (SOA) common programming model.

Dynamic workload broker architecture


Dynamic workload broker is a key component of Tivoli Workload Scheduler in the
strategy of providing a scheduling solution that integrates business scheduling and
dynamic on-demand scheduling.

The following figure shows the main elements of dynamic workload broker and
their interaction within Tivoli Workload Scheduler:

2 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Tivoli Dynamic
Workload Console

Tivoli Workload Scheduler Tivoli Workload


engine Scheduler
database

Workload
Broker
Workstation

Tivoli Dynamic Workload Broker component


Job Brokering
Job Resource
Definition Console
Dispatcher Advisor

Tivoli Workload Scheduler


master domain manager

Tivoli Workload Scheduler agent with


dynamic scheduling capabilities

Resource Advisor Job Executor


Agent

Figure 1. The dynamic workload broker components.

Dynamic workload broker is installed on the master domain manager and on


every backup master, by selecting the dynamic scheduling capability. It runs the
job management and resource management activities of dynamic scheduling. It
comprises the following internal components:
Resource Repository
Stores information about the IT environment and the resource real-time
performance. It is located in the Tivoli Workload Scheduler database.
Resource Advisor
Matches resource allocation requests for incoming jobs to the available
target resources stored in the Resource Repository. Ensures the correct
concurrent use of the resources. Resource allocation requests specify
requirements in terms of resource attributes.

Chapter 1. Understanding dynamic workload scheduling 3


Job Dispatcher
Manages job submission requests. It interacts with the Resource Advisor
converting job resource requirements into appropriate resource allocation
requests.
Job Repository
Stores the JSDL job definitions created using the Job Brokering Definition
Console. It also stores the jobs created when the job definitions are
submitted to dynamic workload broker. It is located in the Tivoli Workload
Scheduler database.
The Job Repository also contains a series of historical tables where
historical data on submitted jobs is stored. Data is moved to the historical
tables on a regular basis to improve access time to the remaining tables.
You can configure the time interval after which data is moved to the
historical tables using the MoveHistoryDataFrequencyInMins parameter
in the JobDispatcherConfig.properties file, as described in IBM Tivoli
Workload Scheduler Administration Guide. You can also move data to the
archive tables using the movehistorydata command, as described in
“movehistorydata command - Maintaining the database tables” on page 96.
Allocation Repository
Keeps track of resources assigned to each job and monitors the resource
status. It is located in the Tivoli Workload Scheduler database.

Dynamic workload broker interacts with the Tivoli Workload Scheduler agent
which receives job submission requests from the Job Dispatcher and manages the
running of jobs from start to finish on the local system. The Tivoli Workload
Scheduler agent includes the following components:
Resource Advisor Agent (RAA)
Scans the resources available on the local computer system and forwards
this information to the Resource Advisor. The configuration of the system
scanner present in each RAA is in the JobManager.ini file in every Tivoli
Workload Scheduler agent.
Job Executor
Submits, runs, and monitors jobs on the local computer. The information
on the job status is returned to the Job Dispatcher.

The workload broker workstation transfers jobs submitted in Tivoli Workload


Scheduler to dynamic workload broker. It emulates the behavior of a Tivoli
Workload Scheduler standard agent. You can monitor these jobs using the Tivoli
Dynamic Workload Console or the conman command line interface. The workload
broker workstation resides in the master domain manager and is installed with
dynamic workload broker if you select the dynamic scheduling capability.

To interact with specific dynamic workload broker items, you use the following
graphical interfaces:
Tivoli Dynamic Workload Console
It is a subset of the Integrated Solutions Console and provides a Web-based
user interface for managing the Tivoli Workload Scheduler environment,
including the dynamic scheduling objects. You can use it to:
v Define and manage logical resources
v Write job definitions in native Job Submission Description Language
v Track job instances and computers

4 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


You also use the Tivoli Dynamic Workload Console to manage the lifecycle
of workload.
Job Brokering Definition Console
Is a structured editing tool you use to create and modify Job Submission
Description Language (JSDL) files. These files are saved in the Job
Repository as job definitions and become available for submission. The
JSDL files adhere to the XML syntax and semantics as defined in the JSDL
schema.

You can submit the following types of jobs:


v Tivoli Workload Scheduler jobs, in the form of scripts or executables
v Extended agent jobs, including jobs based on the access methods supported by
Tivoli Workload Scheduler for Applications
v Applications based on Java 2 Platform Enterprise Edition (J2EE)

When you submit a job, dynamic workload broker checks the job requirements, the
available resources and their related characteristics, and submits the job to the
resource that best meets the requirements. Load balancing across resource pools is
guaranteed over time. New resources just provisioned are automatically discovered
and integrated in the scheduling environment so that jobs can run automatically on
these resources.

You can also establish an affinity relationship between two or more jobs when you
want them to run on the same resource, for example when the second job must use
the results generated by the previous job. If the resource is not available, the affine
job is held until the resource is available again. You can define affinity between
two or more jobs using the Tivoli Dynamic Workload Console or the dynamic
workload broker command line interface.

Authorization and roles


Each task you can perform using dynamic workload broker requires a certain level
of authorization. A role represents a certain level of authorization and includes the
tasks appropriate for that level of authorization.

The Tivoli Dynamic Workload Console is installed on the Integrated Solutions


Console, an infrastructure which provides a common administration console for
multiple products.

To access the Tivoli Dynamic Workload Console Welcome page, do the following:
1. Enter the following address in a supported browser:
http://<server_name>:<port_name>/ibm/console/login

where,
server_name
The fully qualified host name of the master domain manager or backup
master (where the dynamic scheduling capability was enabled).
port_name
The port number you configured for the master domain manager or
backup master running the active dynamic workload broker instance.
2. Enter a supported user name and password.

The Tivoli Dynamic Workload Console Welcome page displays.

Chapter 1. Understanding dynamic workload scheduling 5


The Tivoli Dynamic Workload Console is a role-based interface, in which tasks are
enabled or disabled based on the user role and authorization. Depending on the
authorization level of the user logging on to the Integrated Solutions Console,
some tasks might not be displayed.

When the Tivoli Dynamic Workload Console is installed, the following user groups
are created in the Integrated Solutions Console:
TDWBAdministrator
The users in this group can perform the following operations from the
Tivoli Dynamic Workload Console:
v Create logical resources and resource groups, delete, query, suspend, and
resume logical resources, computers, and resource groups.
v Define server connections.
v Define, edit, and delete jobs.
v Submit, query and cancel job instances.
v Define user preferences for the Console.
TDWBConfigurator
The users in this group can perform the following operations in the Tivoli
Dynamic Workload Console:
v Create logical resources and resource groups, delete, query, suspend, and
resume logical resources, computers, and resource groups.
v Define server connections.
v Define user preferences for the Console.
TDWBDeveloper
The users in this group can perform the following operations in the Tivoli
Dynamic Workload Console:
v Define server connections.
v Define, edit, and delete jobs.
v Define user preferences for the Console.
TDWBOperator
The users in this group can perform the following operations in the Tivoli
Dynamic Workload Console:
v Create logical resources and resource groups, delete, query, suspend, and
resume logical resources, computers, and resource groups.
v Define server connections.
v Submit, query and cancel job instances.
v Define user preferences for the Console.
WSClient
This is a WebSphere Application Server role that is automatically defined
with the All authenticated? property set to Yes. It is required to enable
Web services for dynamic workload broker and you must leave it as it is.

Table 1 lists which operations can be performed by each group for each task group
available in the Tivoli Dynamic Workload Console:
Table 1. Authorized operations by user groups
TDWB TDWB TDWB TDWB
Supported Operations Administrator Configurator Developer Operator
Scheduling Environment

6 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Table 1. Authorized operations by user groups (continued)
TDWB TDWB TDWB TDWB
Supported Operations Administrator Configurator Developer Operator
Define New Logical Resources X X X
Define New Resource Group X X X
Logical Resources X X X
Resource Groups X X X
Configuration
Server Connections X X X X
Definitions
Define a New Job X X
Jobs X X X
Tracking
Jobs X X
Computers X X X
Preferences
User Preferences X X X X

For information on adding users, refer to the Integrated Solutions Console help.

Managing users and roles


During the Web console installation, new predefined roles and groups are created
in the ISC. These roles determine which console panels are available to a user, and
therefore which activities the user can perform from the console.

These roles authorize users to access the console panels. The user specified in the
engine connection determines which operations can be run locally on a connected
engine. For example, if the user specified in a Tivoli Workload Scheduler engine
connection is not authorized to run reporting in the Tivoli Workload Scheduler
security file, then, even though the user logged in to the console can access the
reporting panels, they cannot perform reporting operations on that Tivoli Workload
Scheduler engine. For more information about how to configure the security file,
refer to the IBM Tivoli Workload Scheduler Administration Guide.

There is a one-to-one relationship between each new role, and the group with the
same name. This means, for example, that all users belonging to the
TWSWEBUIAdministrator group have the TWSWEBUIAdministrator role.

You cannot modify the roles, but you can create new groups where you combine
different roles. For example, you can create a group named my_operators and
assign to it the TWSWEBUIOperator and the TDWBOperators roles so that all
users added to this group can perform operator actions on both Tivoli Workload
Scheduler and dynamic workload broker from the Tivoli Dynamic Workload
Console.

If you do not assign a role to an ISC user, that user, after having logged in, will not
see any entry for Tivoli Workload Scheduler or dynamic workload broker in the
navigation tree.

Chapter 1. Understanding dynamic workload scheduling 7


The following table lists the roles created in the ISC user registry for accessing the
Tivoli Workload Scheduler environments using the Tivoli Dynamic Workload
Console, and the panels they can access:
Table 2. Tivoli Workload Scheduler roles.
Tivoli Workload Scheduler panels accessible from the
Roles Navigation Tree
TWSWEBUIAdministrator All panels
TWSWEBUIOperator Dashboard
My Tasks
Workload Tracking
Workload Submission on Request
Workload Forecasting
Preferences

Note: The TWSWEBUIConfigurator role is also needed in


order to work with Workload Forecasting tasks.
TWSWEBUIDeveloper Workload Definition
Preferences
TWSWEBUIAnalyst Reporting
Preferences
TWSWEBUIConfigurator Scheduling Environment
Preferences

The following table lists the roles created in the ISC user registry for accessing the
dynamic workload broker environments using the Tivoli Dynamic Workload
Console, and the panels they can access:
Table 3. Dynamic workload broker roles.
Tivoli Dynamic Workload Broker panels accessible from the
Roles Navigation Tree
TDWBAdministrator All panels
TDWBOperator Scheduling Environment
Configuration
Definitions, except Define a New Job
Tracking
Preferences
TDWBDeveloper Configuration
Definitions
Preferences
TDWBConfigurator Scheduling Environment
Configuration
Tracking, except Job Instances
Preferences

Authorization with WebSphere® global security


When dynamic workload broker is installed, corresponding roles are set up on the
WebSphere Application Server. By default, these roles are not used. However, if
you enable global security for the WebSphere Application Server cell where also
dynamic workload broker is installed, the authorization required to perform tasks
from theTivoli Dynamic Workload Console is also validated by the WebSphere
Application Server.

8 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


When global security is enabled, Tivoli Dynamic Workload Console users must
provide credentials for accessing the server. These credentials correspond to
existing users defined in the operating system where the WebSphere Application
Server resides or in an LDAP server. A task on the WebSphere Application Server
console maps these users to the dynamic workload broker roles. Using these
mappings, WebSphere Application Server is able to determine the level of
authorization of the user submitting a request to the server.

For example, the Administrator needs to define John Jones as a TDWBConfigurator


in an environment that uses global security. On the WebSphere Application Server
console, the user conf, has been mapped to the Configurator role. The
Administrator does the following:
1. Creates a new user account for John Jones on the Integrated Solutions Console.
2. Assigns the new user to the TDWBConfigurator user group.
3. Provides John Jones with his user name and password to access the Tivoli
Dynamic Workload Console and the user name conf and its associated
password for connecting to dynamic workload broker.

For more information about assigning user roles on the Integrated Solutions
Console and defining user roles from the WebSphere Application Server console,
refer to the IBM Tivoli Workload Scheduler Administration Guide.

Scheduling J2EE jobs


After you configure the J2EE feature of dynamic workload broker (see the IBM
Tivoli Workload Scheduler Administration Guide), you can run the following J2EE
operations:
v Invoke the process method of an EJB which implements the
com.ibm.websphere.scheduler.TaskHandler interface. After developing the EJB,
you can specify the related JNDI Home directory in the Application page of the
Job Brokering Definition Console, or in the ejb element in the JSDL file.
v Post a message to a JMS queue. You can define the message to be sent in the
JMS Properties pane in the Application page of the Job Brokering Definition
Console, or in the ejb element in the JSDL file.

The J2EE operations you can perform vary depending on the scheduler type (direct
or indirect) you select, and on whether or not you enable WebSphere Application
Server and J2EE security. The following table summarizes the possible
configuration settings:
Table 4. Supported J2EE operations
Version of
the external
WebSphere
WebSphere Direct/
Application
Application EJB/JMS J2EE security Indirect Supported
Server
Server where scheduler
security
you schedule
jobs
6.1 EJB No No Direct Yes
6.1 EJB Yes Yes Direct Yes
6.1 EJB Yes No Direct No
6.1 EJB No No Indirect Yes
6.1 EJB Yes Yes Indirect Yes

Chapter 1. Understanding dynamic workload scheduling 9


Table 4. Supported J2EE operations (continued)
Version of
the external
WebSphere
WebSphere Direct/
Application
Application EJB/JMS J2EE security Indirect Supported
Server
Server where scheduler
security
you schedule
jobs
6.1 EJB Yes No Indirect Yes
6.1 JMS No No Direct No
6.1 JMS Yes Yes Direct Yes
6.1 JMS Yes No Direct No
6.1 JMS No No Indirect Yes
6.1 JMS Yes Yes Indirect Yes
6.1 JMS Yes No Indirect Yes
7.0 EJB No No Direct Yes
7.0 EJB Yes Yes Direct Yes
7.0 EJB Yes No Direct Yes
7.0 EJB No No Indirect Yes
7.0 EJB Yes Yes Indirect Yes
7.0 EJB Yes No Indirect Yes
7.0 JMS No No Direct Yes
7.0 JMS Yes Yes Direct Yes
7.0 JMS Yes No Direct Yes
7.0 JMS No No Indirect Yes
7.0 JMS Yes Yes Indirect Yes
7.0 JMS Yes No Indirect Yes

When configuring the J2EE feature, you must decide the scheduling type you want
to use for your J2EE jobs. You can choose between the following types:
indirect scheduling
Selecting an indirect invoker means that dynamic workload broker uses an
existing WebSphere Application Server scheduling infrastructure already
configured on an external WebSphere Application Server. When creating
the job definition, you can specify whether you want to use a direct or
indirect connector in the J2EE Application pane in the Application page in
the Job Brokering Definition Console, or in the invoker element in the
JSDL file. You can choose indirect scheduling to invoke an EJB that does
not contain roles. If the EJB contains roles, use the direct scheduling.
direct scheduling
Selecting a direct invoker means that dynamic workload broker
immediately forwards the job to the components (EJB or JMS) of the
external WebSphere Application Server instance. When creating the job
definition, you can specify whether you want to use a direct or indirect
connector in the J2EE Application pane in the Application page in the Job
Brokering Definition Console, or in the invoker element in the JSDL file.
For more information about the Job Brokering Definition Console, see the
online help.

10 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Define these settings in the J2EEJobExecutorConfig.properties file (see the IBM
Tivoli Workload Scheduler Administration Guide for details).

1 Defining specific job types


1 You can define and schedule dynamic jobs to perform specific database, file
1 transfer, Java, and Web services operations, instead of using a generic script or
1 command. You can customize the sample files provided with the product to match
1 your requirements using the Tivoli Dynamic Workload Console.

1 About this task

1 The procedure for defining specific jobs is the same for all job types. The only
1 difference is in the variables you define, which are related to the job type you
1 select. You can select a specific job type to perform one or more of the following
1 operations. Any passwords you insert in the jobs are securely encrypted. You can
1 edit the sample file provided with Tivoli Workload Scheduler using the Tivoli
1 Dynamic Workload Console. The following sample files are available for
1 customization in: installation_directory/TDWB/sampleJSDL:
1 Data transfer jobs
1 Use these jobs to transfer files to and from a server reachable using FTP,
1 SSH, or other protocols. The following sample files are available:
1 DownloadFile.jsdl
1 Download one single file for each job. To download more than one
1 file, run more jobs.
1 UploadFile.jsdl
1 Upload one single file for each job. To upload more than one file,
1 run more jobs.
1 Database access jobs
1 Use these jobs to access a database, and perform queries and jobs on it.
1 The following sample files are available:
1 DBQuery.jsdl
1 Perform a query or a stored procedure on a database. A database
1 stored procedure is a subroutine available to applications accessing
1 a relational database system. Typical uses for stored procedures
1 include data validation (integrated into the database), access
1 control mechanisms, and data extract mechanisms.

1 Note:
1 v Before you can run a query on a database, download the JDBC
1 drivers for your database client to the workstation where you
1 plan to run this job type. Specify the path to the database client
1 jar files in the DatabaseJobExecutor.properties file, located in
1 the JavaExt\cfg folder in your Tivoli Workload Scheduler
1 installation directory. Define the jdbcDriversPath property to
1 point to the JDBC jar files folder, for example
1 jdbcDriversPath=c:\\mydir\\jars\\jdbc. The JDBC jar files
1 must be located in the specified folder or in its subfolders.
1 Ensure that you have list permissions on the folder and its
1 subfolders.
1 v When defining stored procedures, ensure that they do not
1 contain output variables. Stored procedures containing output
1 variables are not supported.

Chapter 1. Understanding dynamic workload scheduling 11


1 MSSQLJob.jsdl
1 Perform a job on an MSSQL database.
1 MSSQLJobQuery.jsdl
1 Perform a query, an asynchronous job, and a second query on an
1 MSSQL database.
1 Web services jobs
1 Use these jobs to call a Web service. The following sample files are
1 available:
1 CelsiusToFahrenheit.jsdl
1 Convert temperatures from Celsius to Fahrenheit.
1 GetQuote.jsdl
1 Obtain a quote on the stock market.
1 NumberToString.jsdl
1 Convert a number to a string.
1 PrimeNumber.jsdl
1 Obtain prime numbers until the upper bound is reached.
1 WSGeneric.jsdl
1 Call a generic Web service.
1 Java job
1 Use this job to perform a Java job using the TWSExecutable interface.
1 Ensure that you have list permissions on the folder specified in the jarPath
1 property. For more information about the interface, see “TWSExecutable
1 Java interface” on page 19. The following sample file is available:
1 JavaJob.jsdl
1 Perform a Java job.

1 The following variables are available in the JSDL samples:


1 Table 5. Variables in the CelsiusToFahrenheit.jsdl sample file
1 Variable Supported values Explanation
1 ${CelsiusTemp} N/A Temperature to be converted
1 expressed in degrees Celsius.
1
1 Table 6. Variables in the DBQuery.jsdl sample file
1 Variable Supported values Explanation
1 ${databaseType} Database type
1 db2 IBM DB2
1 mssql Microsoft SQL
1 Server
1 oracle Oracle DBMS
1 ${server} N/A Database server
1 ${port} N/A Database port
1 ${database} N/A Database ID
1 ${query} N/A Name of the query to be run
1 in the database
1 ${username} N/A User name of the user
1 logging on to the database

12 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


1 Table 6. Variables in the DBQuery.jsdl sample file (continued)
1 Variable Supported values Explanation
1 ${password} N/A Password of the user logging
1 on to the database
1
1 Table 7. Variables in the DownloadFile.jsdl sample file
1 Variable Supported values Explanation
1 ${server} N/A Fully qualified address of the
1 server for downloading the
1 file
1 ${localFile} N/A Fully qualified path and
1 name of the file to be created
1 on the local target. Wildcards
1 are not supported.
1 ${remotefile} N/A Fully qualified path and
1 name of the file to be
1 downloaded
1 ${username} N/A User name of the user
1 logging on to the database
1 ${password} N/A Password of the user logging
1 on to the database

Chapter 1. Understanding dynamic workload scheduling 13


1 Table 7. Variables in the DownloadFile.jsdl sample file (continued)
1 Variable Supported values Explanation
1 ${protocol} Protocol to be used for the
11 WINDOWS
connection
1 Is the Microsoft file
1 sharing protocol. If
1 you do not specify a
1 protocol, and SSH
1 does not work,
1 WINDOWS is
1 assumed. Specify
1 the shared directory
1 in the REMOTEFILE
1 keyword, without
1 specifying any paths
1 where the shared
1 directory is nested.
1 Specify the address
1 of the workstation
1 hosting the shared
1 directory in the
1 SERVER keyword.
1 SSH Is a network
1 protocol that
1 provides file access,
1 file transfer, and file
1 management
1 functions over any
1 reliable data stream.
1 If you do not
1 specify a protocol,
1 SSH is assumed.
1 FTP Is a standard
1 network protocol
1 used to exchange
1 files over a
1 TCP/IP-based
1 network, such as the
1 Internet.
1
1 Table 8. Variables in the GetQuote.jsdl sample file
1 Variable Supported values Explanation
1 ${StockSymbol} N/A Stock symbol for which the
1 quote is requested
1
1 Table 9. Variables in the JavaJob.jsdl sample file
1 Variable Supported values Explanation
1 ${jarPath} N/A Path to the .jar file
1 ${className} N/A Name of the class, including
1 the package name
1 ${param1} N/A First parameter of the class
1 ${param2} N/A Second parameter of the
1 class
1 ${param3} N/A Third parameter of the class

14 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


1
1 Table 10. Variables in the MSSQLJob.jsdl sample file
1 Variable Supported values Explanation
1 ${databaseType} Database type
1 oracle Oracle DBMS
1 ${server} N/A Database server
1 ${port} N/A Database port
1 ${database} N/A Database ID
1 ${jobname} N/A Name of the job to be
1 performed in the database
1 ${username} N/A User name of the user
1 logging on to the database
1 ${password} N/A Password of the user logging
1 on to the database
1
1 Table 11. Variables in the MSSQLJobQuery.jsdl sample file
1 Variable Supported values Explanation
1 ${databaseType} Database type
1 oracle Oracle DBMS
1 ${server} N/A Database server
1 ${port} N/A Database port
1 ${database} N/A Database ID
1 ${query1} N/A First query to be run on the
1 database
1 ${jobname} N/A Name of the job to be
1 performed on the database
1 ${query2} N/A Second query to be run on
1 the database
1 ${username} N/A User name of the user
1 logging on to the database
1 ${password} N/A Password of the user logging
1 on to the database
1
1 Table 12. Variables in the NumberToString.jsdl sample file
1 Variable Supported values Explanation
1 ${NumberToConvert} N/A Number to be converted
1
1 Table 13. Variables in the PrimeNumber.jsdl sample file
1 Variable Explanation
1 ${UpperBound} Number to be converted.
1
1 Table 14. Variables in the UploadFile.jsdl sample file
1 Variable Supported values Explanation
1 ${server} N/A Fully qualified address of the
1 server for uploading the file

Chapter 1. Understanding dynamic workload scheduling 15


1 Table 14. Variables in the UploadFile.jsdl sample file (continued)
1 Variable Supported values Explanation
1 ${localFile} N/A Fully qualified path and
1 name of the file to be
1 uploaded
1 ${remoteFile} N/A Fully qualified path and
1 name of the file to be created
1 on the remote target
1 ${username} N/A User name of the user
1 logging on to the database
1 ${password} N/A Password of the user logging
1 on to the database
1 ${protocol} Protocol to be used for the
11 WINDOWS
connection
1 SSH
1 FTP
1
1 Table 15. Variables in the WSGeneric.jsdl sample file
1 Variable Supported values Explanation
1 ${Operation} N/A Name of the operation to be
1 performed
1 ${wsdlURL} N/A URL of the WSDL file
1 ${Param} N/A Parameter for the WSDL file
1

1 You can define the jobs using the jobstore command or the Tivoli Dynamic
1 Workload Console. For more information about the jobstore command, see
1 “jobstore command - Managing job definitions” on page 93. To define and
1 customize the jobs using the Tivoli Dynamic Workload Console, perform the
1 following operations:

1 Procedure
1 1. Browse to the relevant JSDL file and copy the JSDL statements.
1 2. Log on to the Tivoli Dynamic Workload Console.
1 3. In the console navigation tree, select the entry for Tivoli Dynamic Workload
1 Broker.
1 4. Expand Definitions and click Define a New Job.
1 5. In the Job Submission Description Language field, paste the JSDL statements
1 for the job definition and specify the job requirements, as necessary.
1 6. Specify a name for the job definition and save it. The job is now available in
1 the database.
1 7. Browse to the Tivoli Workload Scheduler entry in the Portfolio.
1 8. Click Workload » Design » Create Workload Definitions.
1 9. In the displayed panel, specify the engine connection that you want to use.
1 10. Click Go.
1 11. In the Workload Designer, from the Working List pane, click New » Job
1 Definition » Workload Broker Job Definition.
1 12. In the Workspace pane, specify the properties for the job using the General,
1 Task, Affinity, and Recovery Options tabs.

16 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


1 13. In the Task pane, search for the job definition that you created in step 6 on
1 page 16. The variables present in the job definition are displayed in the
1 Variable list pane.
1 14. Provide a value for the variables, as necessary.
1 15. Save the job definition.

1 Example
1 1. The following database job connects to an existing DB2 database and performs
1 basic operations on the database, such as create, update, delete on database
1 entities:
1 <jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
1 xmlns:jsdldatabase="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdldatabase" name="DATABASE">
1 <jsdl:application name="database">
1 <jsdldatabase:database>
1 <jsdldatabase:sqlActionInfo>
1 <jsdldatabase:dbms>db2</jsdldatabase:dbms>
1 <jsdldatabase:server>nc115037.romelab.it.ibm.com</jsdldatabase:server>
1 <jsdldatabase:port>50000</jsdldatabase:port>
1 <jsdldatabase:database>executor</jsdldatabase:database>
1
1 <jsdldatabase:statements>
1 <jsdldatabase:dbStatement>insert into test.target (id,hostname,ipaddress,
1 port) values ('id1','myHost','1.1.1.1',80)</jsdldatabase:dbStatement>
1 <jsdldatabase:dbStatement>select * from test.target where id='id1'
1 and hostname='myHost'and ipaddress='1.1.1.1' and port=80</jsdldatabase:dbStatement>
1 <jsdldatabase:dbStatement>update test.target set hostname='UpdateHost'</jsdldatabase:dbStatement>
1 <jsdldatabase:dbStatement>select * from test.target where id='id1'
1 and hostname='UpdateHost'and ipaddress='1.1.1.1' and port=80</jsdldatabase:dbStatement>
1 <jsdldatabase:dbStatement>delete from test.target where id='id1'
1 and hostname='UpdateHost'and ipaddress='1.1.1.1' and port=80</jsdldatabase:dbStatement>
1 <jsdldatabase:dbStatement>select * from test.target where id='id1'
1 and hostname='UpdateHost'and ipaddress='1.1.1.1' and port=80</jsdldatabase:dbStatement>
1 </jsdldatabase:statements>
1
1 <jsdldatabase:credentials>
1 <jsdl:userName>Administrator</jsdl:userName>
1 <jsdl:password>tdwb8nxt</jsdl:password>
1 </jsdldatabase:credentials>
1 </jsdldatabase:sqlActionInfo>
1 </jsdldatabase:database>
1 </jsdl:application>
1 </jsdl:jobDefinition>
1 2. The following database job connects to an existing Oracle database and
1 performs basic operations on the database, such as create, update, delete on
1 database entities:
1 <jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
1 xmlns:jsdldatabase="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdldatabase" name="DATABASE">
1 <jsdl:application name="database">
1 <jsdldatabase:database>
1 <jsdldatabase:sqlActionInfo>
1 <jsdldatabase:dbms>oracle</jsdldatabase:dbms>
1 <jsdldatabase:server>nc115037.romelab.it.ibm.com</jsdldatabase:server>
1 <jsdldatabase:port>1521</jsdldatabase:port>
1 <jsdldatabase:database>orcl</jsdldatabase:database>
1
1 <jsdldatabase:statements>
1 <jsdldatabase:dbStatement>insert into target (id,hostname,ipaddress,
1 port) values ('id1','myHost','1.1.1.1',80)</jsdldatabase:dbStatement>
1 <jsdldatabase:dbStatement>select * from target where id='id1'
1 and hostname='myHost'and ipaddress='1.1.1.1' and port=80</jsdldatabase:dbStatement>
1 <jsdldatabase:dbStatement>update target set hostname='UpdateHost'
1 </jsdldatabase:dbStatement>
1 <jsdldatabase:dbStatement>select * from target where id='id1'
1 and hostname='UpdateHost'and ipaddress='1.1.1.1' and port=80</jsdldatabase:dbStatement>
1 <jsdldatabase:dbStatement>delete from target where id='id1'
1 and hostname='UpdateHost'and ipaddress='1.1.1.1' and port=80</jsdldatabase:dbStatement>
1 <jsdldatabase:dbStatement>select * from target where id='id1'
1 and hostname='UpdateHost'and ipaddress='1.1.1.1' and port=80</jsdldatabase:dbStatement>
1 </jsdldatabase:statements>
1
1 <jsdldatabase:credentials>
1 <jsdl:userName>scott</jsdl:userName>
1 <jsdl:password>tiger</jsdl:password>
1 </jsdldatabase:credentials>

Chapter 1. Understanding dynamic workload scheduling 17


1 </jsdldatabase:sqlActionInfo>
1 </jsdldatabase:database>
1 </jsdl:application>
1 </jsdl:jobDefinition>
1 3. The following Java job launches a Java class located in the path specified in the
1 jarPath variable. The package of the Java class is indicated in the className
1 variable. The parameters for the Java class are indicated with key1 e key2:
1 <?xml version="1.0" encoding="UTF-8"?>
1 <jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
1 xmlns:jsdljava="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdljava" name="JAVA">
1 <jsdl:application name="java">
1 <jsdljava:java>
1 <jsdljava:javaParms>
1 <jsdljava:jarPath>C:/TestTools/executors/java</jsdljava:jarPath>
1 <jsdljava:className>com.ibm.test.executor.Exjvsb01</jsdljava:className>
1 <jsdljava:parameters>
1 <jsdljava:parameter key="key1">parameter1</jsdljava:parameter>
1 <jsdljava:parameter key="key2">parameter2</jsdljava:parameter>
1 </jsdljava:parameters>
1 </jsdljava:javaParms>
1 </jsdljava:java>
1 </jsdl:application>
1 </jsdl:jobDefinition>
1 4. The following file transfer job downloads the specified file using the credentials
1 and the protocol indicated in the file:
1 <?xml version="1.0" encoding="UTF-8"?>
1 <jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
1 xmlns:jsdlfiletransfer="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdlfiletransfer" name="FILETRANSFER">
1
1 <jsdl:application name="filetransfer">
1 <jsdlfiletransfer:filetransfer>
1 <jsdlfiletransfer:downloadInfo>
1 <jsdlfiletransfer:server>nc121031.romelab.it.ibm.com
1 </jsdlfiletransfer:server>
1 <jsdlfiletransfer:localfile>./npp.5.1.1.Installer.DW.exe
1 </jsdlfiletransfer:localfile>
1 <jsdlfiletransfer:remotefile>/TestTools/executors/fileTransfer/
1 npp.5.1.1.Installer.DW.exe</jsdlfiletransfer:remotefile>
1
1 <jsdlfiletransfer:credentials>
1 <jsdl:userName>root</jsdl:userName>
1 <jsdl:password>tws08app</jsdl:password>
1 </jsdlfiletransfer:credentials>
1
1 <jsdlfiletransfer:protocol>FTP</jsdlfiletransfer:protocol>
1 </jsdlfiletransfer:downloadInfo>
1 </jsdlfiletransfer:filetransfer>
1 </jsdl:application>
1 </jsdl:jobDefinition>
1 5. The following file transfer job uploads the specified file using the credentials
1 and the protocol indicated in the file:
1 <?xml version="1.0" encoding="UTF-8"?>
1 <jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
1 xmlns:jsdlfiletransfer="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdlfiletransfer" name="FILETRANSFER">
1
1 <jsdl:application name="filetransfer">
1 <jsdlfiletransfer:filetransfer>
1 <jsdlfiletransfer:uploadInfo>
1 <jsdlfiletransfer:server>nc125216.romelab.it.ibm.com
1 </jsdlfiletransfer:server>
1 <jsdlfiletransfer:localfile>/FileTransferForUploadTest
1 </jsdlfiletransfer:localfile>
1 <jsdlfiletransfer:remotefile>/TestTools/executors/fileTransfer/
1 FileTransferForUploadTest</jsdlfiletransfer:remotefile>
1
1 <jsdlfiletransfer:credentials>
1 <jsdl:userName>root</jsdl:userName>
1 <jsdl:password>Tivoli00</jsdl:password>
1 </jsdlfiletransfer:credentials>
1
1 <jsdlfiletransfer:protocol>SSH</jsdlfiletransfer:protocol>
1 </jsdlfiletransfer:uploadInfo>
1 </jsdlfiletransfer:filetransfer>
1 </jsdl:application>
1 </jsdl:jobDefinition>

18 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


1 6. The following JSDL file invokes a Web service. The Web service application
1 name is shown in the operation variable and the web service URL is indicated
1 in the wsdlURL variable. Define all arguments the Web service requires in the
1 JSDL arguments section. When the Web service completes, the agent captures
1 the output and returns it as the job log:
1 <?xml version="1.0" encoding="UTF-8"?>
1 <jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
1 xmlns:jsdlws="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdlws" description="Calls a web service to perform a sum of two numbers" name="SumNumber">
1 <jsdl:annotation></jsdl:annotation>
1 <jsdl:application name="ws">
1 <jsdlws:ws>
1 <jsdlws:wsToInvoke operation="getSum" wsdlURL="https://nc125166.romelab.
1 it.ibm.com:9443/Sum/services/Sum/wsdl/Sum.wsdl">
1 <jsdlws:arguments>
1 <jsdlws:value>1</jsdlws:value>
1 <jsdlws:value>2</jsdlws:value>
1 </jsdlws:arguments>
1
1 <jsdlws:credentials>
1 <jsdl:userName>administrator</jsdl:userName>
1 <jsdl:password>tivoli</jsdl:password>
1 </jsdlws:credentials>
1 </jsdlws:wsToInvoke>
1 </jsdlws:ws>
1 </jsdl:application>
1 </jsdl:jobDefinition>

1 TWSExecutable Java interface


1 You use the TWSExecutable Java interface to define Java jobs to perform custom
1 operations. The TWSExecutable Java interface is available in the following location:
1 <TWA_home>/TWS/JavaExt/eclipse/plugins/
1 com.ibm.scheduling.agent.java_<version>.jar.

1 The interface content is as follows:


1 import com.ibm.scheduling.agent.java.parametersdomain.Parameters;
1
1 public interface TWSExecutable {
1 public void validateParameters(Parameters parameters) throws Exception;
1 public void execute(Parameters parameters) throws Exception;
1 }

1 You can use the


1 validateParameters

1 method to validate the parameters provided and return an exception in case of


1 errors.

1 The following example shows how to check for the presence of the name
1 parameter and write the name to a log file:
1 import java.io.BufferedWriter;
1 import java.io.FileOutputStream;
1 import java.io.OutputStreamWriter;
1
1 import com.ibm.scheduling.agent.java.jobexecutor.TWSExecutable;
1 import com.ibm.scheduling.agent.java.parametersdomain.Parameters;
1
1
1 public class Executor implements TWSExecutable{
1
1 public void validateParameters(Parameters arg0) throws Exception {
1 if(arg0.getParameter("name")==null||arg0.getParameter("name").equals(""))
1 throw new Exception("Invalid Name");
1
1 }
1

Chapter 1. Understanding dynamic workload scheduling 19


1 public void execute(Parameters arg0) throws Exception {
1 BufferedWriter bw= new BufferedWriter(new OutputStreamWriter( new
1 FileOutputStream(arg0.getOutputFile()), "UTF8"));
1
1 bw.write(arg0.getParameter("name"));
1 bw.close();
1
1
1 }
1
1 }
1
A business scenario
The purpose of the following scenario is to show how a system of dynamic
allocation of workload to computer resources can make an important contribution
to the smooth and profitable running of a business by optimizing use of available
resources.

The business
Fine Cola is a medium-sized enterprise that produces and distributes soft drinks to
retailers across the country. It owns a production plant and several strategically
located distribution centers. Fine Cola has a range of customer types from
nationwide foodstore chains to small local outlets. The foodstore chains normally
maintain fixed orders though changes can be made at delivery time. Small local
outlets often restock directly from the delivery truck with no previous order made.
Order quantities can vary, peaking in the warmer season and during holidays.

The process from ordering of the raw materials to the delivery of the finished
product and the return of empties consists of a number of subprocesses: inventory,
purchase ordering or raw materials, production, supply to distribution centers, and
delivery. All of these subprocesses are interdependent and activities in one
subprocess are often triggered by an event in another. For example, ordering of a
raw material is automatically triggered when inventory discovers that the amount
of the raw material currently held in the warehouse has hit the reorder level.

The challenge
Fine Cola uses Tivoli Workload Scheduler to manage the timing and
interdependencies of its production and supply process. However, in some areas
problems are occurring with computer resource allocation:
v Some scheduled jobs are experiencing long wait times before resources become
available.
v Performance problems are occurring as some resources become overloaded.
v When a resource that normally runs workload is removed temporarily or
permanently, the job definitions must be manually changed to target a new
resource.

Tivoli Workload Scheduler uses fixed resource allocation and this is presenting
Fine Cola with the choice of either acquiring more resources or constantly running
the risk that jobs will not be completed in a timely manner.

The problems are particularly evident during the end-of-day reconciliation process.
This process starts when the last delivery truck returns and must be completed
before the next day's delivery route planning can be started. The main focus of the
end of day processing is the daily transaction database. This database includes a
wide variety of transactions including consignment transactions for each item in a

20 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


customer order, consignment transactions for each delivery load, receipt
transactions for returned items, receipt transactions for empties, adjustments
transactions to customer billing when the order amount has been changed on
delivery. These transactions are used to update the following databases: customer
orders and billing, inventory, and general ledger.

Within a small time window, the following tasks must be completed:


v Update the inventory database with returned items.
v Update the inventory database with returned empties.
v Update customer orders and billing database to take account of changes to
orders and to create orders and billing for customers who have restocked from
the truck.
v Update the general ledger database.
v Conduct data-mining extractions on the transaction database and save the
extracted information in the management reports database for later analysis of
buying trends to be used in future promotion campaigns.
v Produce several reports of varying levels of detail of transactions by item, by
customer, and by delivery route to enable analysis of the profitability of product
lines and routes. Save these reports in the management reports database.

The solution
Fine Cola decides that an important element is missing from their IT solution: the
ability to maintain a pool of computer resources, to identify those that match the
requirements of a job, and to dynamically assign the job to a matching resource
that is available at submission time.

A decision is made to take advantage of the dynamic workload broker feature of


Tivoli Workload Scheduler, since this seems to cover their requirements for job
scheduling, dependency resolution, and efficient allocation of resources. The IT
infrastructure administrator starts by migrating to this version of Tivoli Workload
Scheduler and by deploying Tivoli Workload Scheduler agents on the computers
normally used to perform the tasks associated with the transaction database in the
end-of-day reconciliation process. In this way, it will be possible to see whether
dynamic allocation results in a more efficient use of resources.

The hardware scan performed by the agent provides a pool of detailed information
about the computer systems, their operating systems, file systems, and network
connections. To complete the picture of available resources and make it possible to
accurately match resources to job requirements, the administrator must now
identify the computer systems that have access to the different databases. She does
this by using the Tivoli Dynamic Workload Console to create a logical resource for
each database and linking it to the computer systems from which the database can
be accessed.

Now that all the pieces are in place, the administrator can create the job
definitions, providing an accurate picture of the physical and logical resources
required for the job. She installs the Job Brokering Definition Console on her local
workstation. This tool provides an easy-to-use graphical interface for creating JSDL
job definitions.

She identifies the jobs and job requirements listed in Table 16 on page 22.

Chapter 1. Understanding dynamic workload scheduling 21


Table 16. Day-end jobs and requirements
Access to shared
Job remote drives Operating system Database access
Inventory item None Linux Inventory,
update Transaction
Inventory empties None Linux Inventory,
update Transaction
Customer orders None AIX® with at least Customer,
create/ update 1024 MB of free Transaction
physical memory
Customer orders None AIX Customer,
billing Transaction
Transaction None AIX General ledger,
consolidation and Transaction
General ledger
update
Item information None Linux®, AIX, or Transaction,
data mining HP-UX Management reports
route information None Linux, AIX, or Transaction,
data mining HP-UX Management reports
Sales summary by //shared/reports/ Linux, AIX, or Transaction,
item sales HP-UX Management reports
Sales summary by //shared/reports/ Linux, AIX, or Transaction,
route sales HP-UX Management reports
Sales summary by //shared/reports/ Linux, AIX, or Transaction,
customer sales HP-UX Management reports

These jobs already exist in Tivoli Workload Scheduler but they use static allocation
of resources. She uses the Job Brokering Definition Console to import these jobs
and to create a JSDL job definition for each job, including the requirements
identified for each job:
v Add the candidate operating systems identified for each job.
v Add a file system requirement for remote access to the directory
//shared/reports/sales for the reporting jobs.
v Add the appropriate logical resources for the required database access.
.

22 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Figure 2. Resource requirements for the Inventory item update job

When all the jobs have been created, she checks the matching resources that are
found for the jobs she has defined. She finds that eight systems match the job
requirements for the reporting and data-mining jobs, which require access to the
transaction and management reports databases. The other jobs that require access
to the inventory, customer, and general ledger databases respectively, each have
two matching systems. However, all these systems are also included in the eight
systems found for the reporting and data-mining tasks.

Chapter 1. Understanding dynamic workload scheduling 23


Figure 3. Matching resources for the day-end jobs

She wonders whether there will be problems of load balancing between the eight
systems and decides to include some optimization instructions in all of the job
definitions.

24 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Figure 4. Optimization instructions for a job

The objective she decides on is to distribute jobs between available resources with
the aim of keeping CPU usage to a minimum. She thinks that this will provide a
more efficient distribution of resources than simply aiming for an equal number of
jobs on each available computer system.

She also considers that the update jobs are targeting a subset of the computers
available to the data-mining and reporting jobs and decides that the update jobs
should be assigned a higher priority, so that their resources are assigned before the
jobs that have wider range of options. She goes back to the job definitions of the
update jobs, and sets the scheduling priority to 100 (the highest possible).

The job definitions are now complete, and she uploads them to the Job Repository
in the Tivoli Workload Scheduler database. She is confident that she will see an
improvement in the performance during end-of-day processing, since all jobs have
more than one possible target and since she has tailored her definitions to promote
a balanced use of available resources.

Using Tivoli Workload Scheduler, she creates a job stream for the day-end jobs and
schedules it to be submitted on each business day. Most of the jobs do not have
dependencies and can run at the same time. However, the route information data
mining job requires data produced by the item information data mining job as
input. It must wait until the item information data mining job has successfully
completed and then it must run on the same computer system.

Chapter 1. Understanding dynamic workload scheduling 25


To achieve this objective without losing the benefits of dynamic allocation of
resources, she decides to define an affinity relationship between the two jobs.
Using Tivoli Workload Scheduler, she adds information to the route information
data mining job to identify its relationship to the item information data mining
task. When the job is submitted in the integrated environment, dynamic workload
broker recognizes the relationship and allocates the job to the resource where the
item information data mining task previously ran.

When the jobs in the job stream are submitted and dynamically allocated to
resources, she is able to track their progress and view job output from Tivoli
Workload Scheduler.

26 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Chapter 2. Using dynamic workload broker to run Tivoli
Workload Scheduler jobs
You can dramatically reduce the cost of ownership by minimizing customer effort,
reducing the complexity of the deployment, and using resources more efficiently
when you use dynamic scheduling in your Tivoli Workload Scheduler
environment.

Dynamic scheduling enhances the capabilities of Tivoli Workload Scheduler to


schedule, monitor and manage jobs. The Tivoli Workload Scheduler scheduling and
choreography features are used to manage the submission of jobs and the
resolution of dependencies, while the dynamic scheduling features are used to
identify resources where the jobs can run and to assign jobs to resources in a way
that makes efficient uses of the available computer resources.

Dynamic workload broker provides a series of improvements on your existing


Tivoli Workload Scheduler solution:
v Virtualization of the scheduling infrastructure by providing an abstraction layer
on the resource selection
v Workload balancing by routing jobs among a group of resources according to the
availability and activity levels of those resources
v Scheduling of IBM WebSphere Java™ 2 Enterprise Edition (J2EE) applications
v Automatic routing of jobs to the most appropriate resources based on job
requirements
v Enhanced flexibility in workload distribution and running
v Automatic routing of jobs for which submission failed to appropriate resources

The workload broker workstation acts as a bridge between the Tivoli Workload
Scheduler engine and dynamic workload broker and plays a key role since it
transfers the jobs submitted in Tivoli Workload Scheduler to dynamic workload
broker. To make this happen, when you define or schedule jobs on Tivoli Workload
Scheduler, you specify the name of the workload broker workstation as the
destination CPU and at submission time dynamic workload broker selects the best
matching workstation.

The workload broker workstation is automatically installed on the master domain


manager (and every backup master) when you select the dynamic scheduling
capability at Tivoli Workload Scheduler installation time. It contains a subset of the
standard agent features to enable you to manage the lifecycle of jobs even if they
are processed through dynamic workload broker.

When the dynamic scheduling capability is in place, you must decide which jobs
are to benefit from the dynamic resource allocation provided by dynamic workload
broker. New definitions must be created for these jobs. Each Tivoli Workload
Scheduler job must have a related dynamic workload broker job definition that
includes the rules for identifying matching resources. The Tivoli Workload
Scheduler job definition must contain information to identify the dynamic
workload broker job. A task is available on the Job Brokering Definition Console to
automatically convert existing Tivoli Workload Scheduler jobs to the correct format.

© Copyright IBM Corp. 2009, 2010 27


You can use the standard Tivoli Workload Scheduler procedures to submit and
monitor jobs that are to be allocated resources by dynamic workload broker to the
workload broker workstation. Jobs are then managed and monitored by dynamic
workload broker and submitted to the Tivoli Workload Scheduler agents.

Modifying your existing workload definitions for use with dynamic


workload broker
This section describes how to change your existing Tivoli Workload Scheduler jobs
for dynamic scheduling.

This section describes the following tasks:


1. “Planning and considerations”
2. “Using Tivoli Workload Scheduler variables in dynamic workload broker jobs”
on page 31
3. “Adapting Tivoli Workload Scheduler jobs for dynamic workload broker”
4. “Creating Tivoli Workload Scheduler jobs managed by dynamic workload
broker” on page 32
5. “Monitoring and cancelling jobs” on page 36

Planning and considerations


When integrating dynamic workload broker into your existing Tivoli Workload
Scheduler environment, you can decide which jobs are most suitable to dynamic
allocation of resources. Analyze the characteristics of the jobs in your environment
and consider job streams that might be improved when using resource
virtualization. The following job types might be potential candidates:
v Heavy computational tasks
v Jobs which require resource optimization and resource balancing
v Jobs strongly dependent on the availability of hardware resources, such as CPU
and RAM
v Jobs that must run in high-availability clusters
v Jobs that can benefit from automated recovery of failures
v Jobs requiring IBM WebSphere job scheduling
v Jobs billed to departments based on resource consumption

Adapting Tivoli Workload Scheduler jobs for dynamic


workload broker
Changes must be made to the job definitions you have identified as suitable for
dynamic allocation of resources. These changes enable you to move from a static
allocation of resources to a dynamic allocation using a logical resource. The logical
resource represents the requirements for running the job and is associated with the
computers that match the requirements. The procedure for adapting the jobs
includes the selection or definition of the logical resource.

Important: Although this is the established procedure for converting standard job
definitions into definitions for dynamic scheduling, there is a more advantageous
way of adapting static workload to dynamic scheduling requirements. It is based
on the use of JSDL job definition templates in the Job Brokering Definition Console
and is described in “Using JSDL job definition templates” on page 57. With the use

28 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


of templates, jobs can be adapted by simply changing their CPU to an appropriate
extended agent, without changing the job definition, and without requiring a
different JSDL definition for each job.

An import and export utility is provided for adapting jobs created with Tivoli
Workload Scheduler to the dynamic workload broker format. This utility also
allows you to insert in the resulting dynamic workload broker job a number of
Tivoli Workload Scheduler UNISON variables by selecting a checkbox during the
export operation.

When the import and export procedure is completed, the following job definitions
will exist:
v The original Tivoli Workload Scheduler job definition. This job cannot be
submitted to the workload broker workstation.
v A new Tivoli Workload Scheduler job definition that includes a task string that
identifies an associated dynamic workload broker job definition.
v A new dynamic workload broker job definition that includes the definitions for
dynamic allocation of resources.
When the new Tivoli Workload Scheduler job is submitted to the workload broker
workstation, the associated dynamic workload broker job is launched and dynamic
allocation is made based on its definition.

Note: You can make changes to the dynamic workload broker job definition, for
example, adding variables, but you must not change the name of the job.

To adapt Tivoli Workload Scheduler jobs to be managed dynamically by dynamic


workload broker, perform the following steps:
1. Export Tivoli Workload Scheduler job definitions to a file with the composer
extract command. For example, to export all jobs to a file named, my_jobs.txt,
enter the command as follows:
composer extract c:\my_jobs.txt jd=@#@
2. Save the resulting files on the workstation where the Job Brokering Definition
Console is installed.
3. Open the Job Brokering Definition Console.
4. In the Window menu, select Open Perspective → Job Definition Transition.
5. Click on the icon with the tray and incoming arrow in the upper right corner
of the window. The icon name is Import Tivoli Workload Scheduler job
definition and Tivoli Dynamic Workload Broker logical resources. The
import wizard is displayed. The following fields are available:
Job import file name
Specify the name of the Tivoli Workload Scheduler job you want to
import.
Job stream import file name
Optionally, specify the name of the Tivoli Workload Scheduler job
stream you want to import.
6. Click Finish. The job, and job stream (if specified), you selected are imported
in the Job Brokering Definition Console. The contents of the job are displayed
in the Tivoli Workload Scheduler Jobs table. You can double-click on each
element in the file to view the details on the element.
7. You can optionally filter on the Tivoli Workload Scheduler jobs being
displayed by clicking the Filter by job and workstation icon.

Chapter 2. Using dynamic workload broker to run Tivoli Workload Scheduler jobs 29
8. Decide on which logical resources the new job must run. You must associate
the job to a logical resource. If you have previously imported the same job, the
logical resources previously allocated to it are displayed.
9. Assign the job to the logical resource by dragging or copying the job to the
logical resource in the dynamic workload broker Logical Resources pane.
You can filter on the logical resources being displayed by clicking the Filter by
logical resources icon.
a. If none of the available logical resources fits your job requirements, you
can create a new logical resource by performing the following steps:
b. Click with the right mouse button on the dynamic workload broker
Logical Resources pane.
c. Select Add in the menu. The Add logical resource dialog is displayed.
d. Click OK. All logical resources created are assigned the TWSResource Type.
e. Associate the logical resource to a computer by dragging or copying the
logical resource to one or more computers in the dynamic workload
broker Computers pane. You can filter on the computers being displayed
by clicking the Filter by computer icon.
When the jobs are assigned to the logical resource, the Tivoli Workload
Scheduler workstation name is added as a prefix to the job name.
10. To export the jobs to Tivoli Workload Scheduler format, click on the icon with
the tray and outgoing arrow in the lower right corner of the window. The icon
name is Export To Tivoli Workload Scheduler And Tivoli Dynamic
Workload Broker. The following fields are available:
Default bridge
Specify the name of the workload broker workstation to which the
jobs are to be submitted.
Job export file name
Specify the file name to which the exported job is to be saved.
Job stream export file name
Specify the file name to which the exported job stream is to be saved.

The wizard creates the new Tivoli Workload Scheduler job definitions in the
directory you specify. It also creates the corresponding JSDL files which are
saved to the local job repository directory.
11. Optionally select Add TWS variables to insert a number of Tivoli Workload
Scheduler UNISON variables during the export operation. The variables are
then assigned a value when you submit the job in the Tivoli Workload
Scheduler environment.
12. You can now edit the JSDL files adding dynamic workload broker-specific
features.
13. Save the Tivoli Workload Scheduler job definitions to the Tivoli Workload
Scheduler server using the composer add command. For example, to save the
job definition exported to the file named, my_exported_jobs.txt, to the Tivoli
Workload Scheduler server, enter the command as follows:
composer add C:\my_exported_jobs.txt

When you schedule the new job streams on Tivoli Workload Scheduler, the job
streams will start the updated Tivoli Workload Scheduler jobs which internally
link the dynamic workload broker jobs.
14. Save the job definitions also in the dynamic workload broker Job Repository.

30 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Using Tivoli Workload Scheduler variables in dynamic
workload broker jobs
When importing jobs from Tivoli Workload Scheduler, you can add Tivoli
Workload Scheduler variables to obtain higher flexibility for your job.

The variables are assigned a value when you submit the job in Tivoli Workload
Scheduler. The supported Tivoli Workload Scheduler variables are as follows:
Table 17. Supported Tivoli Workload Scheduler variables in JSDL definitions.
Variables that can be inserted in the
Description
dynamic workload broker job definition
tws.job.fqname Fully qualified name of the job
(UNISON_JOB)
1 tws.job.interactive Job is interactive. Values can be true or
1 false.
tws.job.logon Credentials of the user who runs the job
(LOGIN)
tws.job.name Name of the submitted job
tws.job.priority Priority of the submitted job
tws.job.taskstring The task string of the submitted job
tws.job.workstation Name of the workstation on which the job is
defined
tws.jobstream.name Name of the job stream that includes the job
(UNISON_SCHED)
tws.jobstream.workstation Name of the workstation on which the job
stream that includes the job is defined
tws.master.workstation Name of the master domain manager
(UNISON_MASTER)
tws.plan.date Start date of the production plan
(UNISON_SCHED_DATE)
tws.plan.date.epoch Start date of the production plan, in epoch
format (UNISON_SCHED_EPOCH)
tws.plan.runnumber Run number of the production plan
(UNISON_RUN)

If you want to insert the variables when importing a job from Tivoli Workload
Scheduler, follow the instructions in “Adapting Tivoli Workload Scheduler jobs for
dynamic workload broker” on page 28.

If you want to create a dynamic workload broker job to be submitted from Tivoli
Workload Scheduler, you can add one or more of the variables listed in Table 17 in
the Variables field of the Overview pane as well as in the Script field of the
Application pane in the Job Brokering Definition Console.

If you plan to use the variables in a script, you also define the variables as
environment variables in the Environment Variables field in the Application pane.
Specify the Tivoli Workload Scheduler name of the variable as the variable value.
You can find the Tivoli Workload Scheduler name of the variable in the Variables
inserted in the dynamic workload broker job definition column.

Chapter 2. Using dynamic workload broker to run Tivoli Workload Scheduler jobs 31
You then create a Tivoli Workload Scheduler job which contains the name of the
job definition, as explained in “Creating Tivoli Workload Scheduler jobs managed
by dynamic workload broker.”

The following example illustrates a JSDL file with several of the supported Tivoli
Workload Scheduler variables defined:
...<jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod
/scheduling/1.0/jsdl" xmlns:jsdle="http://www.ibm.com/xmlns/prod/scheduling/1.0/
jsdle"
description="This jobs prints UNISON Variables received
from TWS in standard OutPut "
name="sampleUNISON_Variables">
<jsdl:annotation>This jobs prints UNISON Variables
received from TWS in
standard OutPut </jsdl:annotation>
<jsdl:variables>
<jsdl:stringVariable name="tws.jobstream.name">none</jsdl:stringVariable>
<jsdl:stringVariable name="tws.job.fqname">none</jsdl:stringVariable>
<jsdl:stringVariable name="tws.master.workstation">none</jsdl:stringVariable>
<jsdl:stringVariable name="tws.plan.runnumber">none</jsdl:stringVariable>
<jsdl:stringVariable name="tws.plan.date">none</jsdl:stringVariable>
<jsdl:stringVariable name="tws.plan.date.epoch">none</jsdl:stringVariable>
<jsdl:stringVariable name="tws.job.logon">none</jsdl:stringVariable>
</jsdl:variables>
<jsdl:application name="executable">
<jsdle:executable output="${tws.plan.runnumber}">
<jsdle:environment>
<jsdle:variable name="UNISON_SCHED">${tws.jobstream.name}
</jsdle:variable>
<jsdle:variable name="UNISON_JOB">${tws.job.fqname}
</jsdle:variable>
<jsdle:variable name="UNISON_MASTER">${tws.master.workstation}
</jsdle:variable>
<jsdle:variable name="UNISON_RUN">${tws.plan.runnumber}
</jsdle:variable>
<jsdle:variable name="UNISON_SCHED_DATE">${tws.plan.date}
</jsdle:variable>
<jsdle:variable name="UNISON_SCHED_EPOCH">${tws.plan.date.epoch}
</jsdle:variable>
<jsdle:variable name="LOGIN">${tws.job.logon}
</jsdle:variable>
</jsdle:environment>
...

Creating Tivoli Workload Scheduler jobs managed by dynamic


workload broker
To create a Tivoli Workload Scheduler job and have resources allocated
dynamically, perform the following steps:
1. Create a JSDL job definition in dynamic workload broker using the Job
Brokering Definition Console.
2. Create a job to be submitted in Tivoli Workload Scheduler. Define the job using
the standard Tivoli Workload Scheduler syntax and instructions, with the
following imperatives:
a. Define as target CPU the workstation where the workload broker
workstation is installed.
b. In the Task String section of the job, specify the name of the JSDL job
definition you created in the dynamic workload broker environment.
c. Set the task type as BROKER.

32 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


3. The Tivoli Workload Scheduler job can now be scheduled and when it is
submitted to the workload broker workstation, the dynamic workload broker
job is automatically launched and the resources are dynamically allocated.

Using variables in jobs


Dynamic workload broker supports the use of variables in jobs for additional
flexibility. You can assign values to the variables or leave them blank, so that you
can define the value when the job is submitted.

When you define jobs that will be processed through dynamic scheduling, you can
include variables that can be used at run time to valorize or override the variables
defined in the JSDL job definition.

You define the variables in the Task String section of the Tivoli Workload
Scheduler job, as described in the following example:
jobName -var var1Name=var1Value,...,varNName=varNValue

To define variables in the Tivoli Workload Scheduler job, perform the following
steps:
1. Create a JSDL job definition using the Job Brokering Definition Console.
2. Define the variables for the job. For example, you can define the memory
variable to specify the amount of memory required for the job to run.
3. Move to the Resources tab, Hardware Requirements section and type the
name of the variable in the Exact value field in the Physical Memory section.
When the job is submitted, the value assigned to the memory variable defines
the amount of physical memory.
4. Save the job definition in the Job Repository database.
5. Define a job in Tivoli Workload Scheduler. This job contains the standard
Tivoli Workload Scheduler syntax and instructions; in the Task String section
of the job, specify the name of the JSDL job definition. The name of the job
definition is specified in the jobDefinition element in the JSDL file.
In the Task String section of the job, you can also specify the parameters you
want to provide to the job while it runs using static text or variables. For
example, you can use the memory variable you previously defined.

Note: if you are using variables that you have not previously defined, you
must provide them with a value now.
6. Add the job to a job stream.
7. Submit or schedule the job using either the Tivoli Dynamic Workload Console
or conman.
8. After any existing dependencies are resolved, the master domain manager
submits the job to dynamic workload broker via the workload broker
workstation.
9. The workload broker workstation identifies the job definition to be submitted
based on the information on the Task String section of the job. It also creates
an alias which contains the association with the job. For more information on
the job alias syntax, see “Alias definition in Tivoli Workload Scheduler” on
page 34.
10. The job definition is submitted to dynamic workload broker with the value
specified for the memory variable.
11. Dynamic workload broker manages and monitors the whole job lifecycle.

Chapter 2. Using dynamic workload broker to run Tivoli Workload Scheduler jobs 33
12. Dynamic workload broker returns status information on the job to the
workload broker workstation, which communicates it to the Master Domain
Manager. The job status is mapped to the Tivoli Workload Scheduler status as
described in Table 18 on page 36.

Defining affinity relationships


In dynamic workload broker, you can define affinity relationships between two or
more jobs when you want them to run on the same resource. When submitting the
job from the Tivoli Workload Scheduler environment, you can define affinity that
will be resolved by dynamic workload broker by adding an affinity definition to
the Task String section of the Tivoli Workload Scheduler job in one of the
following ways:
v Identifying affine job with the dynamic workload broker job ID
v Identifying affine job with the dynamic workload broker job alias
v Identifying affine job with theTivoli Workload Scheduler job name
Identifying affine job with the dynamic workload broker job ID
jobName [-var varName=varValue,...,]-affinity jobid=jobid
Identifying affine job with the dynamic workload broker job alias
jobName [-var varName=varValue,...,]-affinity alias=alias

where
jobid Is the ID dynamic workload broker assigns when the job is submitted.
alias Is one of the following:
v The alias defined by the user at submission time for dynamic workload
broker jobs.
v The alias automatically generated by the workload broker workstation
when the job is submitted from Tivoli Workload Scheduler. For more
information on this alias, see “Alias definition in Tivoli Workload
Scheduler.”
Identifying affine job with theTivoli Workload Scheduler job name
The jobs must belong to the same job stream
jobName [-var varName=varValue,...,]-twsAffinity jobname=twsJobName

where
twsJobName
Is the name of the instance of the Tivoli Workload Scheduler job
with which you want to establish an affinity relationship.

Alias definition in Tivoli Workload Scheduler


When the Tivoli Workload Scheduler job is submitted to the workload broker
workstation, an alias is automatically generated. This alias uniquely identifies the
job in the Tivoli Workload Scheduler environment and is displayed in the Tivoli
Dynamic Workload Console.

The syntax of the alias is as follows:


cpuschedname#schedname.jobname.SCHEDID-schedid.ON-yymmdd.JNUM-nnnn

where:

34 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


cpuschedname
Is the job stream workstation.
schedname
Is the job stream name.
jobname
Is the job name.
SCHEDID
Is the ID that identifies the job stream instance.
ON Is the scheduled date of the job stream.
JNUM Is the job number created by Tivoli Workload Scheduler before submitting
the job. Identifies a specific instance of a job within a given production
date.

Scenario: A job exploiting the strengths of Tivoli Workload Scheduler


and dynamic workload broker
This scenario demonstrates how you can exploit both the scheduling features
provided by Tivoli Workload Scheduler and the resource optimization features
provided by dynamic workload broker.

Data is regularly collected from branches of a company and stored in the file
system of the computer where the branch collection job runs. The branch data
collected within a definable number of hours is used by another job to update a
central database. Both the branch collection and the centralized update jobs must
run on the same computer, which for the update procedure must have access to
the central database. The centralized update job must not start until the branch
collection job has completed successfully.

The following steps describe an example process for creating and submitting the
jobs to complete this scenario:
1. Create job definitions in dynamic workload broker using the Job Brokering
Definition Console as follows:
v BRANCH_COLLECT which must run on a Windows® platform.
v COLLECT_DATA which must run on a Windows platform and have access to the
central database.
All Windows candidate operating systems are selected for both jobs and a
logical resource identifying the database access requirement is added to the job
definition of COLLECT_DATA.
2. Save the job definitions to the Job Repository.
3. In Tivoli Workload Scheduler, create the two jobs, TWS_BRANCH_ COLLECT and
TWS_COLLECT_DATA, to be associated with the jobs you have just created. Both
jobs are added to the same job stream and the TWS_BRANCH_COLLECT job precedes
the TWS_COLLECT_DATA job. For both jobs, define the standard Workload
Scheduler syntax and instructions as follows:
v Define the workload broker workstation as target CPU for the jobs.
v In the Task String section of the jobs, specify the name of the associated job
definition you created in the dynamic workload broker environment. For
TWS_BRANCH_ COLLECT, the name is BRANCH_COLLECT and for TWS_COLLECT_DATA,
the name is COLLECT_DATA.

Chapter 2. Using dynamic workload broker to run Tivoli Workload Scheduler jobs 35
For the COLLECT_DATA job, the following additional information must be
included in the Task String section:
v To ensure that this job runs after the branch collection job in this job stream,
which will be submitted with the alias, branch_collect_20070607, on the same
computer, specify the following syntax in the Task String section:
COLLECT_DATA -affinity alias=branch_collect_20070607
v To define the time interval for which data is to be collected and updated in
the centralized database, add a variable to the Task String section as follows:
COLLECT_DATA -var data_collect_interval=12

The COLLECT_DATA job will now collect data produced in the last 12 hours.
4. Add both jobs to a job stream, using the standard procedure.
5. Submit or schedule the jobs in the Tivoli Workload Scheduler environment,
using the standard procedure.
6. When all dependencies are solved, the Master Domain Manager submits the
jobs to the workload broker workstation.
7. As each job is submitted to the workload broker workstation, it identifies the
job definition to be submitted based on the information in the Task String
section of the Workload Scheduler job and submits it. It also creates an alias
which contains the association with the job in the Tivoli Workload Scheduler
environment.
When the COLLECT_DATA job is submitted, it identifies the affinity with the
BRANCH_COLLECT job and ensures that the job runs on the same computer.

dynamic workload broker returns status information on the job to the workload
broker workstation, which communicates it to the Master Domain Manager. The
job status is mapped to the Tivoli Workload Scheduler status as described in
Table 18.

Monitoring and cancelling jobs


You can use the Tivoli Dynamic Workload Console or the conman command line
to monitor the status of submitted jobs, retrieve the job output, and cancel jobs if
necessary, as you normally do in Tivoli Workload Scheduler. You can also use the
Tivoli Dynamic Workload Console to view their status since it provides more detail
on jobs processed through dynamic workload broker.

Job statuses in dynamic workload broker correspond to the following statuses in


Tivoli Workload Scheduler:
Table 18. Status mapping between dynamic workload broker and Tivoli Workload Scheduler
Dynamic workload broker job status Tivoli Workload Scheduler job status

1. Run failed 1. ABEND


2. Unable to start 2. FAILED
3. Resource allocation failed 3. FAILED
4. Unknown 4. ABEND

1. Submitted 1. INTRO+
2. Submitted to Agent 2. WAIT
3. Resource Allocation Received 3. WAIT
4. Waiting for Reallocation 4. WAIT
5. Waiting for Resources 5. WAIT

36 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Table 18. Status mapping between dynamic workload broker and Tivoli Workload Scheduler (continued)
Dynamic workload broker job status Tivoli Workload Scheduler job status

1. Running 1. EXEC+

1. Completed Successfully 1. SUCC

1. Canceled 1. ABEND
2. Cancel Pending 2. The status is updated when the job reaches the
3. Cancel Allocation Canceled state in dynamic workload broker
3. The status is updated when the job reaches the
Canceled state in dynamic workload broker

You can view the job output by using both the Tivoli Dynamic Workload Console
or the conman command-line.

The following example displays the output of the TWS_COLLECT_DATA job,


submitted from Tivoli Workload Scheduler to the workload broker workstation.
%sj ITDWB_SA#JOBS.TWS_COLLECT_DATA;stdlist

==========================================================
= JOB : lab134114#TWS_COLLECT_DATA
= USER : mdm_821
= JCLFILE : COLLECT_DATA -var data_collect_interval=12
-twsaffinity jobname=branch_collect
= Job Number: 226589429
= Wed Oct 25 00:31:03 GMT+08:00 2006
==========================================================
THIS IS THE OUTPUT OF THE JOB
==========================================================
= Exit Status : 0
= System Time (Seconds) : 30 Elapsed Time (Minutes) : 0
= User Time (Seconds) : 30
= Wed Oct 25 00:31:33 GMT+08:00 2006
==========================================================

The keywords in the file output are as follows:


JOB Is the host name of the Tivoli Workload Scheduler agent to which the job
has been submitted and the job name.
USER Is the Tivoli Workload Scheduler user who submitted the job to the
workload broker workstation. When a scheduled job is submitted, the user
name is retrieved from the STREAMLOGON keyword specified in the job
definition. When an ad-hoc job is submitted, the user name corresponds to
the user who submitted the job.
JCLFILE
Is the job name.
Job Number
Is the job number.
Exit Status
Is the status of the job when completed.
System Time
Is the time the kernel system spent for the job.
User Time
Is the time the system user spent for the job.

Chapter 2. Using dynamic workload broker to run Tivoli Workload Scheduler jobs 37
Note: The job output is not displayed if the job belongs to a carry forward job
stream. For more information on carry forward job streams, refer to IBM Tivoli
Workload Scheduler User's Guide and Reference.

You can also kill the job after submitting it. Killing a job in Tivoli Workload
Scheduler performs the same operations as issuing the cancel command in
dynamic workload broker.

38 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Chapter 3. Identifying the resources for jobs
To schedule jobs, dynamic workload broker first scans the computers in the
environment to retrieve hardware and operating system information from the
agent computers. You can also optionally create logical resources that represent
characteristics of the computers that are not gathered by the scan, such as software
licenses or installed applications, to further identify resources available in the
environment.

About this task

After the Tivoli Workload Scheduler agent is installed, an automatic scan is


performed on the discovered computers where the agent is installed. The scan
returns hardware and operating system information which is stored in the
Resource Repository.

The hardware and operating system information returned by the scan is considered
a physical resource. Physical resources collected from the agent computers include
the following:

Types of physical resources Examples


Computer system Computer system name, model, number of
processors, CPU speed
Operating system Operating system type and version, virtual
memory, physical memory, swap space
Network system IP address, network card, host name
File system File system storage capacity

The automatic discovery process of gathering physical resource information is


capable of identifying available computers with the resources required for jobs to
run on. The scan is scheduled and configurable. You can configure the scan from
the ResourceAdvisorAgentConfig.properties file on the master domain manager
and from the JobManager.ini file on the agents. Ensure the scan runs at regular
times to update any changes to resources. Refer to the IBM Tivoli Workload
Scheduler Administration Guide for more information about this configuration file.

When the physical resources gathered by the scan do not supply enough
information to accurately address specific job requirements, you can define logical
resources or resource groups using the Tivoli Dynamic Workload Console. The
Tivoli Dynamic Workload Console gives you the capability to set up additional
logical resources and link them to computers where the resources are available.
Logical resources help identify resources required by jobs to make allocation more
accurate. Logical resources can also be used when expressing a consumable
quantity of a resource. For example, you might use a logical resource to identify
specific applications, and you might also use them to define a limited number of
software licenses available. When a job is submitted, the job definition includes the
physical and logical resource requirements, and with this information dynamic
workload broker finds the most suitable computer.

You can also use the Tivoli Dynamic Workload Console to define a resource group.
A resource group is a combination of physical and logical resources defined to

© Copyright IBM Corp. 2009, 2010 39


accurately match and allocate resources to job requirements when the job is
submitted. After creating logical resources and resource groups, you can
subsequently edit them using the Tivoli Dynamic Workload Console. If a computer,
logical resource, or resource group becomes unavailable or you need to make it
unavailable to perform maintenance tasks, for example, you can set the status to
offline. You can subsequently set the status online using the Tivoli Dynamic
Workload Console.

The following are tasks for configuring resources:


v “Creating logical resources” on page 42
v “Creating resource groups” on page 44

Checking physical resources on computers


You can browse and display the physical resources discovered by the agent scan
on the computers in your environment.

Before you begin

The automatically scheduled scan that runs on computers when the Tivoli
Workload Scheduler agent is installed returns hardware and operating system
information from the agent computers to the Resource Repository. You can use the
Tivoli Dynamic Workload Console to view the information collected by the agent,
in addition to the other information about the computers. The following
information can be accessed:
v Operating system information
v Computer availability
v Processor information
v Machine information
v Free memory, free virtual memory, and free swap space
v System resources allocated to jobs
v A history of job instances that ran on the computers and are currently running

About this task

To view information about the physical resources available on the computers in


your environment, do the following:

Procedure
1. In the console navigation tree, expand Tracking and click Computers.
2. Specify the search criteria for the computers you want to find.
3. Click Search. The computers that meet the search criteria are displayed in the
Computer Search Results page.
4. To view the physical resources for a computer, select the display name link for
the computer. The Computer details page displays the physical resources on
the computer.

What to do next

Figure 5 on page 42 shows the Computer Search Results page. From this view you
can perform the following tasks:
v Set computers offline so that they cannot be allocated to run jobs.

40 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


v Set offline computers back online so that they can be allocated to run jobs.
v Delete computers so that they are no longer visible when you search for
computers. When you delete a computer, it is temporarily removed from the
database for a period of time defined in the
ResourceAdvisorAgentConfig.properties file. After the deletion, the Tivoli
Workload Scheduler agent remains installed and running. Any jobs currently
allocated and running on the computer complete. To permanently delete a
computer, you must uninstall the Tivoli Workload Scheduler agent.
v Refresh the view of the computer search results to see updated information
about computers.
v View the number of jobs currently allocated on a given computer in the Active
Jobs column. For each computer this column shows the number of jobs that
have selected the computer as a target system, as well as the number of jobs that
are currently allocating the computer as a related resource. In the specific case
you defined a computer system as a type for a related resource required to run a
job (in the JSDL definition of the job), when the job is allocated it is displayed
twice in Active Jobs as follows:
– If the same computer is selected both as a target system and as a related
resource, the column shows 2 jobs for that computer, even though there is
only one job running.
– If different computers are selected for the target system and the related
resource, the column shows the same job twice (once for each computer).
v View additional information about a computer.
To perform these tasks, do the following:
1. Select a computer in the Computer Search Results table.
2. Select one of the following operations from the Actions menu:
v Set as online
v Set as offline
v Delete
v Refresh
3. Click Go to perform the operation.
You can display details on computers by clicking the computer name link in the
Computer Search Results table.

Chapter 3. Identifying the resources for jobs 41


Figure 5. Computer Search Results page

In general, you can click links for job names, job instance names, and computers
from the Tivoli Dynamic Workload Console to display more details about them.

Creating logical resources


Using the Tivoli Dynamic Workload Console, you can define logical resources and
resource groups for workstations with properties that are not discovered with a
system scan. You create a logical resource specifying the characteristics of the
resource that are required to run jobs.

About this task

To create a logical resource, perform the following steps:

Procedure
1. In the console navigation tree, expand Scheduling Environment and click
Define a New Logical Resource. The Define a New Logical Resource wizard
starts. The wizard helps you create a new resource and add it to computers in
your environment.
2. In the General Properties page, define the general properties for the logical
resource:
a. In the Name field, type the name to be assigned to the logical resource. This
field is required. The name must start with an alphabetical character, and
can contain underscore symbols ( _ ), minus symbols (-), and periods (.).
Spaces, special characters, accented characters are not supported.
b. In the Type field, type a meaningful name for the logical resource type. For
example, if the logical resource describes DB2® applications, you might call
the resource DB2. The name must start with an alphabetical character, and

42 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


can contain underscore symbols ( _ ), minus symbols (-), and periods (.).
Spaces, special characters, accented characters are not supported.
c. In the Quantity field, specify a value that represents the availability of the
logical resource. For example, if the resource consists in a license server, you
can specify the number of licenses available on the server for a product.
This field is optional.
d. Select the Set as Offline check box to mark the resource as not available.
You can subsequently change the resource status by expanding Scheduling
Environment in the left pane and selecting Logical Resources. You can then
search for a resource and modify the status.
e. Click the Next button to proceed.
3. In the Computer Search Criteria page, specify the criteria for searching the
computers to be added to the logical resource. In this page, you can either
perform a search on all computers available in the dynamic workload broker
environment or you can search for specific computers. To search on all
available computers, leave all fields blank. As an alternative, you can specify
one or more of the search criteria listed below. The search criteria are
cumulative; each additional information you specify further refines the search:
v In the Host Name field, specify the host name of a computer. Wildcards are
supported. The search is performed on computers with the specified host
name or section of the host name. For example, if you enter test* in the Host
name field, the test1 and testing host names are returned.
v In the Logical resources already on the computer area, specify the name and
type of logical resources already present on the computer, if any. In the
Name field, specify the logical resource name and in the Type field specify
the logical resource type. Wildcards are supported.
v In the Availability area, specify whether the computer is:
Available
The computer is available and can be assigned jobs.
Unavailable
The computer is not available. The network might be down or the
computer might be switched off.
v In the Status area, define the status of the specified computer.
Online
The computer is online.
Offline
The computer is offline. The administrator might have set the
computer offline for maintenance purposes.
v In the Hardware Characteristics area, specify the number of processors
available on the computer:
Single processor
The computer contains one processor.
Double processor
The computer contains two processors.
Multi processor
The computer contains three or more processors.
v In the Operating System area, specify the operating system installed on the
computers for which you want to search. The search is performed only for
computers with the selected operating systems. Available operating systems
are:

Chapter 3. Identifying the resources for jobs 43


– Windows
– Linux
– AIX
– Sun Solaris
– HP-UX
The results of the search are displayed in the Computer Search Results pages.
4. In the Computer Search Results page, you specify to which computers you
want to add the logical resource you are creating. Your selections are displayed
in the Summary page.
5. In the Summary page, you can optionally remove the selected computer from
the logical resource you are defining. Click Finish to save the logical resource.

Results

The logical resource has been created and can be accessed using the Scheduling
Environment → Logical Resources task. You can perform the following operations
using this task:
v Set the online or offline status of the logical resource.
v Delete the logical resource.
v Edit the logical resource specifications, including the computers where the
logical resource is located, the online or offline status of the computers, and the
logical resource name, unless the logical resource was imported from the
Configuration Management Database. A Configuration Management Database
logical resource can be identified in the table of logical resources by the value
CCMDB in the Owner column.

Creating resource groups


Using the Tivoli Dynamic Workload Console, you can create resource groups to
group computers, logical resources, or both. A resource group represents a logical
association between computers, logical resources, or both with similar hardware or
software characteristics. It is a combination of physical and logical resources to
accurately match and allocate resources to job requirements when the job is
submitted.

About this task

To create a resource group, perform the following steps:

Procedure
1. In the console navigation tree, expand Scheduling Environment and click
Define New Resource Group. The Resource Group wizard starts. The wizard
helps you create a new resource group.
2. In the Group Type Selection page, specify a name, the status, and a type for
the resource group:
a. In the Name field, type the name to be assigned to the resource group. The
name must start with an alphabetical character, and can contain underscore
symbols ( _ ), minus symbols (-), and periods (.). Spaces, special characters,
and accented characters are not supported. This field is required.
b. Select the Set as Offline check box to mark the resource group as not
available. You can subsequently change the resource group status by

44 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


expanding Scheduling Environment in the left pane and selecting Resource
Groups. You can then search for a resource group and modify the status.
c. In the Select items to be grouped area, select the elements the group
consists of. Supported values are computers, logical resources or both. This
field is required.
d. Click the Next button to proceed.
3. In the Computer Search Criteria page, specify the criteria for searching
available computers to be added to the resource group. In this page, you can
either perform a search on all computers available in the dynamic workload
broker environment or you can search for specific computers. To search on all
available computers, leave all fields blank. As an alternative, you can specify
one or more of the search criteria listed below. The search criteria are
cumulative; each additional information you specify further refines the search:
v In the Host Name field, specify the host name of a computer. Wildcards are
supported. The search is performed on computers with the specified host
name or section of the host name. For example, if you enter test* in the Host
name field, the test1 and testing host names are returned.
v In the Logical resources already on the computer area, specify the name and
type of logical resources already present on the computer, if any. In the
Name field, specify the logical resource name and in the Type field specify
the logical resource type. The name and type must start with an alphabetical
character, and can contain underscore symbols ( _ ), minus symbols (-), or
periods (.). Spaces, special characters, and accented characters are not
supported.
v In the Availability area, specify whether the computer is:
Available
The computer is available to be allocated.
Unavailable
The computer is not available. The network might be down or the
computer might be switched off.
v In the Status area, define the status of the specified computer.
Online
The computer is online.
Offline
The computer is offline. The administrator might have set the
computer offline for maintenance purposes.
v In the Hardware Characteristics area, specify the number of processors
available on the computer:
Single processor
The computer contains one processor.
Double processor
The computer contains two processors.
Multi processor
The computer contains three or more processors.
v In the Operating System area, specify the operating system installed on the
computers for which you want to search. The search is performed only for
computers with the selected operating systems. Available operating systems
are:
– Windows
– Linux

Chapter 3. Identifying the resources for jobs 45


– AIX
– Sun Solaris
– HP-UX
Click Next to perform the search based on the criteria specified. The results of
the search are displayed in the Computer Search Result page.
4. In the Computer Search Result page, you specify to which computers you
want to add the group you are creating. Click Next.
5. If the resource group you are defining includes a logical resource, then the
Logical Resource Search Criteria page prompts you to specify the following
search criteria:
a. The name of the logical resource.
b. The type of logical resource.
Click Next to display the Logical Resources Search Results page.
6. Select the logical resource to add to the resource group you are defining and
click Next to display the Summary page.
7. In the Summary page, you can optionally remove any computer or logical
resource that you included in the resource group. Click Finish to save the
resource group.

Results

The resource group has been created and can be accessed using the Scheduling
Environment → Resource Groups task. You can perform the following operations
using this task:
v Set the online or offline status of the resource group.
v Delete the resource group.
v Edit the resource group specifications, including adding and removing
computers and logical resources from the group, changing their online or offline
status, and changing the resource group name.

46 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Chapter 4. Writing JSDL definitions with the Job Brokering
Definition Console
The Job Brokering Definition Console provides an easy-to-use graphical interface
that helps you create and edit JSDL job definitions for use with dynamic workload
broker.

The Job Brokering Definition Console graphical interface helps you create and edit
job definitions based on the Job Submission Definition Language (JSDL) schema.
Each text field in the Job Brokering Definition Console corresponds to an element
or attribute in the JSDL file and vice versa.

The Job Brokering Definition Console simplifies the task of creating a JSDL file by
hiding the complexity of the file itself and validating the file structure against the
JSDL schema. Information defined in the Job Brokering Definition Console is
automatically converted to the corresponding element or attribute in the JSDL file.

You can save a JSDL file locally or upload it as a job definition in the Job
Repository where it becomes available for submission. When you save the file in
the Job Brokering Definition Console, the JSDL file is checked against an .xsd file
provided with the product installation which contains the syntax rules. A message
is displayed if a syntax error is encountered in the JSDL file, allowing you to
correct the error.

The Job Submission Description Language (JSDL) is an XML-based language used


for specifying the characteristics and requirements of a job, as well as instructions
on how to manage and run it. These include the following:
v Job identification information
v Program running information
v Resource requirements
v Scheduling and running requirements
v Resource quantity to be allocated or required
v Logical allocation of the resource quantity

Selecting target types

When creating a JSDL file, you can choose between the following resource types as
targets for your job:
Resources
A resource is a computer system. You can use this resource type to define a
basic requirement for your job.
Related resources
A related resource is a set of resource types. You can use this resource type
to define a basic requirement for your job. A related resource includes the
following resource types:
v A set of hardware and software properties of a computer such as
operating system, file system and network system.

© Copyright IBM Corp. 2009, 2010 47


v Logical resources and logical entities that can be associated to one or
more computers to represent applications, groups, licenses, servers and
so on.
Related resources have two main functions:
v You can specify related resources as an additional requirement adding to
the resource requirement. In this case, you must create a relationship
between the resource and the related resource.
v You can use the related resource to indicate that the presence of a certain
resource in your environment is a co-requisite for running the job. In
this case, you must not create a relationship between the resource and
the related resource. A related resource having no relation to a resource
is a global resource. For example, if you want to move a file from
resource A to resource B, resource B is a co-requisite for running the job
which moves the file. Computers can only be defined as global
resources.

Selecting resource types


Dynamic workload broker manages the resource types listed in Table 19. For each
resource type, you can specify requirements on the properties listed in the
Available properties column. Table 19 also lists consumable properties and
properties that can be optimized. Consumable properties can be allocated
exclusively to the job while it runs using the allocation mechanism. Properties that
can be optimized can be used to provide a more effective load balancing on the
resource property.
Table 19. Resource types and properties
Resource Type Available properties Is consumable Can be optimized Supports wildcards
ComputerSystem CPUUtilization No Yes No
HostName No No Yes
Manufacturer No No Yes
Model No No Yes
NumOfProcessors Yes Yes No
ProcessingSpeed No Yes No
ProcessorType No No No
LogicalResource DisplayName No No Yes
SubType No No Yes
Quantity Yes Yes No
OperatingSystem DisplayName No No Yes
FreePhysicalMemory No Yes No
FreeSwapSpace No Yes No
FreeVirtualMemory No Yes No
OperatingSystemType No No No
OperatingSystem No No No
Version
TotalPhysicalMemory Yes Yes No
TotalSwapSpace Yes Yes No
TotalVirtualMemory Yes Yes No

48 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Table 19. Resource types and properties (continued)
Resource Type Available properties Is consumable Can be optimized Supports wildcards
FileSystem DisplayName No No Yes
FileSystemRoot No No Yes
FileSystemType No No No
FreeStorageCapacity No Yes No
TotalStorageCapacity Yes Yes No
NetworkSystem NetworkAddress No No No
NetworkSystem No No Yes
HostName

When you define the requirements for a job definition, you can define the amount
of a consumable property which will be allocated to the job. When a resource
property is allocated to a job, the amount you specify is logically reserved for the
job. If another job is submitted which allocates a value greater than the remaining
capacity of the same consumable property, this job cannot run on the same
resource as the previous job because the required property is already reserved. If
no property allocation is specified in the job definition, the job can run on the same
resource as the previous job because the allocation mechanism applies only if both
jobs allocate the same property.

You can use the allocation mechanism to limit concurrent use of the same quantity
by several jobs and improve system performance.

To allocate a property for a job, use the allocation element in the JSDL file or the
Software Requirements and Hardware Requirements tabs in the Job Brokering
Definition Console.

This allocation type applies to computer systems. To allocate a property for a


resource other than a computer system, you define the resource whose property
you want to allocate in the Related resource pane and define the allocation setting
for one or more of its properties. You then define a relationship between the
resource and the related resource you created. In this way you define the related
resource and the allocated property as a requirement for the job to run.

Job definitions
This topic provides an overview of the possible content of job definitions and
describes how the different types of job definition content are added using the Job
Brokering Definition Console.

A job definition contains all the information required to determine the computer
system or systems on which a job could run, any scheduling and job balancing
rules that are to be applied when allocating resources, as well as the information
required to identify and run the application. It is defined using the Job Submission
Description Language (JSDL).

JSDL is an XML-based language used for specifying the characteristics and


requirements of a job, as well as instructions on how to manage and run the jobs.
A JSDL file can include the following types of information

Chapter 4. Writing JSDL definitions with the Job Brokering Definition Console 49
Basic job information
Includes the job name, any job categories to which you want to assign it,
and any variables that are used in the job.
Variables can be used in several ways in a job definition. For example:
v A set of variables can describe a command and its arguments. These can
be added to program running information and within the script of the
job.
v Variables can also be used to identify resources, for example, a target
host.
The default value assigned to the variable in the job definition is used
when the job is run, unless it is overridden at submission time. See “Using
Tivoli Workload Scheduler variables in dynamic workload broker jobs” on
page 31 and “Using variables in job definitions” on page 57.
Program running information
Identifies the script or executable to be run and, if necessary, standard
input, output, and error files and the working directory. If the job needs to
provide credentials these can also be specified.
You can define the required credentials to run a job if the credentials are
different from those under which the Tivoli Workload Scheduler agent
runs.
On Windows targets, jobs with no specified credentials, run under the user
account specified during the Tivoli Workload Scheduler agent installation,
unless the agent runs under the Local System account. In this case, any job
submitted to the agent runs under the default administrator's account.
On UNIX® targets, jobs with no specified credentials, run under root.
Required resource specifications
Enables dynamic workload broker to identify the computer systems on
which the job can run based on hardware and software requirements.
Related requirements
Allow you to specify required relationships between resources and
co-requisite resources for a job.
Allocation
Resource quantity to be allocated or required.
Optimization and load-balancing policies.
The following load balancing policies are available:
Balance load between resources by number of jobs running
Jobs are assigned to targets based on the number of jobs currently
running on each target. The objective is to ensure that each
resource runs the same number of jobs during the same time
interval. This policy is the default. It is suitable for situations
where many similar jobs, which consume similar quantities of
system resources, are to be run on a set of resources
Balance load between resources by optimization objective
You define an objective by selecting a resource type and related
resource property and specifying the objective to maximize or
minimize the property. For example, you could balance load with
the aim of keeping the amount of free physical memory available
on operating system resources as high as possible. The objective
would be set to maximize free physical memory and when jobs

50 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


with this objective are submitted, they are allocated to available
resources so that more jobs go to the resources that currently have
the greatest amount of free physical memory.
Select best resource by optimization objective
You define the optimization objective in exactly the same way as
described for the Balance load between resources by optimization
objective. However, when a job with this policy is submitted, it
would always be assigned to the resource that best matched the
objective. For example, if the objective is to maximize free physical
memory, the job would run on the resource that had the highest
amount of free physical memory at submission time.
Enterprise Workload Manager
If you have Enterprise Workload Manager installed, you can define
jobs with an optimization policy to use the load-balancing
capabilities of this product.

In the JSDL schema, the Optimization page corresponds to the


optimization element.
Scheduling and running requirements.
Allows you to define a priority, the time a job can wait for resources before
failing, and recovery actions in the event of a failure.
The maximum priority is 100 and priority settings between 90 and 100
should only be used for critical jobs. Jobs with these priorities are always
allocated resources ahead of other waiting jobs regardless of how long the
other jobs have been waiting. At lower priorities than 90, jobs are allocated
resources based on the priority setting and the age of the job. As time
passes, jobs with a low priority setting increase their priority so that they
eventually are allocated resources even if jobs with higher initial priorities
are waiting.

The Job Brokering Definition Console graphical interface allows you to create and
edit job definitions based on the JSDL schema. Fields in the Job Brokering
Definition Console correspond to elements in the JSDL schema. When creating a
job definition using the Job Brokering Definition Console, you can view the job
definition structure in the Outline pane.

Chapter 4. Writing JSDL definitions with the Job Brokering Definition Console 51
Figure 6. Job Brokering Definition Console main page

The JSDL schema offers great flexibility in defining jobs and their requirements. A
job can have a very open definition, with few defined requirements, allowing it to
run on a wide range of resources and to follow default rules for load balancing.
Other jobs could have a much more detailed set of hardware and software
requirements, as well as specific resource allocations and a load balancing policy.
Using the graphical interface simplifies the task of creating JSDL files and
eliminates many of the risks of error that occur when the files are edited manually.
The different elements that make up a job definition are available, in many cases
with a set of fixed values from which you can choose. Information defined in the
Job Brokering Definition Console is validated, ensuring that any values you have
entered are correct and consistent with each other.

In addition, the Job Brokering Definition Console also includes content assistance
that provides server-side values for several fields on the interface, for example,
candidate host names and logical resources, to name a few. Fields with content
assistance are identified by a light-bulb icon next to the field. Position your mouse
over the light-bulb and press Ctrl + Space to display a list of possible values.
Server-side values are populated using the server cache for the currently active
server connection. Server data is cached automatically when the initial connection
to a server is made or each time the server connection is changed. You can refresh
the cache at any time, for example, if you have defined a new resource
requirement on the server, by selecting Server → Refresh Server Data Cache.

When you save the file in the Job Brokering Definition Console, the JSDL file is
checked against an .xsd file provided with the product installation which contains
the syntax rules. A message is displayed if a syntax error is encountered in the

52 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


JSDL file, allowing you to correct the error. You can save the JSDL files locally or
upload them as job definitions in the Job Repository where they become available
for submission.

Resources in the job definition


This topic provides an overview of how resources and their properties are used in
the job definition to identify possible targets, to reserve allocations of consumable
resources, and to optimize load balancing between available resources.

An understanding of physical and logical resources and their properties is the key
to creating a job definition that accurately targets suitable resources for running the
job, determines the resource allocation requirement, and contributes to balancing
the load between available resources. Each resource has one or more properties
associated with it. Properties can have the following characteristics:
Is consumable
Properties of resources that are consumable have finite amount associated
with them which can be consumed by the jobs that are allocated to the
resource. For example, a computer system has a finite number of
processors.
Can be optimized
Some properties can be used to define optimization objectives, which
determine how load is to be balanced when jobs are allocated to a group of
resources. For example, you could choose to allocate a job to the matching
resource that has the lowest CPU usage.
Supports wildcards
Some properties can be specified in the job definition using wildcards. For
example, a requirement for a particular series of computer models could be
defined by specifying the model using wildcards.

Table 20 shows the different resource types that can be included in a job definition
and their available properties.
Table 20. Resource types and properties
Resource Type Available properties Is consumable Can be optimized Supports wildcards
ComputerSystem CPUUtilization No Yes No
HostName No No Yes
Manufacturer No No Yes
Model No No Yes
NumOfProcessors Yes Yes No
ProcessingSpeed No Yes No
ProcessorType No No No
LogicalResource DisplayName No No Yes
SubType No No Yes
Quantity Yes Yes No

Chapter 4. Writing JSDL definitions with the Job Brokering Definition Console 53
Table 20. Resource types and properties (continued)
Resource Type Available properties Is consumable Can be optimized Supports wildcards
OperatingSystem DisplayName No No Yes
FreePhysicalMemory No Yes No
FreeSwapSpace No Yes No
FreeVirtualMemory No Yes No
OperatingSystemType No No No
OperatingSystem No No No
Version
TotalPhysicalMemory Yes Yes No
TotalSwapSpace Yes Yes No
TotalVirtualMemory Yes Yes No
FileSystem DisplayName No No Yes
FileSystemRoot No No Yes
FileSystemType No No No
FreeStorageCapacity No Yes No
TotalStorageCapacity Yes Yes No
NetworkSystem NetworkAddress No No No
NetworkSystem No No Yes
HostName

Resource properties can be used in the job definition in the following ways:
Identifying targets for the job
On the Resources page of the Job Brokering Definition Console, you can
supply information about the resources required for the job. Using this
information, dynamic workload broker can identify the computer systems
on which the job could run. In addition to the basic hardware and software
requirements, you can use the Advanced Requirements tab to include
requirements for specific resource properties. For example, you can add a
requirement for a specific processor type or specify a required range of
processor speeds. In the JSDL schema, the Resources page corresponds to
the resources element.
When you define a resource requirement, the underlying relationship
between the required resource and the computer system which contains
the resource is automatically created by the Job Brokering Definition
Console to facilitate the usage of the product.
Resource property requirements to be used when identifying targets for job
can also be specified on the Related Resources page. A related resource
includes the following resource types:
v A set of hardware and software properties of a computer such as
operating system, file system, and network system.
v Logical resources, which are a flexible means of providing information
about your environment in addition to the information collected by the
hardware scan. For example, you could create logical resources to
represent applications, groups, licenses, or database access. A logical
resource can be linked to one or more specified computers or it can be a
freestanding global resource, available to all computers.

54 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Related resources have two main functions:
To specify additional requirements, making the matching criteria for
possible targets more precise
Targets can only match if they either contain or are associated with
the specified resource. In addition to defining the related resource
in the job definition, you must also define its relationship to the
target resource and specify the relationship type as contains or
associates with. Related resource that define hardware and
software properties always have a contains relationship while
logical resources often have an associates with relationship. For
example, if a related requirement for a logical resource that
represents a node-locked license is included, the target system
must be one of those that is associated with this resource, and
therefore a target where the license is available.
To specify global resources that must be available for the job to run
These related resources are not related to the target resource and
have no role in finding matching resources for the job to run on.
The resource must be available to the job at submission time. For
example, if a license required to run the software used by the job is
of a type that is not assigned to any computer, a logical resource
could be created to identify it and to track the number of licenses
that exist and that are in use. No computers are associated with
this logical resource and so it is referred to as a global resource,
available to all computers. The job definition includes a related
resource identifying the floating license logical resource and the
number of licenses required. Before the job can run, it must be
possible to meet this requirement.

In the JSDL schema, the Related Resources page corresponds to the


relatedResources element.
When the resource requirements for the job are defined, logical rules are
applied to determine whether the requirements are alternatives to each
other (OR) or whether they are inclusive (AND). In general, the different
types of requirements have an AND relationship, for example, if you
specify an operating system type, CPU architecture, and a value for
minimum physical memory, the target resource for the job must meet all of
these requirements.
Within the following requirement types, you can specify alternatives that
have an OR relationship:
v Candidate hosts
v Candidate CPU architectures
v Candidate operating systems
If several entries are added for any of these requirement types, they are
considered as alternatives. For example, if Linux, AIX, and HP-UX are
specified as candidate operating systems, the target resource for the job
must have one of these operating system types.
Within the following requirement types, all requirements specified must be
met by the target resource for the job.
v Logical resources
v File systems

Chapter 4. Writing JSDL definitions with the Job Brokering Definition Console 55
For example, if you add Local Disk and CD ROM to the File system
requirements, the target resource for the job must have both a local disk
and a CD ROM.
Reserving resources
When defining the requirements for a job definition, you can define the
amount of a consumable property which will be allocated to the job. When
a resource property is allocated to a job, the amount you specify is
logically reserved for the job. If another job is submitted which allocates a
value greater than the remaining capacity of the same consumable
property, this job cannot run on the same resource as the previous job
because the required property is already reserved. If no property allocation
is specified in the job definition, the job can run on the same resource as
the previous job because the allocation mechanism applies only if both jobs
allocate the same property.
You can use the allocation mechanism to limit concurrent use of the same
quantity by several jobs and improve system performance.
On theJob Brokering Definition Console, you can allocate a specified
quantity of a consumable property. You can use the allocation pane from
the Advanced Requirements tab of the Resources page or you can define
a required resource and property in the Related resource page and specify
the amount of the property to be allocated. From the Advanced
Requirements tab on the Resources page, you can only allocate
consumable properties of computer system resources.
Defining load-balancing policies
You can use the Optimization page in the Job Brokering Definition
Console to define custom rules for load-balancing to be applied when the
job is submitted. The default method of load-balancing is to aim to
equalize the number of jobs running on each resource.
Dynamic workload broker provides two types of optimization policy types
that use rules based on resource properties:
v Balance load between resources by optimization objective
v Select best resource by optimization objective
For both policies, you define an objective to distribute jobs minimizing or
maximizing the property of a computer system, a file system, a logical
resource, or an operating system. For example, you could balance loads
with the aim of keeping the free physical memory available on operating
system resources as high as possible.
When the Balance load between resources by optimization objective
policy is used, jobs are distributed between matching resources based on a
statistical probability that the resource currently has highest amount of free
physical memory of all matching resources. When the Select best resource
by optimization objective policy is used, the job is allocated to the
resource that has the highest amount of free physical memory.
When defining an objective, you must select a resource that is included in
the job definition as part of the identification of targets for the job. For
example, if you want to define the objective to minimize free physical
memory, at least one operating system requirement must be included in
the job definition. This could be candidate operating systems, a physical or
virtual memory requirement, or a related requirement involving operating
system properties. Computer system properties are the exception to this

56 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


rule. Optimization objectives using computer system properties can be
always defined even if the job definition includes no explicit computer
system requirements.
For information about all available load balancing policies, see “Job
definitions” on page 49.

Using variables in job definitions


Use of variables adds flexibility to the job definitions.

There are two types of variables in a job definition:


Job variables
There are three types of job variables: String, Double, Integer. You can
define job variables in your job definition that are resolved or overwritten
at job submission time. This enables the job definition to be used for
different situations by specifying different values for the variable at
submission time. You define variables in the variable element, but you can
refer to the variable from several other elements.
You define variables and assign them values from the Overview page on
the Job Brokering Definition Console. Job variables are referenced in the
job definition in the format ${variable_name}. For example, to use a variable
to set the minimum amount of physical memory required for a job to 512
MB, do the following:
1. In the Variables pane of the Overview page, add the string variable
memory and assign it a value of 512.
2. On the Hardware Requirements tab of the Resources page, select
Range value for Physical memory and set the Minimum value to
${memory}.
When jobs are submitted, using Tivoli Dynamic Workload Console, Tivoli
Workload Scheduler Task field, or the dynamic workload broker CLI,
default values for variables defined in the job definition can be overridden
and new variables can be added.
Environment variables
Environment variables are set in the run time environment for the dynamic
workload broker job definition. Environment variables can be used to
change the run time environment for the job on the assigned resource. This
enables you to change only the values of the environment variables when
you change the resources for the job definition. Environment variables are
referenced in the job definition in the format $variable_name where
variable_name is the name of the environment variable.
Environment variable values cannot be set or overwritten when the job is
submitted.

Using JSDL job definition templates


Use job definition templates to be able to run multiple jobs based on a single JSDL
document, or to turn a traditional job into a dynamic job without the need to create
a specific JSDL definition for it.

You have two options for writing the JSDL job definitions for the workload you
want to submit with dynamic workload broker:
v Writing a separate definition for each job

Chapter 4. Writing JSDL definitions with the Job Brokering Definition Console 57
v Writing a generalized definition that you can use as a template to run more jobs

Writing and using templates is an option that lets you reuse the same JSDL
document on multiple jobs when they use the same resources and candidate hosts
and share similar scheduling and optimization preferences. This requires that you
also define an extended agent workstation for each template you implement, so
that at runtime the JSDL template can be properly identified by selecting the
extended agent on which the job you want to run is defined. In this way, you can
make up classes of jobs where all the jobs that belong to the same class are defined
to run on the same extended agent and therefore select, by means of the workload
broker workstation, the same JSDL document to submit to the broker.

Except when they include return code mapping expressions, traditional Tivoli
Workload Scheduler jobs can be routed to dynamic workload broker by simply
changing their CPU to an appropriate extended agent, without changing the job
definition and without requiring a different JSDL definition for each job. This is the
recommended way for changing static workload into dynamic workload in Tivoli
Workload Scheduler. It is in the long run more expedient than the transition
procedure described in “Modifying your existing workload definitions for use with
dynamic workload broker” on page 28.

Writing a JSDL job definition template

Specific, prepackaged JSDL templates that you can fill in do not exist. Rather, you
work a number of steps so that you can write in the Job Brokering Definition
Console a JSDL file that can be referenced by more Tivoli Workload Scheduler job
definitions.

To write a template you use the following:


v The composer command line or the Tivoli Dynamic Workload Console to define
extended agents (with their access method) and to create or modify job
definitions in Tivoli Workload Scheduler.
v The Job Brokering Definition Console to write the JSDL file that you then use as
a template.

The steps are:


1. In the Job Brokering Definition Console, you create a JSDL document, give it a
name, and save it in the in the Job Repository of dynamic workload broker.
Like for regular job definitions, fill in the data throughout the pages of the Job
Brokering Definition Console, specifying the required resources, and
optimization and scheduling details. Unlike you do in regular job definitions, in
the Application page, after setting the Type to Executable (or to Extended Job),
specify the following variable name in the Script (or Task string) field:
${tws.job.taskstring}
2. With composer or the Tivoli Dynamic Workload Console define a workstation of
type extended agent hosted by the workload broker workstation.
If you need background information about extended agents, see the Tivoli
Workload Scheduler User's Guide and Reference. For the purpose of creating the
template, however, you only need to know the following facts about an
extended agent:
v It is a logical definition that must be hosted by a physical workstation. In
this case the physical workstation must always be the workload broker
workstation. This workstation can host as many extended agents as you
need.

58 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


v It requires an access method. An access method can be a complex program,
but in this case it is only a statement that references the name of the JSDL
file that will be your template. The access method statement is included in
the definition of the extended agent and must have the following syntax:
ACCESS "/jsdl/filename_of_the_ JSDL_template -var name=value,name=value,..."

where -var name=value is optional and represents one or more variables


passed by the workload broker workstation to dynamic workload broker at
job submission time.
3. Add the extended agent to the plan as you do with any other workstation. The
workload broker workstation has the task of managing the lifecycle of the
extended agent, notifying the master domain manager that it is up and
running.

When jobs are run on the extended agent, they are routed to the workload broker
workstation, which handles them differently from other jobs. Instead of searching
for the name of the JSDL definition in the task string of the job, the workload
broker workstation:
1. Gets the name of the target JSDL from the access method, and passes the task
string as a value for variable ${tws.job.taskstring}.
2. The task string value is replaced in the script element of the target JSDL, and is
used as a command string to run on the target agent that is dynamically
selected by the dynamic workload broker.
Thus, the JSDL definition invoked by the workload broker workstation works
as a sort of template that you can use to run different task strings defined in
different Tivoli Workload Scheduler jobs: the same JSDL document is reused for
multiple jobs.

Example

You want to exploit dynamic workload broker to run a job named SUBMIT_JOBXA
and you want to use a JSDL template. The following definitions accomplish this:
1. The definition of the workload broker workstation. It is named DGCENTER_DWB
and it is of type BROKER. There can be only one workload broker workstation
running at a time in a Tivoli Workload Scheduler network (this applies also to
the dynamic workload broker server).
CPUNAME DGCENTER_DWB
OS OTHER
NODE DGCENTER TCPADDR 41111
ENGINEADDR 31111
DOMAIN MASTERDM
FOR MAESTRO
TYPE BROKER
AUTOLINK ON
BEHINDFIREWALL OFF
FULLSTATUS OFF
END
2. The definition of extended agent DGCENTER_DWBXA. The extended agent must:
v Be hosted by the workload broker workstation (DGCENTER_DWB in this
example).
v Include the access method. While normally the ACCESS keyword is followed
by the name of the program that implements the specific access method, in
the case of JSDL templates it needs only to define the name of the JSDL
document you use as template - that must be stored in the dynamic
workload broker Job Repository in the Tivoli Workload Scheduler database

Chapter 4. Writing JSDL definitions with the Job Brokering Definition Console 59
and available in a local folder in the workstation where you run the Job
Brokering Definition Console- and whatever other parameters you want to
use. These items must be enclosed between double quotes.
This requires that you created the JSDL document you will be using as a
template (named SJT in this example), defining the required resources,
candidate hosts, and scheduling and optimization preferences, and specifying
${tws.job.taskstring} in the Script field of the executable.
CPUNAME DGCENTER_DWBXA
OS OTHER
NODE DGCENTER TCPADDR 41111
FOR MAESTRO HOST DGCENTER_DWB ACCESS "/jsdl/SJT -var target=D:\vmware,RES=RES1"
TYPE X-AGENT
AUTOLINK OFF
BEHINDFIREWALL OFF
FULLSTATUS OFF
END
3. The definition of job SUBMIT_JOBXA in Tivoli Workload Scheduler:
DGCENTER_DWBXA#SUBMIT_JOBXA
SCRIPTNAME "C:\TWS\Utils\Jobs\javacount_on.bat"
STREAMLOGON Administrator
DESCRIPTION "Added by composer."
TASKTYPE WINDOWS
RECOVERY STOP
The fact that the job is defined to run on extended agent DGCENTER_DWBXA,
hosted by the workload broker workstation and matched with the SJT JSDL
definition, drives the process that:
a. Submits the job via dynamic workload broker
b. Uses the specifications of the SJT JSDL definition
c. Replaces variable ${tws.job.taskstring} in SJT with the task string of
SUBMIT_JOBXA, that is:
C:\TWS\Utils\Jobs\javacount_on.bat

Scenarios for creating job definitions


These scenarios provide examples of creating job definitions with different types of
requirements.

JSDL and the Job Brokering Definition Console provide very flexible tools for
defining jobs. The following scenarios provide examples of how to set up a job
definition to achieve your objectives for identification of targets, resource
allocation, and load balancing:
v “Scenario: Creating a job definition using a computer resource group” on page
61.
This scenario demonstrates the use of a resource group to specify candidate
target systems.
v “Scenario: Creating a job definition using a logical resource group” on page 62.
This scenario demonstrates the use of a resource group to specify logical
resources required for the job..
v “Scenario: Creating a job definition for a job to run on x86 processors” on page
63
This scenario demonstrates the use of advanced requirements for resources and
the use of resource properties for defining load-balancing rules.
v “Scenario: Creating a job definition for a script to run on a specific operating
system” on page 64

60 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


This scenario demonstrates the creation of relationships between an operating
system type software resource and an additional resource requirement.
v “Scenario: Alternative operating system requirements” on page 65
This scenario demonstrates the definition of two resource requirements related to
specific operating system types and a minimum free physical memory
requirement.

Scenario: Creating a job definition using a computer resource


group
In this scenario, a job is created to run the inventory update program, selecting the
target system from the invadmin resource group set up to include the computers
that are suitable for running the script.

About this task

To create a job definition that does this, perform the following steps:

Procedure
1. In the Job Brokering Definition Console select File → New → Job brokering
definition and create a new job definition named compgroupjob. The job
definition opens at the Overview page with the job name assigned.
2. Open the Application page and identify and attach the script, as follows:
a. In the Type menu, select Executable.
b. In the Executable pane, select the Executable File radio button.
c. Click Browse and locate the executable file.
d. Click OK.
3. Open the Resources page and specify the resource group, as follows:
a. Select the Advanced Requirements tab.
b. In the Resource Group pane, click Add. The Resource Group Details dialog
box is displayed.
c. In the Group Name field, type invadmin (the resource group name, as
defined in the Tivoli Dynamic Workload Console).
4. Select File → Save to save the job definition file.

Results
The JSDL file created for this scenario has the following syntax:
<jsdl:jobDefinition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
xmlns:jsdle="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdle"
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl JSDL.xsd
http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdle JSDL-Native.xsd"
description="Run inventory update script on a computer from the
invadmin resource group.
" name="compgroupjob">
<jsdl:application name="executable">
<jsdle:executable path="/opt/invupdate">
</jsdle:executable>
</jsdl:application>
<jsdl:resources>
<jsdl:group name="invadmin"/>
</jsdl:resources>
</jsdl:jobDefinition>

Chapter 4. Writing JSDL definitions with the Job Brokering Definition Console 61
Scenario: Creating a job definition using a logical resource
group
In this scenario, the target for the job is determined by several requirements
defined as logical resources. A resource group has been created to include all the
logical resources required for the job.

About this task

To create a job definition that does this, perform the following steps:

Procedure
1. In the Job Brokering Definition Console selectFile → New → Job brokering
definition and create a new job definition named loggroupjob. The job
definition opens at the Overview page with the job name assigned.
2. Open the Application page and define the required information for the
application that the job is to run.
3. Open the Related Resources page and create a requirement for a logical
resource, as follows:
a. In the Resource Requirements pane, click Add. The Resource Requirement
Details dialog box is displayed.
b. In the ID field, specify a meaningful ID, in this example, loggroup.
4. Open the Resources page and create a relationship to the resource requirement,
as follows:
a. Select the Advanced Requirements tab.
b. In the Relationships pane, click Add. The Relationship Details dialog box is
displayed.
c. In the Type menu, select Associates with.
d. In the Target menu, select the resource requirement that you created and
click OK.
5. Switch back to the Related Resources page and add the logical resource group
as follows:
a. In the Resource Group pane, click Add. The Resource Group Details dialog
box is displayed.
b. In the Group Name field, type the resource group name, as defined in the
Tivoli Dynamic Workload Console.
6. Select File → Save to save the job definition file.

Results

The JSDL file created for this scenario has the following syntax:
<jsdl:jobDefinition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl JSDL.xsd"
description="A job whose requirements are defined by a number of logical
resources. " name="loggroupjob">
<jsdl:application name="executable">
<jsdle:executable path="/opt/myExecutable">
</jsdle:executable>
</jsdl:application>
<jsdl:resources>
<jsdl:relationship target="loggroup" type="AssociatesWith"/>
</jsdl:resources>

62 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


<jsdl:relatedResources id="loggroup" type="LogicalResource">
<jsdl:group name="logresgroup"/>
</jsdl:relatedResources>
</jsdl:jobDefinition>

Scenario: Creating a job definition for a job to run on x86


processors
In this scenario, a job is created to run the application, appx86. The application
must run on a workstation with an x86 processor where the CPU usage between 3
and 30%. Load balancing is to be defined by an objective to keep CPU use on
matching resources to a minimum.

About this task

To create the job definition, perform the following steps:

Procedure
1. In the Job Brokering Definition Console select File → New → Job brokering
definition and create a new job definition named x86job. The job definition
opens at the Overview page with the job name assigned.
2. Open the Application page and define the required information for the appx86
application that the job is to run.
3. Open the Resources page and specify the processor and CPU usage
requirements as follows:
a. Select the Advanced Requirements tab.
b. Click Add Requirement. The Resource Property Details dialog box is
displayed.
c. In the Property Name menu, select CPU Utilization.
d. In the Property Value section, select the Range Value radio button and
assign values of 3 to Minimum and 30 to Maximum.
e. Click Add Requirement. The Resource Property Details dialog box is
displayed.
f. In the Property Name menu, select Processor type.
g. In the Property Value section, select the Exact Value radio button and
assign a values of x86.
4. Open the Optimization page and specify the load balancing requirement as
follows:
a. In the Type menu, select Balance load between resources by optimization
objective.
b. In the Resource Type menu, select Computer System.
c. In the Resource Property menu, select CPU Utilization.
d. In the Optimization Objective menu, select the Minimize.
5. Select File → Save to save the job definition file.

Results

The JSDL file created for this scenario has the following syntax:
<jsdl:jobDefinition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl JSDL.xsd"
description="Job to run on X86 processors" name="x86job">
<jsdl:application name="executable">

Chapter 4. Writing JSDL definitions with the Job Brokering Definition Console 63
<jsdle:executable path="/opt/appx86">
</jsdle:executable>
</jsdl:application>
<jsdl:resources>
<jsdl:properties>
<jsdl:requirement propertyName="CPUUtilization">
<jsdl:range>
<jsdl:minimum>3</jsdl:minimum>
<jsdl:maximum>30</jsdl:maximum>
</jsdl:range>
</jsdl:requirement>
<jsdl:requirement propertyName="ProcessorType">
<jsdl:exact>x86</jsdl:exact>
</jsdl:requirement>
</jsdl:properties>
</jsdl:resources>
<jsdl:optimization name="JPT_JSDLOptimizationPolicyType">
<jsdl:objective propertyObjective="minimize"
resourcePropertyName="CPUUtilization"
resourceType="ComputerSystem"/>
</jsdl:optimization>
</jsdl:optimization>
</jsdl:jobDefinition>

Scenario: Creating a job definition for a script to run on a


specific operating system
In this scenario, a job is created to run a script on a Red Hat Enterprise Linux
system.

About this task

By specifying candidate operating systems, you can define the type of operating
system on which a job is to run, in this case Linux. To direct the job to a specific
flavor of Linux, you must define a related resource and link it to the job resources
by creating a relationship. To create a job definition that does this, perform the
following steps:

Procedure
1. In the Job Brokering Definition Console select File → New → Job brokering
definition and create a new job definition named rhjob. The job definition
opens at the Overview page with the job name assigned.
2. Open the Application page and define the required information for the
application that the job is to run.
3. Open the Resources page and specify the operating system type requirement,
as follows:
a. Select the Software Requirements tab.
b. In the Candidate Operating Systems pane, click Add. The Operating
System Details dialog box is displayed.
c. In the Type menu, select LINUX and click OK.
4. Open the Related Resources page and create a resource requirement for the Red
Hat flavor of Linux, as follows:
a. In the Resource Requirements pane, click Add. The Resource Requirement
Details dialog box is displayed.
b. In the ID field, specify a meaningful ID, in this example, redhat.
c. In the Type menu, select Operating System.

64 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


d. In the Resource Properties pane, click Add Requirement. The Resource
Property details dialog box is displayed.
e. In the Property Name menu, select Display Name.
f. In the Property Value , type Red*.
5.
6. Switch back to the Resources page to link the resource requirement to the
operating system resource.
a. Select the Advanced Requirements tab.
b. In the Relationships pane, click Add. The Relationship Details dialog box is
displayed.
c. In the Type menu, select Contains.
d. In the Target menu, select the Red Hat resource requirement that you
created and click OK.
7. Select File → Save to save the job definition file.

Results

The JSDL file created for this scenario has the following syntax:
<jsdl:jobDefinition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl"
xsi:schemaLocation="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdl
JSDL.xsd" description="Job to run on Red Hat Linux" name="rhjob">
<jsdl:application name="executable">
<jsdle:executable path="/opt/myExecutable">
</jsdle:executable>
</jsdl:application>
<jsdl:resources> <jsdl:resources>
<jsdl:candidateOperatingSystems>
<jsdl:operatingSystem type="LINUX"/>
</jsdl:candidateOperatingSystems>
<jsdl:relationship target="redhat" type="Contains"/>
</jsdl:resources>
<jsdl:relatedResources id="redhat" type="OperatingSystem">
<jsdl:properties>
<jsdl:requirement propertyName="DisplayName">
<jsdl:exact>red*</jsdl:exact>
</jsdl:requirement>
</jsdl:properties>
</jsdl:relatedResources>
</jsdl:jobDefinition>

Scenario: Alternative operating system requirements


In this scenario, a definition is created for a job that can run on either a Linux or
an AIX computer.

About this task

The job can run on Linux operating systems with a minimum of 512 MB of RAM
or on AIX operating systems with a minimum of 1024 MB of RAM. The job
definition must include a resource requirement that specifies the two alternative
requirements.

To create job definition for this job, perform the following steps:

Chapter 4. Writing JSDL definitions with the Job Brokering Definition Console 65
Procedure
1. In the Job Brokering Definition Console select File → New → Job brokering
definition and create a new job definition named jobWithRequirementsByOS.
The job definition opens at the Overview page with the job name assigned.
2. Open the Application page and define the required information for the
application that the job is to run.
3. Open the Related Resources page.
4. In the Resource Requirements pane, click Add then specify a meaningful value
for the ID field. In this example it is OperatingSystemType.
5. In the Resource Properties pane, define the logic that describes the two
alternative operating system requirements, as follows:
a. Click Add OR Operand to indicate that you are defining alternatives.
b. Highlight the OR operand and click Add AND Operand to indicate that the
alternative includes more than requirement.
c. Highlight the AND operand and click Add Requirement.
d. In the Resource Property Details dialog, select Operating System Type from
the Property Name menu and type LINUX in the Property value field.
e. Highlight the AND operand again and click Add Requirement.
f. In the Resource Property Details dialog, select Total Physical Memory from
the Property Name menu and type 512 in the Property value field.
g. Highlight the OR operand again and click Add AND Operand to add the
requirements for the second alternative.
h. Highlight the new AND operand and click Add Requirement.
i. In the Resource Property Details dialog, select Operating System Type from
the Property Name menu and type AIX in the Property value field.
j. Highlight the AND operand again and click Add Requirement.
k. In the Resource Property Details dialog, select Total Physical Memory from
the Property Name menu and type 1024 in the Property value field.
6. Open the Resources page and create a relationship to the resource requirement,
as follows:
a. Select the Advanced Requirements tab.
b. In the Relationships pane, click Add. The Relationship Details dialog box is
displayed.
c. In the Type menu, select Contains.
d. In the Target menu, select the resource requirement OperatingSystemType
and click OK.
7. Select File → Save to save the job definition file.

Results

The JSDL file created for this scenario has the following syntax:
<jsdl:jobDefinition xmlns:jsdl="http://www.ibm.com/xmlns/prod/scheduling/
1.0/jsdl" xmlns:jsdle="http://www.ibm.com/xmlns/prod/scheduling/1.0/jsdle"
xmlns:xmi="http://www.omg.org/XMI" xmi:version="2.0" description="This job
has different requirements for memory based on the operating system it will
run on " name="jobWithRequirementsByOS">
<jsdl:application name="executable">
<jsdle:executable path="/opt/myExecutable">
</jsdle:executable>
</jsdl:application>
<jsdl:resources>
<jsdl:relationship target="OperatingSystemType" type="Contains"/>

66 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


</jsdl:resources>
<jsdl:relatedResources id="OperatingSystemType" type="OperatingSystem">
<jsdl:properties>
<jsdl:or>
<jsdl:and>
<jsdl:requirement propertyName="OperatingSystemType">
<jsdl:exact>LINUX</jsdl:exact>
</jsdl:requirement>
<jsdl:requirement propertyName="TotalPhysicalMemory">
<jsdl:range>
<jsdl:minimum>512</jsdl:minimum>
</jsdl:range>
</jsdl:requirement>
</jsdl:and>
<jsdl:and>
<jsdl:requirement propertyName="OperatingSystemType">
<jsdl:exact>AIX</jsdl:exact>
</jsdl:requirement>
<jsdl:requirement propertyName="TotalPhysicalMemory">
<jsdl:range>
<jsdl:minimum>1024</jsdl:minimum>
</jsdl:range>
</jsdl:requirement>
</jsdl:and>
</jsdl:or>
</jsdl:properties>
</jsdl:relatedResources>
</jsdl:jobDefinition>

Chapter 4. Writing JSDL definitions with the Job Brokering Definition Console 67
68 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically
Chapter 5. Submitting and tracking jobs
Although you should normally use the standard Tivoli Workload Scheduler means
to schedule and submit workload, there is also an additional way to submit jobs
directly to dynamic scheduling using either the Tivoli Dynamic Workload Console
or the dynamic workload broker command line, described in the next chapter. This
implies that you only need to write a JSDL job definition. You do not need to write
a job definition in Tivoli Workload Scheduler and the workload broker workstation
does not come into play. Choosing to do so, however, results in not exploiting the
scheduling and choreography services of Tivoli Workload Scheduler. This chapter
explains how to submit and track jobs using the Tivoli Dynamic Workload
Console.

About this task

Job definitions are stored in the Job Repository and you search for them and select
them when the job needs to be submitted. At submission time, you can also specify
that a job run on the same resource as a job that has previously run. The job
definition provides all necessary parameters for a job to run, however, you can add
to and change the parameters defined in the job definition for the job instance you
are submitting. This does not change the job definition stored in the Job
Repository.

The lifecycle of a job involves the following sequence of phases:


1. Submission of the job to the Job Dispatcher.
2. Job scheduling.
3. Allocation of resources by the Resource Advisor.
4. Job execution.
5. Job status monitoring.

Using the Tivoli Dynamic Workload Console, you can manage the whole lifecycle
of a job by performing the following tasks:
v “Submitting jobs”
v “Monitoring submitted jobs” on page 74

Submitting jobs
This section describes how to submit jobs with the Tivoli Dynamic Workload
Console based on the JSDL job definition only.

Before you begin

You can submit jobs according to the specifications defined in the JSDL file, or you
can modify some of the specifications at submission time. Using the Submit...
action from the Definitions → Job task, you can specify the following information
at submission time:
v Define an alias for the job to be submitted so that you can subsequently submit
an affine job using the jobsubmit command specifying the alias name. Since
every job instance has its own job ID which is not easy to remember, define an
alias name that can be easily recognized.

© Copyright IBM Corp. 2009, 2010 69


v Specify the computer on which to run the job. If you choose to submit a job on a
specified computer, the Tivoli Dynamic Workload Console performs a search and
displays physical computers that meet the requirements of the job at that
moment. You can then select a specific computer on which to run the job, or
allow dynamic workload broker to allocate the job dynamically to one of the
jobs in the list of matching computers.
v Add, remove, or modify the values for variables defined in the job. See
“Submitting jobs with variables” on page 72.
v Specify that a job run on the same resource as another job. See “Submitting jobs
with affinity relationships.”

About this task

To submit a job according to the specifications defined in the JSDL file without the
option to modify the definition at submission time, perform the following steps:

Procedure
1. In the console navigation tree, expand Definitions and click Jobs.
2. Search for a job definition stored in the Job Repository database.
3. Select the job definition that you want to submit.
4. Click Submit.
5. Click Go. The job is submitted.

Results

After submitting a job, it can assume one of the following statuses:


Table 21. Job status
Error Waiting Completed Cancel
Conditions Conditions Running Successfully Conditions

v Run Failed v Submitted Running Completed v Canceled


Successfully
v Unable to v Submitted to v Cancel
Start Agent Pending
v Resource v Resource v Cancel
Allocation Allocation Allocation
Failed Received
v Unknown v Waiting for
Reallocation
v Waiting for
Resources

What to do next

You can also use the jobsubmit command from the command-line interface. See
“jobsubmit command - Submitting jobs” on page 84

Submitting jobs with affinity relationships


An affinity relationship is established between two or more jobs when you want
them to run on the same resource.

70 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Before you begin

An affinity relationship is useful when the results of one job are required for the
next job to run. You can define an affinity relationship between two or more jobs in
the following ways:
v “Submitting a job with affinity from the Tivoli Dynamic Workload Console”
v “Submitting a job with affinity from the command line”
v “Defining affinity relationships” on page 34 in Tivoli Workload Scheduler.

Submitting a job with affinity from the Tivoli Dynamic


Workload Console
About this task

To submit a job to run on the same resources as a previous job, do the following:

Procedure
1. In the console navigation tree, expand Definitions and click Jobs.
2. Search for a job definition stored in the Job Repository database.
3. Select the job definition that you want to submit.
4. Click Submit...
5. Click Go. The Job Definitions wizard starts.
6. You can optionally define an alias for the job by selecting Provide an alias to
the job for this submission. Subsequently, you can use the alias name to
submit a new job using the jobsubmit command to define an affinity
relationship with the job you are submitting now. You can also use the alias as
a user-friendly alternative to the job ID when performing queries on jobs from
the command line or tracking job instances.
7. In the Target Resource area, select the option Specify that this job runs on
the same resources as a previous job.
8. Click Next. If you selected to specify an alias, then you are prompted to
provide the alias name. Click Next.
9. Search and select the job with which you want to establish an affinity
relationship. The current job will then run on the same resource as the job you
select. Click Next.
10. On the summary page, review your selections and click Finish to submit the
job.

Results

The job is submitted on the same resources as the job you selected. You can now
check the job status by selecting Tracking → Job Instances from the navigation. See
“Monitoring submitted jobs” on page 74 for more information.

Submitting a job with affinity from the command line


About this task

The jobsubmit command requires a job ID or an alias name for the affine job.

Chapter 5. Submitting and tracking jobs 71


What to do next

Submit the following command to make the job defined in job definition
WinJob2.jsdl, with the alias WJ220070606, run on the same resource as the
previously run job, WinJob1, which was submitted with the alias, WJ120070606:
jobsubmit -jsdl WinJob2.jsdl -alias WJ220070606 -affinity alias=WJ120070606

Submitting jobs with variables


When you submit a job, you can define or change a variable to be used by the job.

About this task

During job submission, you can define variables that are to be used by the job
itself or to assign the job to a resource. You can add new variables or override the
default values for variables that are included in the job definition. For more
information about including variables in the job definitions see “Using variables in
job definitions” on page 57. At submission time, you can add or change variables
in the following ways:
v “Submitting a job with variables from the Tivoli Dynamic Workload Console”
v “Submitting a job with variables from the command line” on page 73
v “Using Tivoli Workload Scheduler variables in dynamic workload broker jobs”
on page 31 in Tivoli Workload Scheduler.

Submitting a job with variables from the Tivoli Dynamic


Workload Console
About this task

To submit a job, changing or adding variables, do the following:

Procedure
1. In the console navigation tree, expand Definitions and click Jobs.
2. Search for a job definition stored in the Job Repository database.
3. Select the job definition that you want to submit.
4. Click Submit...
5. Click Go. The Job Definitions wizard starts.
6. Select Provide values for any of the job variables. The Job Variables page
shows any variables that are defined in the job definition.
7. Add or change variables as follows:
v Change the value of a variable defined in the job definition by replacing the
value shown in the Predefined Variables table.
v Add a text or numeric variable by clicking Add text variable or Add
numeric variable and providing a variable name and value when the entry
is added to the table of variables.
You can remove a variable that you have defined by selecting it and clicking
Remove selected variables. You cannot remove predefined variables.
8. Click Next.
9. On the summary page, review your selections and click Finish to submit the
job.

72 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Submitting a job with variables from the command line
About this task

The jobsubmit command submits jobs from the command line interface. You can
include arguments to change the value of predefined variables and add new ones.
For example, the job definition for Job1 includes the variable memory with the value
512 which is used to set the free physical memory requirement. To increase the
requirement to 1024 when submitting the job, issue the following command:
jobsubmit -jdname Job1 -var memory=1024

What to do next

Job statuses
This section describes all supported statuses for a job as returned both by the
command line interface and by the Tivoli Dynamic Workload Console. It also lists
the operations a user can perform depending on the status the job is in.
Table 22. Job statuses and supported operations
Tivoli Dynamic You can
You can cancel You can browse
Workload Icon Command line status define
the job the job output
Console status affinity
Run failed RED FAILED_
' '
EXECUTION
Resource RED RESOURCE_
allocation failed ALLOCATION_
FAILED
Unable to start RED NOT_EXECUTED '
Unknown YELLOW UNKNOWN ' '
Submitted WAITING SUBMITTED '
Waiting for WAITING WAITING_FOR_
'
resources RESOURCES
Resource WAITING RESOURCE_
allocation ALLOCATION_ '
received RECEIVED
Submitted to WAITING SUBMITTED_
' '
agent TO_ENDPOINT
Waiting for WAITING RESOURCE_
'
reallocation REALLOCATE
Cancel pending ABORT PENDING_
' '
CANCEL
Cancel allocation ABORT CANCEL_
' '
ALLOCATION
Canceled ABORT CANCELLED ' '
Running RUNNING EXECUTING ' ' '
Completed GREEN SUCCEEDED_
' '
successfully EXECUTION

Note: You can define an affinity relationship with a job in Canceled state only if
the job was canceled while running.

Chapter 5. Submitting and tracking jobs 73


Monitoring submitted jobs
A job instance is a job that is submitted to run at a specific time. You can track the
outcome of a submitted job from the Tivoli Dynamic Workload Console.

Before you begin

Prerequisite: A job must be submitted to dynamic workload broker before you can
view its instances. Submitted jobs are stored in the Job Repository for a default
time interval. Refer to the IBM Tivoli Workload Scheduler Administration Guide
for information about configuring this interval in the
JobDispatcherConfig.properties file. You can access the following information about
job instances:
v Status of the job instance.
v The host name of the computer where the job instance ran.
v The return code of the job instance.
v The date and time the job was submitted.
v The date and time the job started and finished running.

About this task

For example, to view all jobs that have resulted in error within the last 24 hours,
follow these steps:

Procedure
1. In the console navigation tree, expand Tracking and click Job Instances. The
Track Job Instance Search Criteria page is displayed
2. Specify the search criteria for the job instances as follows:
a. In the Submission Time section, select the Last 24 Hours radio button.
b. In the Job Status section, select Error Conditions.
c. Click Search.
The results are displayed in the Job Tracking page.

Results

As an alternative, you can take the following steps:


1. In the console navigation tree, expand Definitions and click Jobs. The Job
Definition Search Criteria page is displayed.
2. Specify the search criteria for the job definition associated with the job instance
that you want to view.
3. Select the job for which you want to show instances.
4. Click Show Instances. The results are displayed in the Job Definitions Search
Result page.

Once a job is submitted to the Job Dispatcher, it goes through the phases of job
scheduling, allocation of resources, and finally, job execution. Problems might occur
along the way, and there are specific job statuses that identify at which point
things went wrong. The following is a list of job statuses that a job can assume
after it is submitted to be run:

74 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Job completing successfully
The job goes through the following statuses:Submitted → Waiting for
resources → Resource allocation received → Submitted to agent → Running
→ Completed successfully.
Job being canceled
The job goes through the following statuses:Submitted → Waiting for
resources → Resource allocation received → Submitted to agent → Running
→ Cancel pending → Canceled.
Job being reallocated
The job is allocated to a computer which is temporarily unreachable, for
example because of a network problem. The job goes through the
following statuses:Submitted → Waiting for resources → Resource
allocation received → Waiting for reallocation → Waiting for resources .
Job encountering an error
There can be several reasons for the error. Here are some examples:
v The job encounters an error because the selected working directory does
not exist on the target system. The job goes through the following
statuses:Submitted → Waiting for resources → Resource allocation
received → Submitted to agent → Unable to start. As the job cannot start,
no output is available.
v The job requires an operating system which is not available in the
environment. The job goes through the following statuses:Submitted →
Waiting for resources → Resource allocation failed.
v The job encounters an error because one of the parameters specified in
the job is not supported on the target system. The job goes through the
following statuses:Submitted → Waiting for resources → Resource
allocation received → Submitted to agent → Running → Run failed.
When viewing the job instance details for this job Job Tracking page, the
reason for the error is displayed. You can also use the ID indicated in the
Identifier field to retrieve more information on the job results, which is
stored in a series of log files on the computer where the job ran. The name
of the computer where the job ran is also indicated in the Job Tracking
page. Locate the computer and analyze the log files available in the folder
named with the job ID in the following path:
TWA_home/TWS/stdlist/JM/yyy.mm.dd/archive

Every job has a compressed file whose name is the job ID, for example:
ed1d4933-964b-3f5e-8c73-f720919491d6.zip

The compressed file contains the following:


diagnostics.log
May or may not include diagnostic information.
jm_exit.properties
Includes the return code as well as other job statistics, like CPU
and memory usage.
out.log
Includes the full job output.
trace.log
Includes the output trace of the task launcher process spawned by
the Tivoli Workload Scheduler agent to run the job.

Chapter 5. Submitting and tracking jobs 75


trace.log_cmd
Includes the command used to run the task launcher.

76 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Chapter 6. Using the command line interface
Dynamic workload broker has a command line for running a set of commands.
You can use the command line interface to save, submit, query, monitor, cancel
jobs, and view the job output. You can also archive database tables.

Commands are stored in the following location on the master domain manager:
TWA_home/TDWB/bin

The following commands are available:


Table 23. Dynamic workload broker commands
Command Purpose See
exportserverdata Downloads the list of “exportserverdata command
dynamic workload broker - downloading the list of
instances from the Tivoli workload broker instances
Workload Scheduler database from the database” on page
to a temporary file. Use to 81
record a port number or host
name change.
importserverdata Uploads the list of dynamic “importserverdata command
workload broker instances - uploading the list of
from the temporary file to workload broker instances to
the Tivoli Workload the database” on page 83
Scheduler database after you
are done recording a port
number or host name
change.
jobsubmit Submits a job to the Job “jobsubmit command -
Dispatcher. Submitting jobs” on page 84
jobdetails Returns property information “jobdetails command -
for the specified job. Viewing details on jobs” on
page 90
jobquery Returns a list of submitted “jobquery command -
jobs matching the selection Performing queries on jobs”
criteria. on page 86
jobcancel Cancels a submitted job. “jobcancel command -
Canceling jobs” on page 92
jobstore Manages job definitions. “jobstore command -
Managing job definitions” on
page 93
jobgetexecutionlog Displays the results of “jobgetexecutionlog
submitted jobs. command - Viewing job
output” on page 95
movehistorydata Moves data present in the “movehistorydata command
Job Repository database to - Maintaining the database
the archive tables. tables” on page 96

© Copyright IBM Corp. 2009, 2010 77


Table 23. Dynamic workload broker commands (continued)
Command Purpose See
1 resource Creates and manages “resource command -
1 resources and groups. Working with resources” on
1 Manages associated page 98
1 computers.

1 By properly configuring the


1 CLIConfig.properties file on
1 the agent, you can run this
1 command also from any
1 connected Tivoli Workload
1 Scheduler agent. See
1 “Running the resource
1 command from an agent” on
1 page 105 for details.

Command-line syntax

This chapter uses the following special characters to define the syntax of
commands:
[] Identifies optional attributes. Attributes not enclosed in brackets are
required.
... Indicates that you can specify multiple values for the previous attribute.
| Indicates mutually exclusive information. You can use the attribute to the
left of the separator or the attribute to its right. You cannot use both
attributes in a single use of the command.
{} Delimits a set of mutually exclusive attributes when one of the attributes is
required. If the attributes are optional, they are enclosed in square brackets
([]).
\ Indicates that the syntax in an example wraps to the next line.

Command-line configuration file


The CLIConfig.properties file contains configuration information which is used
when typing commands. By default, arguments required when typing commands
are retrieved from this file, unless explicitly specified in the command syntax.

The CLIConfig.properties file is created at installation time and is located on the


master domain manager in the following path:
TWA_home/TDWB/config

1 Starting from this version of Tivoli Workload Scheduler, an additional instance of


1 this file is installed on every agent for users who want to be able to run the
1 resource command not only from the master but also from specific agents. See
1 “Running the resource command from an agent” on page 105 for details.

The CLIConfig.properties file contains the following set of parameters:


Dynamic workload broker default properties
ITDWBServerHost
Specifies the IP address of dynamic workload broker.

78 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


ITDWBServerPort
Specifies the number of the dynamic workload broker port. The
default value is 9550.
ITDWBServerSecurePort
Specifies the number of the dynamic workload broker port when
security is enabled. The default value is 9551.
use_secure_connection
Specifies whether secure connection must be used. The default
value is false.
KeyStore and trustStore file name and path
keyStore
Specifies the name and path of the keystore file containing private
keys. A keystore file contains both public keys and private keys.
Public keys are stored as signer certificates while private keys are
stored in the personal certificates. The default value is
/Certs/TDWBClientKeyFile.jks.
trustStore
Specifies the name and path of the truststore file containing public
keys. A truststore file is a key database file that contains public
keys. The public key is stored as a signer certificate. The keys are
used for a variety of purposes, including authentication and data
integrity. The default value is /Certs/TDWBClientTrustFile.jks.
Passwords for keyStore and trustStore files
keyStorepwd
Specifies the password for the keystore file.
trustStorepwd
Specifies the password for the truststore file.
File types for keyStore and trustStore files
keyStoreType
Specifies the file type for the keyStore file. The default value is JKS.
trustStoreType
Specifies the file type for the trustStore file. The default value is
JKS.
Default user ID and password for dynamic workload broker
tdwb_user
Specifies the user name for a user authorized to perform
operations on dynamic workload broker when security is enabled.
The default value is ibmschedcli. This password must be
previously defined on IBM WebSphere. For more information on
security considerations, refer to IBM Tivoli Workload Scheduler
Administration Guide
tdwb_pwd
Specifies the password for a user authorized to perform operations
on dynamic workload broker when security is enabled. This
password must be previously defined on IBM WebSphere . For
more information on security considerations, refer to IBM Tivoli
Workload Scheduler Administration Guide.
Detail level for command-line log and trace information

Chapter 6. Using the command line interface 79


logger.Level
Specifies the detail level for the command-line trace and log files.
The command-line trace and log files are created in the following
location:
log file
TWA_home/TDWB/logs/Msg_cli.log.log
trace file
TWA_home/TDWB/logs/Trace_cli.log

The default value is INFO.


logger.consoleLevel
Specifies the detail level for the log and trace information to be
returned to standard output. The default value is FINE. Supported
values for both the consoleLevel and loggerLevel parameters are
as follows:
ALL Indicates that all messages are logged.
SEVERE
Indicates that serious error messages are logged.
WARNING
Indicates that warning messages are logged.
INFO Indicates that informational messages are logged.
CONFIG
Indicates that static configuration messages are logged.
FINE Indicates that tracing information is logged.
FINER
Indicates that detailed tracing information is logged.
FINEST
Indicates that highly detailed tracing information is logged.
OFF Indicates that logging is turned off.
logger.limit
Specifies the maximum size of a log file in bytes. The default value
is 400000. When the maximum size is reached, a new file is
created, until the maximum number of files is reached. When all
files reach the maximum size and the maximum number of files is
exceeded, the oldest file is re-written.
logger.count
Specifies the maximum number of log files. The default value is 6.
When the maximum size is reached, a new file is created, until the
maximum number of files is reached. When all files reach the
maximum size and the maximum number of files is exceeded, the
oldest file is re-written. When a new file is created the 0 suffix is
appended after the file extension. The file with the 0 suffix is
always the current file. Any older files are renumbered accordingly.
java.util.logging.FileHandler.pattern
Specifies that the trace information for the Java Virtual Machine is
logged in the Trace_cli.log file. The default value is INFO.
java.util.logging.FileHandler.limit
Specifies the maximum size of a trace file in bytes. The default

80 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


value is 400000. When the maximum size is reached, a new file is
created, until the maximum number of files is reached. When all
files reach the maximum size and the maximum number of files is
exceeded, the oldest file is re-written.
java.util.logging.FileHandler.count
Specifies the maximum number of trace files. The default value is
6. When the maximum size is reached, a new file is created, until
the maximum number of files is reached. When all files reach the
maximum size and the maximum number of files is exceeded, the
oldest file is re-written. When a new file is created the 0 suffix is
appended after the file extension. The file with the 0 suffix is
always the current file. Any older files are renumbered accordingly.
java.util.logging.FileHandler.formatter
Specifies the formatter to be used for the Trace_cli.log file. The
default value is com.ibm.logging.icl.jsr47.CBEFormatter.
DAO common configuration
This section defines the RDBMS settings for the exportserverdata,
importserverdata, and movehistorydata commands. These commands use
the RDBMS installed on dynamic workload broker These parameters are
valorized at installation time and should not be modified, except for
com.ibm.tdwb.dao.rdbms.useSSLConnections as noted below.
com.ibm.tdwb.dao.rdbms.rdbmsName
Specifies the RDBMS name.
com.ibm.tdwb.dao.rdbms.useDataSource
Specifies the data source to be used.
com.ibm.tdwb.dao.rdbms.jdbcPath
Specifies the path to the JDBC driver.
com.ibm.tdwb.dao.rdbms.jdbcDriver
Specifies the JDBC driver.
com.ibm.tdwb.dao.rdbms.userName
Specifies the name of the RDBMS user.
com.ibm.tdwb.dao.rdbms.password
Specifies the password of the RDBMS user.
com.ibm.tdwb.dao.rdbms.useSSLConnections
Specifies that access to the Tivoli Workload Scheduler DB2
database by some of the CLI commands is over SSL. Is set to FALSE
by default. You must set to TRUE, if the database is DB2 and you
use FIPS security, for the following commands to work:
v exportserverdata
v importserverdata
v movehistorydata

exportserverdata command - downloading the list of workload broker


instances from the database
Use the exportserverdata command to download the list of dynamic workload
broker instances from the Tivoli Workload Scheduler database and change a port
number or a host name.

Chapter 6. Using the command line interface 81


Syntax

exportserverdata ?

exportserverdata -dbUsr db_user_name -dbPwd db_user_password -exportFile


filename

Description

This command extracts a list of URIs (Uniform Resource Identifier) of all the
dynamic workload broker instances from the Tivoli Workload Scheduler database
and copies them to a temporary file so that, if either the hostname or the port
number of any of the instances listed are changed, the administrator can record
this information in the file and place it back in the database with the
importserverdata command.

This action is necessary because the list of dynamic workload broker instances
must be kept up-to-date at all times, since the Resource Advisor agents
periodically connect to the active instance to send their data about the resources
discovered in each computer. They are able to automatically switch between the
instances of this list and find the active one to copy these data in its Resource
Repository. Since the master domain manager and every backup master are
installed with a dynamic workload broker instance, the active dynamic workload
broker instance runs in the master domain manager, while an idle instance resides
in each backup master.

The URI pointing to each dynamic workload broker instance is the following:
https://hostname:port_number/JobManagerRESTWeb/JobScheduler

You can change only the hostname and the port number.

Important: The list is ordered. You can change the order of the instances as they
appear in this list, and the agents will follow this order. If you have several backup
masters and decide to follow a specific switching order when a master fails, you
can instruct the agents to switch to the right instance using this ordered list,
speeding up the transition time.

If your Tivoli Workload Scheduler database is DB2 and you use FIPS security, to
run this command successfully you need to have the
com.ibm.tdwb.dao.rdbms.useSSLConnections option set to TRUE in the
CLIConfig.properties file.

Options
? Displays help information.
-dbUsrdb_user_name
The user name required to access the Tivoli Workload Scheduler database
server.
-dbPwddb_user_password
The user password required to access the Tivoli Workload Scheduler database
server.
-exportFilefilename
The name of the temporary file where the URIs extracted from the database are
copied for editing. This text file is created when you run the command and

82 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


you can open it with any editor to change the hostname or the port number. If
you do not specify a path, the file is created in the same directory where the
command is located, that is:
<TWA_home>/TDWB/bin

If you do specify a different path, make sure the path exists before you run
this command.

Example

To download the current list of all (active and backup) dynamic workload broker
instances and copy them in a file named c:\myservers\uris160709, run:
exportserverdata -dbUsr twsadm -dbPwd fprefect -exportFile c:\myservers\uris160709

The command returns file uris160709, that looks like this:


https://accrec015:42127/JobManagerRESTWeb/JobScheduler
https://prodop099:52529/JobManagerRESTWeb/JobScheduler
https://prodop111:31116/JobManagerRESTWeb/JobScheduler

prodop099 is the active dynamic workload broker instance because is hosted by the
currently active master domain manager, whereas accrec015 and prodop111 are
idle because they are hosted by backup masters.

You can edit this file to apply your changes before using the importserverdata
command to upload the URIs back to the database.

See Also

“importserverdata command - uploading the list of workload broker instances to


the database”

importserverdata command - uploading the list of workload broker


instances to the database
Use the importserverdata command to upload the list of dynamic workload broker
instances to the Tivoli Workload Scheduler database after editing the temporary file
to change a port number or a host name.

Syntax

importserverdata ?

importserverdata -dbUsr db_user_name -dbPwd db_user_password -importFile


filename

Description

This command puts back the list of dynamic workload broker instances in the
Tivoli Workload Scheduler database from the temporary file where they were
previously downloaded with the exportserverdata command.

Use the exportserverdata and importserverdata commands if you have to record


any hostname or port number changes in the URIs of the instances. This is
necessary to keep the list of dynamic workload broker instances up-to-date at all
times, since the Resource Advisor agents periodically connect to the active instance

Chapter 6. Using the command line interface 83


to send their data about the resources discovered in each computer. They are able
to automatically switch between the instances of this list and find the active one to
copy these data in its Resource Repository. Since the master domain manager and
every backup master are installed with a dynamic workload broker instance, the
active dynamic workload broker instance runs in the master domain manager,
while an idle instance resides in each backup master.

Important: The list is ordered. You can change the order of the instances as they
appear in this list, and the agents will follow this order. If you have several backup
masters and decide to follow a specific switching order when a master fails, you
can instruct the agents to switch to the right instance using this ordered list,
speeding up the transition time.

If your Tivoli Workload Scheduler database is DB2 and you use FIPS security, to
run this command successfully you need to have the
com.ibm.tdwb.dao.rdbms.useSSLConnections option set to TRUE in the
CLIConfig.properties file.

Options
? Displays help information.
-dbUsrdb_user_name
The user name required to access the Tivoli Workload Scheduler database
server.
-dbPwddb_user_password
The user password required to access the Tivoli Workload Scheduler database
server.
-importFilefilename
The name of the temporary file you specified with the -exportFile keyword in
the exportserverdata command.

Example

To upload the edited list of dynamic workload broker instance URIs from file
c:\myservers\uris160709 to the Tivoli Workload Scheduler database, run:
importserverdata -dbUsr twsadm -dbPwd fprefect -importFile c:\myservers\uris160709

See Also

“exportserverdata command - downloading the list of workload broker instances


from the database” on page 81

jobsubmit command - Submitting jobs


Use the jobsubmit command to submit jobs to the Job Dispatcher.

Syntax

jobsubmit ?

jobsubmit [-usr user_name -pwd password] {-jsdl jsdl_file | -jdname


job_definition_name} [-alias job_alias] [-var variable=value...] [-affinity {jobid=job_id |
alias=alias}] [-configFile configuration_file]

84 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Description

This command submits a job to the Job Dispatcher. When the job is submitted, it is
assigned a unique ID, which can be used for retrieving information on and
canceling jobs.

You can use this command to submit jobs saved locally on the dynamic workload
broker server or saved in the Job Repository. To submit a local job, use the -jsdl
option and specify the path to the JSDL file. To submit a job saved in the Job
Repository, use the -jdname option and specify the job definition name.

When submitting jobs, you can also define an alias to be used as an alternative to
the job ID when performing queries on the job, or for defining subsequent jobs as
affine. To define affinity between two or more jobs, use the -affinity option when
submitting the subsequent jobs. You define jobs as affine when you want them to
run on the same resource, for example when the second job must use the results
generated by the previous job.

Options
? Displays help information.
-usr user_name
Specifies the username for a user authorized to perform operations on the
command line. This parameter is required when security is enabled and the
username is not defined in the CLIConfig.properties configuration file (with
the tdwb_user keyword).
-pwd password
Specifies the password for a user authorized to perform operations on the
command line. This parameter is required when security is enabled and the
password is not defined in the CLIConfig.properties configuration file (with
the tdwb_pwd keyword).
-jsdl jsdl_file
Specifies the name and path to a local JSDL file which provides the parameters
for a job when it is submitted. This parameter is required when the jdname
parameter is not is not specified.
-jdname job_definition_name
Specifies the name of a job definition stored in the Job Repository database.
The job definition name is defined within the JSDL file and can be modified
only by editing the JSDL file. This parameter is required when the jsdl
parameter is not specified. To obtain this name, you can use the Definitions →
Jobs task from the Tivoli Dynamic Workload Console console navigation tree,
or the jobstore command specifying one or more of the query options. For
more information on the jobstore command, see “jobstore command -
Managing job definitions” on page 93.
-alias job_alias
Indicates that an alias must be generated for the job being submitted. You can
use the alias as a user-friendly alternative to the job ID when performing
queries on the job. You can also use the alias when submitting new jobs so that
the new job is affine to the job having this alias. To define affinity between two
or more jobs, use the -affinity option when submitting the new jobs. You
define jobs as affine when you want them to run on the same resource. On
Windows systems, the maximum length for the alias is 200 characters, if you
used the default installation paths for WebSphere Application Server and
dynamic workload broker.

Chapter 6. Using the command line interface 85


-var variable=value
Specifies a variable and the associated value. You can also specify a list of
variables by separating them with a comma. This value overrides the value
specified when creating the JSDL file. You can also specify new variables
without previously defining them in the JSDL file.
-affinity jobid=job_id
Specifies that the current job is affine to a previously submitted job. To
establish the affinity relationship, specify the job ID for the previous job. The
job ID is automatically generated at submission time.
-affinity alias=alias
Specifies that the current job is affine to a previously submitted job. To
establish the affinity relationship, specify the job alias for the previous job. The
job alias is generated at submission time when you specify the -alias option.
-configFile configuration_file
Specifies the name and path of a custom configuration file. This parameter is
optional. If this parameter is not specified, the default configuration file is
assumed. For more information on the configuration file, see “Command-line
configuration file” on page 78.

Authorization

The user name and password for the command are defined in the
CLIConfig.properties file. To override the settings defined in this file, you can enter
the user name and password when typing the command. For more information on
the CLIConfig.properties file, see “Command-line configuration file” on page 78.

Return Values

The jobsubmit command returns one of the following values:


0 Indicates that jobsubmit completed successfully.
< > 0 Indicates that jobsubmit failed.

Examples
1. To submit the local job test_job located in the /staging_area/accounts/ path
using the configuration parameters specified in the custom_config.properties
configuration file, type the following command:
jobsubmit -jsdl /staging_area/accounts/test_job -configFile
/opt/test/custom_config.properties
2. To submit the job definition domestic_accounts saved in the Job Repository,
type the following command:
jobsubmit -jdname domestic_accounts

See Also

“jobdetails command - Viewing details on jobs” on page 90

jobquery command - Performing queries on jobs


Use the jobquery command to perform advanced queries on submitted jobs.

Syntax

jobquery ?

86 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


jobquery [-usr user_name -pwd password] {[-status status...] [-submitter submitter]
[-name job_definition_name] [-alias job_alias] [-sdf submit_date_from] [-sdt
submit_date_to] [-jsdf job_start_date_from] [-jsdt job_start_date_to ] [-jedf
job_end_date_from] [-jedt job_end_date_to]} [-configFile configuration_file]

Description

This command performs advanced queries on submitted jobs based on the


following attributes:
v job status
v name of the user who submitted the job
v job name
v job alias
v job submission date
v job start date
v job completion date

You can also use this command to retrieve the job ID generated at submission
time, which is required when running the jobstatus, jobdetails and jobcancel
commands. To retrieve the job ID, specify the -name option.

Options
? Displays help information.
-usr user name
Specifies the user name for a user authorized to perform operations on the
command line. This option is required when security is enabled and the user
name is not defined in the CLIConfig.properties configuration file (with the
tdwb_user keyword).
-pwd password
Specifies the password for a user authorized to perform operations on the
command line. This option is required when security is enabled and the
password is not defined in the CLIConfig.properties configuration file (with
the tdwb_pwd keyword).
-status status
Specifies the status of the jobs to be searched. Separate statuses using commas;
spaces are not supported. Supported statuses are as follows:
0 all supported statuses
1 submitted
2 waiting for resources
3 resource allocation received
4 submitted to agent
5 running
6 cancel pending
7 canceling allocation
8 waiting for reallocation
41 resource allocation failed
42 run failed

Chapter 6. Using the command line interface 87


43 completed successfully
44 canceled
45 unknown job
46 job not started
-submitter submitter
Specifies the name of the user who submitted the job.
-name job_definition_name
Specifies the job name. This option returns the unique job ID, which can be
used for retrieving information on and canceling jobs. This option supports the
asterisk (*) wildcard character as described below:
as a single parameter
it must be enclosed in inverted commas, for example
C:\Program Files\TDWB\bin>jobquery -name "*"

This command returns a list of all submitted jobs.


to complete a job name
it does not require inverted commas, for example
C:\Program Files\TDWB\bin>jobquery -name batchsub*

This command returns a list of all submitted jobs starting with the
batchsub suffix.
-alias job_alias
Specifies the job alias. The job alias is generated at submission time using the
-alias option. For more information see “jobsubmit command - Submitting
jobs” on page 84.
-sdf submit_date_from
Specifies a time range starting from the date when the job was submitted. The
query is performed starting from the date you specified to the present date,
unless the -sdt option is specified. Use both the -sdf and -sdt options to define
a specific time range. Specify the date in the dd/MM/yyyy-hh:mm:ss format.
-sdt submit_date_to
Specifies a time range starting from the date when the job was submitted. The
query is performed starting from the date when the dynamic workload broker
database was populated to the date you specified, unless the -sdf option is
specified. Use both the -sdf and -sdt options to define a specific time range.
Specify the date in the dd/MM/yyyy-hh:mm:ss format.
-jsdf job_start_date_from
Specifies a time range starting from the date when the job started. The query is
performed starting from the date you specified to the present date, unless the
-jsdt option is specified. Use both the -jsdf and -jsdt options to define a
specific time range. Specify the date in the dd/MM/yyyy-hh:mm:ss format.
-jsdt job_start_date_to
Specifies a time range starting from the date when the job started. The query is
performed starting from the date when the dynamic workload broker database
was populated to the date you specified, unless the -jsdf option is specified.
Use both the -jsdf and -jsdt options to define a specific time range. Specify the
date in the dd/MM/yyyy-hh:mm:ss format.
-jedf job_end_date_from
Specifies a time range starting from the date when the job completed. The

88 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


query is performed starting from the date you specified to the present date,
unless the -jedt option is specified. Use both the -jedf and -jedt options to
define a specific time range. Specify the date in the dd/MM/yyyy-hh:mm:ss
format.
-jedt job_end_date_to
Specifies a time range starting from the date when the job completed. The
query is performed starting from the date when the dynamic workload broker
database was populated to the date you specified, unless the -jedf option is
specified. Use both the -jedf and -jedt options to define a specific time range.
Specify the date in the dd/MM/yyyy-hh:mm:ss format.
-configFile configuration_file
Specifies the name and path of a custom configuration file. This option is
optional. If this option is not specified, the default configuration file is
assumed. For more information on the configuration file, see “Command-line
configuration file” on page 78.

Authorization
The user name and password for the command are defined in the
CLIConfig.properties file. To override the setting defined in this file, you can enter
the user name and password when typing the command. For more information on
the CLIConfig.properties file, see “Command-line configuration file” on page 78.

Return Values

The jobquery command returns one of the following values:


0 Indicates that jobquery completed successfully.
< > 0 Indicates that jobquery failed.

Examples
1. To retrieve the job ID for a job named CLIJSB11, type the following command:
jobquery -usr john -pwd BCA12EDF -name CLIJSB11

The following output is displayed. The job ID is associated to the Job Identifier
key:
Call Job Dispatcher to query jobs. There are 10 Jobs found for your request
Details are as follows:

Job Name: CLIJSB11


Job Alias: alias
Job Identifier: 617c9bf7095787c83e1c36744e569ceb
Status: FAILED_running
Job EPR: http://lab135200.romelab.it.ibm.com:955
/JDServiceWS/services/Job
Job Submitter Name:
Submit Time: Tue May 23 15:41:54 CEST 2006
Start Time: Tue May 23 14:48:09 CEST 2006
End Time: Tue May 23 14:48:09 CEST 2006
Job Last Status Message:
Job Duration: PT0S
Returncode: 0
Job Resource Name: LAB237010
Job Resource Type: ComputerSystem
2. To retrieve all jobs submitted by test_user in submitted, resource allocation
failed, and canceled state, type the following command:
jobquery -status 1,3,44 -submitter test_user

Chapter 6. Using the command line interface 89


See Also

“jobsubmit command - Submitting jobs” on page 84

jobdetails command - Viewing details on jobs


Use the jobdetails command to view details on submitted jobs.

Syntax

jobdetails ?

jobdetails [-usr user_name -pwd password] -id job_ID [-v ][-configFile


configuration_file]

Description

This command displays details on submitted jobs using the unique ID created at
job submission. To retrieve the job ID after submitting the job, use the jobquery
command specifying the -name parameter.

Options
? Displays help information.
-usr username
Specifies the username for a user authorized to perform operations on the
command line. This parameter is required when security is enabled and the
username is not defined in the CLIConfig.properties configuration file (with
the tdwb_user keyword).
-pwd password
Specifies the password for a user authorized to perform operations on the
command line. This parameter is required when security is enabled and the
password is not defined in the CLIConfig.properties configuration file (with
the tdwb_pwd keyword).
-id job_ID
Specifies the unique job ID created at submission time. This parameter is
required.
-v Displays job details.
-configFile configuration_file
Specifies the name and path of a custom configuration file. This parameter is
optional. If this parameter is not specified, the default configuration file is
assumed. For more information on the configuration file, see “Command-line
configuration file” on page 78.

Authorization

The user name and password for the command are defined in the
CLIConfig.properties file. To override the setting defined in this file, you can enter
the user name and password when typing the command. For more information on
the CLIConfig.properties file, see “Command-line configuration file” on page 78.

Return Values

The jobdetails command returns one of the following values:

90 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


0 Indicates that jobdetails completed successfully.
<>0 Indicates that jobdetails failed.

Examples
1. To view run information on a job with ID 617c9bf7095787c83e1c36744e569ceb,
type the following command:
jobdetails -id 617c9bf7095787c83e1c36744e569ceb

An output similar to the following is displayed:


Call Job Dispatcher to get the job properties.
Success return from Job Dispatcher.
Job Identifier: 617c9bf7095787c83e1c36744e569ceb
Job Name: CLIJSB11
Job Alias: alias
Job State: SUBMITTED
Job Submitter: null
Client Notification: http://lab135200.romelab.it.ibm.com:9550
/RAServiceWS/services/Allocation
Job Last Status Message:
Job Submit Time: Tue May 23 15:43:44 CET 2009
Job Start Time: Tue May 23 14:49:51 CET 2009
Job End Time: Tue May 23 14:49:51 CET 2009
Job Duration: PT0S
Job Return Code: 0
Job Resource Name: LAB237010
Job Resource Type: ComputerSystem
Job Usage Metric Name: StartTime
Job Usage Metric Type: null
Job Usage Metric Value: 1148388591000
Job Usage Metric Name: EndTime
Job Usage Metric Type: null
Job Usage Metric Value: 1148388591000
2. To submit the job with ID 617l9jw7095787g83f1c36744e569glf using the
configuration parameters specified in the custom_config.properties
configuration file, type the following command:
jobdetails -id 617l9jw7095787g83f1c36744e569glf -configFile
/opt/test/custom_config.properties
3. To view the status of a job with ID 617c9bf7095787c83e1c36744e569ceb, type
the following command:
jobdetails -id 617c9bf7095787c83e1c36744e569ceb

An output similar to the following is displayed:


Call Job Dispatcher to get the job properties.
Success return from Job Dispatcher.
Job ID: 617c9bf7095787c83e1c36744e569ceb
Status: SUBMITTED
4. To view details on the job with ID 617c9bf7095787c83e1c36744e569ceb using
the configuration parameters specified in the custom_config.properties
configuration file, type the following command:
jobdetails -jsdl 617c9bf7095787c83e1c36744e569ceb -configFile
/opt/test/custom_config.properties

See Also
v “jobsubmit command - Submitting jobs” on page 84
v “jobquery command - Performing queries on jobs” on page 86

Chapter 6. Using the command line interface 91


jobcancel command - Canceling jobs
Use the jobcancel command to cancel a submitted job.

Syntax

jobcancel ?

jobcancel [-usr user_name -pwd password] -id job_ID [-configFile configuration_file]

Description

This command cancels the running of submitted jobs using the unique ID created
at job submission. To retrieve the job ID after submitting the job, you can use the
jobquery command specifying the job name.

Options
? Displays help information.
-usr user_name
Specifies the username for a user authorized to perform operations on the
command line. This parameter is required when security is enabled and the
username is not defined in the CLIConfig.properties configuration file (with
the tdwb_user keyword).
-pwd password
Specifies the password for a user authorized to perform operations on the
command line. This parameter is required when security is enabled and the
password is not defined in the CLIConfig.properties configuration file (with
the tdwb_pwd keyword).
-id job_ID
Specifies the unique job ID created at submission time. This parameter is
required.
-configFile configuration_file
Specifies the name and path of a custom configuration file. This parameter is
optional. If this parameter is not specified, the default configuration file is
assumed. For more information on the configuration file, see “Command-line
configuration file” on page 78.

Authorization

The user name and password for the command are defined in the
CLIConfig.properties file. To override the settings defined in this file, you can enter
the user name and password when typing the command. For more information on
the CLIConfig.properties file, see “Command-line configuration file” on page 78.

Return Values

The jobcancel command returns one of the following values:


0 Indicates that jobcancel completed successfully.
< > 0 Indicates that jobcancel failed.

Examples
1. To cancel the running of a job with ID 617l9jq7037529f83x1w36185e569fwl, type
the following command:

92 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


jobcancel -id 617l9jq7037529f83x1w36185e569fwl

See Also

“jobsubmit command - Submitting jobs” on page 84

jobstore command - Managing job definitions


Use the jobstore command to manage job definitions.

Syntax

jobstore ?

jobstore [-usr user_name -pwd password]{[ -create jsdl_file ] | [ -update jsdl_file ] |


[-del job_definition_name ] | [ -get job_definition_name ] | [-queryall ] | [[
-queryname job_definition_name...] [ -querydesc job_definition_description...]
[-queryowner job_definition_owner... ]]} [ -configFile configuration_file }

Description

This command saves and updates JSDL files in the Job Repository. JSDL files are
saved in the database as job definitions with unique names. After saving JSDL files
in the database, you can perform the following operations on job definitions:
v Delete job definitions
v Print job definitions to standard output or save them to a file
v Perform queries on job definitions based on several attributes

You can submit job definitions using the jobsubmit command. For more
information on the jobsubmit command, see “jobsubmit command - Submitting
jobs” on page 84.

Options
? Displays help information.
-usr username
Specifies the user name for a user authorized to perform operations on the
command line. This parameter is required when security is enabled and the
user name is not defined in the CLIConfig.properties configuration file (with
the tdwb_user keyword).
-pwd password
Specifies the password for a user authorized to perform operations on the
command line. This parameter is required when security is enabled and the
password is not defined in the CLIConfig.properties configuration file (with
the tdwb_pwd keyword).
-create jsdl_file
Specifies the name and path to a JSDL file to be saved in the Job Repository
database. The JSDL file is saved as a job definition. The name for the job
definition is saved within the JSDL file and can only be modified by editing
the JSDL file. Delete and retrieve (get) operations are performed on the job
definition.
-update jsdl_file
Specifies the name and path to a JSDL file to be updated in the Job Repository
database. The JSDL file must be already existing in the database.

Chapter 6. Using the command line interface 93


-del job_definition_name
Deletes a job definition from the Job Repository database.
-get job_definition_name
Prints the JSDL file contained in the job definition to standard output or to a
file you specify. You can use this command for performing minor editing on
job definitions.
-queryall
Performs a query without any filters. This query returns all job definitions
stored in the dynamic workload broker database.
-queryname job_definition_name
Performs a search on job definitions based on the job definition name. The job
definition name is unique. This parameter is case sensitive. Wildcards (*, ?) are
supported.
-querydesc job_definition_desc
Performs a search on job definitions based on the job definition description.
Wildcards are supported.
-queryowner job_definition_owner
Performs a search on job definitions based on the user who created the job
definition.
-configFile configuration_file
Specifies the name and path of a custom configuration file. This parameter is
optional. If this parameter is not specified, the default configuration file is
assumed. For more information on the configuration file, see “Command-line
configuration file” on page 78.

Authorization

The user name and password for the command are defined in the
CLIConfig.properties file. To override the setting defined in this file, you can enter
the user name and password when typing the command. For more information on
the CLIConfig.properties file, see “Command-line configuration file” on page 78.

Return Values

The jobstore command returns one of the following values:


0 Indicates that jobstore completed successfully.
< > 0 Indicates that jobstore failed.

Examples
1. To retrieve all jobs created by user Administrator, type the following
command:
jobstore -queryuser Administrator
2. To update the job branch_update already stored in the Job repository database,
type the following command:
jobstore -update ../jsdl/branch_update.xml

See Also
v “jobsubmit command - Submitting jobs” on page 84
v “jobquery command - Performing queries on jobs” on page 86

94 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


jobgetexecutionlog command - Viewing job output
Use the jobgetexecutionlog command to view the output of a submitted job.

Syntax

jobgetexecutionlog ?

jobgetexecutionlog [-usr user_name -pwd password] -id job_ID -sizePage size Page
-offset offset [-configFile configuration_file]

Description

This command displays the job output for submitted jobs using the unique ID
created at job submission. To retrieve the job ID after submitting the job, you can
use the jobquery command specifying the job name. You can also specify the
length of the output page to be displayed and the number of the byte in the job
output from where you want to start displaying the output.

Options
? Displays help information.
-usr user_name
Specifies the username for a user authorized to perform operations on the
command line. This parameter is required when security is enabled and the
username is not defined in the CLIConfig.properties configuration file (with
the tdwb_user keyword).
-pwd password
Specifies the password for a user authorized to perform operations on the
command line. This parameter is required when security is enabled and the
password is not defined in the CLIConfig.properties configuration file (with
the tdwb_pwd keyword).
-id job_ID
Specifies the unique job ID created at submission time. This parameter is
required.
-sizePage size Page
Specifies the number of bytes to be displayed in the job output page.
-offset offset
Specifies the number of the first byte to be displayed in the job output page.
This option can be used to view large job outputs.
-configFile configuration_file
Specifies the name and path of a custom configuration file. This parameter is
optional. If this parameter is not specified, the default configuration file is
assumed. For more information on the configuration file, see “Command-line
configuration file” on page 78.

Authorization

The user name and password for the command are defined in the
CLIConfig.properties file. To override the settings defined in this file, you can enter
the user name and password when typing the command. For more information on
the CLIConfig.properties file, see “Command-line configuration file” on page 78.

Chapter 6. Using the command line interface 95


Return Values

The jobgetexecutionlog command returns one of the following values:


0 Indicates that jobgetexecutionlog completed successfully.
< > 0 Indicates that jobgetexecutionlog failed.

Examples
1. To view the output of a job with ID 617l9jq7037529f83x1w36185e569fwl
displaying the output in pages containing 400® bytes starting from the first byte
in the page, type the following command:
jobgetexecutionlog -id 617l9jq7037529f83x1w36185e569fwl -sizePage 400 -offset 1

The following output is displayed:


Call Job Dispatcher to get the output of the job
Success returned from Job Dispatcher
Get Execution Log request submitted
The Execution Log Page requested is:
al 5
drwxrwxrwx 7 root root 200 Aug 24 16:39 .
drwxrwxrwx 8 root root 208 Aug 22 15:11 ..
drwxrwxrwx 6 root root 248 Aug 22 15:11 eclipse
-rw-rw-rw- 1 root root 139 Aug 24 16:39 jsdef
drwxr-xr-x 2 root root 552 Aug 24 16:54 logs
drwxrwxrwx 5 root root 240 Aug 22 15:11 rcp
drwxrwxrwx 3 root root 72 Aug 22 15:11 shared
drwxrwxrwx 3 root root 80 Aug 22 15:11 workspace

The file size is:


381

See Also
v “jobsubmit command - Submitting jobs” on page 84
v “jobquery command - Performing queries on jobs” on page 86

movehistorydata command - Maintaining the database tables


You can use the movehistorydata command when access to the database becomes
too slow.

This problem might be due to a huge number of records being present in the
database, for example when bulk job submissions are performed.

You can use the movehistorydata command to move the data present in the Job
Repository to the archive tables. When you run this command, the jobs are moved
to the following tables in the database:
JOA_JOB_ARCHIVES
Contains archived job instances
JRA_JOB_RESOURCE_ARCHIVES
Contains resource information related to the jobs
MEA_METRIC_ARCHIVES
Contains metrics collected for the jobs

For more information on historical tables, refer to the IBM Tivoli Workload Scheduler
Administration Guide.

96 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Note: Depending on the number of jobs and accesses to the database, a cleanup
operation might cause some peaks in memory or CPU usage.

If your Tivoli Workload Scheduler database is DB2 and you use FIPS security, to
run this command successfully you need to have the
com.ibm.tdwb.dao.rdbms.useSSLConnections option set to TRUE in the
CLIConfig.properties file.

Syntax

movehistorydata ?

movehistorydata -dbUsr db_user_name-dbPwd db_password


[-successfulJobsMaxAge successfulJobsMaxAge [-notSuccessfulJobsMaxAge
notSuccessfulJobsMaxAge ][ -archivedJobsMaxAge archivedJobsMaxAge]]

Description

This command performs a cleanup operation on the Job Repository database.


Based on the values you specify, information on submitted jobs is moved to the
archive database and the information in the archive database is deleted.

Use this command to temporarily override the settings defined in the


JobDispatcherConfig.properties file, when unexpected events require an
immediate database cleanup. The settings in the JobDispatcherConfig.properties
file remain unchanged. For more information on the
JobDispatcherConfig.properties file, refer to the IBM Tivoli Workload Scheduler
Administration Guide.

Options
? Displays help information.
-dbUsr db_user_name
Specifies the username for a user authorized to perform operations on the
database server.
-dbPwd db_password
Specifies the password for a user authorized to perform operations on the
database server.
-successfulJobsMaxAge successfulJobsMaxAge
Specifies how many hours jobs completed successfully or cancelled must be
kept in the Job Repository database before being archived. The default value is
12 hours.
-notSuccessfulJobsMaxAge notSuccessfulJobsMaxAge
Specifies how many hours jobs completed unsuccessfully or in unknown status
must be kept in the Job Repository database before being archived. The default
value is 72 hours.
-archivedJobsMaxAge archivedJobsMaxAge
Specifies how many hours jobs must be kept in the archive database before
being archived. The default value is 168 hours.

Return Values

The movehistorydata command returns one of the following values:


0 Indicates that movehistorydata completed successfully.

Chapter 6. Using the command line interface 97


<>0 Indicates that movehistorydata failed.

Examples
1. To move to the archive database all successful jobs completed in the last 40
hours, type the following command:
movehistorydata -dbUsr halmst -dbPwd dgordon -successfulJobsMaxAge 40
2. To move to the archive database all jobs in all supported statuses and remove
from the archive database all jobs older than 700 hours, type the following
command:
movehistorydata -dbUsr halmst -dbPwd dgordon -successfulJobsMaxAge 0
-notSuccessfulJobsMaxAge 0 -archivedJobsMaxAge 700

resource command - Working with resources


You can use the resource command to create, modify, associate, query or set
resources online or offline.

Syntax

resource ?

resource [-usr user_name -pwd password ]


{
[-create{ -logical name -type type[-quantity quantity ][-offline ] |
-group name[-offline ]}]
|
[-delete{-logical name |
-group name |
-computer name |
-computerByID ID}]
|
[-update{-computer name{[-setOnline | -setOffline]} |
-logical name
[-setName name]
[-setType type]
[-setQuantity quantity]
[-setOnline | -setOffline]
[-addComputer name |
-addComputerByID ID |
-removeComputer name |
-removeComputerByID ID]
|
-group name
[-setName name]
[-setOnline | -setOffline]
[-addComputer name |
-addComputerByID ID |
-removeComputer name |
-removeComputerByID ID |
-addLogical name |
-removeLogical name]}]
|
[-query{-computer name [-v] |
-logical name [-v] |

98 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


-groupname [-v]}
[-configFile configuration_file]
}

Description

Use this command to work with computers, logical resources, and resource groups.
In particular it is possible to:
v Create, update, list and delete logical resources or groups
v Create logical resources, associate them to computers, define groups of logical
resources or computers and set them online or offline
v Retrieve and update resource properties by using the query and the update
options
v Change the association between computers and logical resources
v Delete computers associated to resources, set them online or offline, and query
computer properties

Options
? Displays help information.
-usr user_name
Specifies the user name for a user authorized to perform operations on the
command line. This option is required when security is enabled and the user
name is not defined in the CLIConfig.properties configuration file (with the
tdwb_user keyword).
-pwd password
Specifies the password for a user authorized to perform operations on the
command line. This option is required when security is enabled and the
password is not defined in the CLIConfig.properties configuration file (with
the tdwb_pwd keyword).
-create -logical name -type type
Creates the logical resource with the specified name and type. It is also
possible to set a specific quantity or set the resource offline by using optional
parameters in the following way:
-create -logical name -type type-quantity quantity -offline
-create -group name
Creates the resource group with the specified name. It is also possible to set it
offline by using the -offline optional parameter in the following way:
-create -group name -offline
-delete -logical name
Deletes the logical resource with the specified name.
-delete -group name
Deletes the resource group with the specified name.
-delete -computer name
Deletes the computer system with the specified name.
-delete -computerByID ID
Deletes the computer system with the specified ID.
-update -computer name
Updates the computer system with the specified name. You can set the
computer online or offline as follows:

Chapter 6. Using the command line interface 99


-update -computer name -setOnline
Sets the specified computer online.
-update -computer name -setOffline
Sets the specified computer offline.
-update -logical name
Updates the specified logical resource. You can update the properties and
status of a resource in the following ways:
-update -logical name -setName name
Updates the name of the specified logical resource.
-update -logical name -setType type
Updates the type of the specified logical resource.
-update -logical name -setQuantity quantity
Updates the quantity of the specified logical resource.
-update -logical name -setOnline
Sets online the specified logical resource.
-update -logical name -setOffline
Sets offline the specified logical resource.

You can change the association between a logical resource and a computer in
the following ways:
-update -logical name -addComputer name
Associates the specified logical resource to the computer with the specified
name.
-update -logical name -addComputerByID ID
Associates the specified logical resource to the computer with the specified
ID.
-update -logical name -removeComputer name
Removes the association between the specified logical resource and the
computer with the specified name.
-update -logical name -removeComputerByID ID
Removes the association between the specified logical resource and the
computer with the specified ID.
-update -group name
Updates the specified resource group. You can update the properties and status
of a resource group in the following ways:
-update -group name -setName name
Updates the name of the specified resource group.
-update -group name -setOnline
Sets online the specified resource group.
-update -group name -setOffline
Sets offline the specified resource group.

You can add and remove logical resources or computers to and from a resource
group in the following ways:
-update -group name -addLogical name
Adds the logical resource with the specified name to the resource group.

100 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


-update -group name -removeLogical name
Removes the logical resource with the specified name from the resource
group.
-update -group name -addComputer name
Adds the computer with the specified name to the resource group.
-update -group name -addComputerByID ID
Adds the computer with the specified ID to the resource group.
-update -group name -removeComputer name
Removes the computer with the specified name from the resource group.
-update -group name -removeComputerByID ID
Removes the computer with the specified ID from the resource group.
-query -computer name
Retrieves the following properties of the specified computer:
v Name
1 v Computer ID
v Operating system name
v Operating system type
v Operating system version
v Status
v Availability status
Retrieves the following additional properties if you add the -v option:
v Physical memory
v Virtual memory
v CPU utilization
v Free physical memory
v Free virtual memory
v Free swap space
v Allocated physical memory
v Allocated virtual memory
v Allocated swap space
v Processors number
v Allocated processors number
v Processor type
v Processor speed
v Manufacturer
v Model
v Serial number
You can use the asterisk (*) as a wildcard character in the following ways:
As a single parameter
You must enclose it between double quotes, for example:
C:\IBM\TWA\TDWB\bin>resource –query –computer "*"

This command returns a list of all existing computers.


To complete a computer name
You must enclose the entire name between double quotes, for example:

Chapter 6. Using the command line interface 101


C:\IBM\TWA\TDWB\bin> resource –query –computer "lab123*"

This command returns a list of all existing computers with a name


starting with lab123.
-query -logical name
Retrieves the name and the type of the specified logical resource. Retrieves the
following additional properties if you add the -v option:
v Status
v Quantity
v Current allocation
v Computers list
You can use the asterisk (*) as a wildcard character in the following ways:
As a single parameter
You must enclose it between double quotes, for example:
C:\IBM\TWA\TDWB\bin>resource –query –logical "*"

This command returns a list of all existing logical resources.


To complete a resource name
You must enclose the entire name between double quotes, for example:
C:\IBM\TWA\TDWB\bin> resource –query –logical "myRes*"

This command returns a list of all existing logical resources with a


name starting with myRes.
-query -group name
Retrieves the name and the status of the specified resource group. Retrieves the
list of computers and of logical resources contained in the resource group if
you use the –v option.
You can use the asterisk (*) as a wildcard character in the following ways:
As a single parameter
You must enclose it between double quotes, for example:
C:\IBM\TWA\TDWB\bin>resource –query –group "*"

This command returns a list of all existing resource groups.


To complete a resource group name
You must enclose the entire name between double quotes, for example:
C:\IBM\TWA\TDWB\bin> resource –query –group "myResGrou*"

This command returns a list of all existing resource groups with a


name starting with myResGrou.
-configFile configuration_file
Specifies the name and the path of a custom configuration file. This keyword is
optional. If you do not specify it, the default configuration file is assumed. For
more information on the configuration file, see “Command-line configuration
file” on page 78.

Authorization

The user name and password for the command are defined in the
CLIConfig.properties file. To override the settings defined in this file, you can
enter the user name and the password when you type the command. For more

102 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


information on the CLIConfig.properties file, see “Command-line configuration
file” on page 78.

Return Values

The resource command returns one of the following values:


0 Indicates that the command completed successfully.
< > 0 Indicates that the command failed.

Examples
v To create a logical resource named myApplication, of type Applications, type the
following command:
resource.bat -usr john -pwd BXVFDCGS -create -logical myApplication -type Applications

The following output is displayed:


AWKCLI153I Logical resource "myApplication" created.
v To update the quantity of the logical resource named myApplication, type the
following command:
resource.bat -update -logical myApplication -setQuantity 5 -usr john -pwd BXVFDCGS

The following output is displayed:


AWKCLI165I Logical resource "myApplication" updated.
v To add the relationship between a logical resource and a computer, type the
following command:
resource.bat -update -logical myApplication -addComputer myComputer -usr john -pwd BXVFDCGS

The following output is displayed:


AWKCLI165I Logical resource "myApplication" updated.
v To retrieve details of a logical resource named myApplication, type the following
command:
resource.bat -usr john -pwd BXVFDCGS -query -logical myApplication –v

The following output is displayed:


AWKCLI171I Calling the resource repository to perform a query on resources.

AWKCLI172I "1" logical resources were found for your query.


Details are as follows:

Resource Name:myApplication
Resource Type:Applications
Resource Status:Online
Resource Quantity:5
Resource Current Allocation:0
Computers List:
Computer Name:myComputer
Computer ID:D656470E8D76409F9F4FDEB9D764FF59
Computer Status:Online
Computer Availability Status:Unavailable
v 4. To set the logical resource named myApplication offline, type the following
command:
resource.bat -usr john -pwd BXVFDCGS -update -logical myApplication -setOffline

The following output is displayed:


AWKCLI165I Logical resource "myApplication" updated.
v 5. To set the computer named myComputer offline, type the following command:

Chapter 6. Using the command line interface 103


resource.bat -usr john -pwd BXVFDCGS -update -computer myComputer -setOffline

The following output is displayed:


AWKCLI165I Computer "myComputer" updated.
v 6. To retrieve basic properties of the computer named myComputer, type the
following command:
resource.bat -usr john -pwd BXVFDCGS -query -computer myComputer

The following output is displayed:


AWKCLI171I Calling the resource repository to perform a query on resources.
AWKCLI174I "1" computers were found for your query.
Details are as follows:

Computer Name: myComputer


Computer ID:D656470E8D76409F9F4FDEB9D764FF59
Computer OS Name: Microsoft Windows XP Professional English (United States) version
Computer OS Type:Windows XP
Computer OS Version:5
Computer Status:Offline
Computer Availability Status:Unavailable
v 7. To retrieve detailed properties of the computer named myComputer, type the
following command:
resource.bat -usr john -pwd BXVFDCGS -query -computer myComputer -v

The following output is displayed:


AWKCLI171I Calling the resource repository to perform a query on resources.
AWKCLI174I "1" computers were found for your query.
Details are as follows:

Computer Name: myComputer


Computer ID:D656470E8D76409F9F4FDEB9D764FF59
Computer OS Name:Microsoft Windows XP Professional English (United States) version
Computer OS Type:Windows XP
Computer OS Version:5
Computer Status:Offline
Computer Availability Status:Unavailable
Computer details:
Physic memory = 2095536.0
Virtual memory = 3513788.0
Cpu utilization = 16.0
Free physic memory = 947972.0
Free virtual memory = 2333484.0
Free swap space = 52.0
Allocated physic memory = 0.0
Allocated virtual memory = 0.0
Allocated swap space = 0.0
Processors number = 1.0
Allocated processors number = 0.0
Processor type = x86
Processor speed = 1995.00
Manufacturer = IBM
Model = 2668F8G
Serial number = L3WZYNC
v To create a resource group named myGroup, type the following command:
resource.bat -usr john -pwd BXVFDCGS -create -group myGroup

The following output is displayed:


AWKCLI153I Resource group "myGroup" created.

104 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


v To retrieve basic properties of a resource group named myGroup, type the
following command:
resource.bat -query -group myGroup

The following output is displayed:


Setting CLI environment variables....
AWKCLI171I Calling the resource repository to perform a query on resources.
AWKCLI173I "1" groups were found for your query.
Details are as follows:

Group Name:myGroup
Group Status:Online
v To add the computer named myComputer to a resource group named myGroup,
type the following command:
resource.bat -update -group myGroup -addComputer myComputer

The following output is displayed:


Setting CLI environment variables....
AWKCLI165I Resource Group "myGroup" updated.
v To retrieve details of a resource group named myGroup, type the following
command:
resource.bat -query -group myGroup -v

The following output is displayed:


Setting CLI environment variables....
AWKCLI171I Calling the resource repository to perform a query on resources.
AWKCLI173I "1" groups were found for your query.
Details are as follows:

Group Name:myGroup
Group Status:Online
Computers List:
Computer Name:myComputer
Computer ID:D656470E8D76409F9F4FDEB9D764FF59
Computer Status:Online
Computer Availability Status:Unavailable

Resources List:

1 Running the resource command from an agent


1 Starting from this version of Tivoli Workload Scheduler, you can create and
1 manage resources and groups of resources and computers from Tivoli Workload
1 Scheduler agents besides the master domain manager. For this purpose an
1 additional instance of the CLIConfig.properties file is installed on every agent. If
1 you intend to run the resource command from an agent, you must configure
1 certain keywords of CLIConfig.properties locally.

1 Configuring the local CLIConfig.properties file

1 When you apply the version 8.5.1.01 fixpack on a Tivoli Workload Scheduler
1 version 8.5.1 agent, a local copy of CLIConfig.properties is automatically installed
1 and partially configured.

1 Important: For this to work properly, the 8.5.1 version of the agent must have
1 been installed with the runtime environment for Java jobs.

Chapter 6. Using the command line interface 105


1 CLIConfig.properties is installed in the following path in the agent:
1 TWA_home/TWS/TDWB_CLI/config

1 To be able to run resource.bat or resource.sh from the agent, customize the


1 following keywords of the local CLIConfig.properties file:
1 ITDWBServerHost
1 Specify the IP address or the hostname of the master domain manager.
1 ITDWBServerPort
1 Specify the number of the WebSphere Application Server HTTP port.
1 ITDWBServerSecurePort
1 Specify the number of the WebSphere Application Server HTTPS port.
1 tdwb_user
1 Specify the user name for a user authorized to perform operations on
1 dynamic workload broker when security is enabled. This user must be
1 previously defined on IBM WebSphere. For more information on security
1 considerations, refer to IBM Tivoli Workload Scheduler Administration Guide.
1 tdwb_pwd
1 Specify the password for a user authorized to perform operations on
1 dynamic workload broker when security is enabled. This password must
1 be previously defined on IBM WebSphere. For more information on
1 security considerations, refer to IBM Tivoli Workload Scheduler Administration
1 Guide.

1 Starting the command

1 To run the command, enter:


1 resource.bat

1 or
1 resource.sh

106 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Appendix A. Accessibility
Accessibility features help users with physical disabilities, such as restricted
mobility or limited vision, to use software products successfully. The major
accessibility features in this product enable users to do the following:
v Use assistive technologies, such as screen-reader software and digital speech
synthesizer, to hear what is displayed on the screen. Consult the product
documentation of the assistive technology for details on using those technologies
with this product.
v Operate specific or equivalent features using only the keyboard.
v Magnify what is displayed on the screen.

In addition, the product documentation was modified to include features to aid


accessibility:
v All documentation is available in both HTML and convertible PDF formats to
give the maximum opportunity for users to apply screen-reader software.
v All images in the documentation are provided with alternative text so that users
with vision impairments can understand the contents of the images.

Navigating the interface using the keyboard


Standard shortcut and accelerator keys are used by the product and are
documented by the operating system. Refer to the documentation provided by
your operating system for more information.

Magnifying what is displayed on the screen


You can enlarge information on the product windows using facilities provided by
the operating systems on which the product is run. For example, in a Microsoft
Windows environment, you can lower the resolution of the screen to enlarge the
font sizes of the text on the screen. Refer to the documentation provided by your
operating system for more information.

© Copyright IBM Corp. 2009, 2010 107


108 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically
Appendix B. 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 “Searching knowledge bases”
v “Obtaining fixes”
v “Receiving weekly support updates” on page 110
v “Contacting IBM Software Support” on page 110

Searching knowledge bases


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

Searching the information center


IBM provides extensive documentation that can be installed 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.

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

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 at http://www.ibm.com/software/
support.
2. Click Downloads and drivers in the Support topics section.
3. Select the Software category.
4. Select a product in the Sub-category list.
5. In the Find downloads and drivers by product section, select one software
category from the Category list.

© Copyright IBM Corp. 2009, 2010 109


6. Select one product from the Sub-category list.
7. Type more search terms in the Search within results if you want to refine your
search.
8. Click Search.
9. From the list of downloads returned by your search, 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 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.
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, Application servers.
A third list is displayed.
7. In the third list, select a product sub-segment, for example, Distributed
Application & Web Servers. A list of applicable products is displayed.
8. Select the products for which you want to receive updates, for example, IBM
HTTP Server and WebSphere Application Server.
9. Click Add products.
10. After selecting all products that are of interest to you, click Subscribe to email
on the Edit profile tab.
11. Select Please send these documents by weekly email.
12. Update your e-mail address as needed.
13. In the Documents list, select Software.
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).

Contacting IBM Software Support


IBM Software Support provides assistance with product defects.

110 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


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, OS/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”
2. “Describing problems and gathering information” on page 112
3. “Submitting problems” on page 112

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.

Appendix B. Support information 111


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
Software Support Web site daily, so that other users who experience the same
problem can benefit from the same resolution.

112 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information about the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user's responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing


IBM Corporation
North Castle Drive
Armonk, NY 10504-1785 U.S.A.

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.

© Copyright IBM Corp. 2009, 2010 113


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 document 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.

Any performance data contained herein was determined in a controlled


environment. Therefore, the results obtained in other operating environments may
vary significantly. Some measurements may have been made on development-level
systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurement may have been
estimated through extrapolation. Actual results may vary. Users of this document
should verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of


those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.

All statements regarding IBM's future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.

All IBM prices shown are IBM's suggested retail prices, are current and are subject
to change without notice. Dealer prices may vary.

This information is for planning purposes only. The information herein is subject to
change before the products described become available.

This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which


illustrate programming techniques on various operating platforms. You may copy,
modify, and distribute these sample programs in any form without payment to

114 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically


IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating
platform for which the sample programs are written. These examples have not
been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or
imply reliability, serviceability, or function of these programs. You may copy,
modify, and distribute these sample programs in any form without payment to
IBM for the purposes of developing, using, marketing, or distributing application
programs conforming to IBM‘s application programming interfaces.

Each copy or any portion of these sample programs or any derivative work, must
include a copyright notice as follows:

© (your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights
reserved.

If you are viewing this information in softcopy form, the photographs and color
illustrations might not display.

Trademarks
IBM, the IBM logo, AIX, DB2, IBMLink, Informix, OS/2, OS/390, OS/400,
PowerPC, RAA, Tivoli, Tivoli Enterprise Console, TME, and WebSphere are
trademarks or registered trademarks of International Business Machines
Corporation in the United States, other countries, or both.

Intel, Intel Inside (logos), MMX, Celeron, Intel Centrino, Intel Xeon, Itanium,
Pentium and Pentium III Xeon are trademarks or registered trademarks of Intel
Corporation or its subsidiaries in the United States, other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, or


both.

Microsoft and Windows NT 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.

UNIX is a registered trademark of The Open Group in the United States and other
countries.

HP Runtime Environment for J2SE HP-UX 11i platform, adapted by IBM for IBM
Software, Version 1.4.2

SET and the SET Logo are trademarks owned by SET Secure Electronic Transaction
LLC.

Other company, product, and service names may be trademarks or service marks
of others.

Notices 115
116 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically
Index
A conventions used in publications
credentials 49
x
J
accessibility x customer support J2EE jobs
affine jobs See Software Support direct scheduling 9
defining 5, 85 EJB 9
submitting 71 indirect scheduling 9
affinity JMS 9
defining 34, 71, 85 D supported operations 9
definition 5 database data extract 11 J2EE operations
syntax 34 database data validation 11 J2EE security 9
affinity relationship database operations supported configurations 9
defining 34 sample JSDL files 11 supported scheduler type 9
affinity with job alias 34 database stored procedure WebSphere Application Server
affinity with job ID 34 database jobs security 9
affinity with job name 34 sample JSDL files 11 Java jobs
alias sample JSDL files 11 sample JSDL files 11
creating when submitting 71 DB tables maintenance Java operations
defining when submitting 71 movehistorydata command 96 sample JSDL files 11
archiving defining user preferences 5 job alias
job instances 96 dynamic workload broker instance alternative to job ID 71
authorization 5 URI 82, 83 defining 85
Job Brokering Definition Console 49, 61,
62, 63, 64, 65
C E editing job definitions 61, 62, 63, 64,
education 65
call to a Web service
See Tivoli technical training job canceling
sample JSDL files 11
environment variables 57 TWS kill command 36
canceling TWS jobs
exportserverdata command 82 job definition
kill command 36
creating 61, 62, 63, 64, 65
checking
job dependency
scan results 40
defining 34
CLIConfig.properties file F job ID
command-line configuration 78 file system jobcancel command 87
command line related resource 53 jobdetails command 87
command location 77 file transfer jobs jobquery command 87
managing jobs 77 sample JSDL files 11 jobstatus command 87
setting the environment 77 file transfer operations retrieving 87
command line job statuses 73 sample JSDL files 11 job instances
command line syntax 78 fixes, obtaining 109 archiving 96
command-line configuration
showing 74
CLIConfig.properties file 78
status 74
commands
exportserverdata 82 G job priority
generic Java job assigning 49
importserverdata 83
template 11 Job Scheduling Console
jobcancel 92
generic Web service call accessibility x
jobdetails 90
template 11 job status 69
jobgetexecutionlog 95
global resources job status mapping 36
jobquery 86
definition 55 TWS job status 36
jobstore 93
glossary x job statuses
jobsubmit 84
mapping 73
movehistorydata 96
supported operations 73
resource 98
Job Submission Description
computer I Language 49
resource 53 importserverdata command 83 job targets
computers information centers, searching for defining 49, 53
configuring 39 problem resolution 109 job variables 33
physical resources 40 Internet creating 71, 72
conman command searching for problem resolution 109 editing 71, 72
monitoring TWS jobs 36
jobcancel command 92
viewing job output 36
jobdetails command 90
consumable resource
jobgetexecutionlog command 95
resource quantity 49, 56
jobquery command 86

© Copyright IBM Corp. 2009, 2010 117


jobs
allocation 49, 53
R U
creating 49, 53 related resource UNISON variables
defining 49, 53 file system 53 in job definitions 28
jobs logical resource 53 user credentials 49
consumable properties 53 network system 53 user preferences 5
optimizable properties 53 operating system 53 users 5
optimization 49, 53 resource using variables 57
scheduling 49 computer 53
submitting 70 resource command 98
using variables 49 running from agent
CLIConfig.properties setup 105
V
jobstore command 93 variable management 33
jobsubmit command 84 requirement 105
variables 49
jsdl resource groups
defining 72
template 57 creating 44
variables in job
JSDL 49 definition 39
defining at submission 72
resource quantity
defining at submissions 71
consumable resource 49, 56
defining in job definition 57
defining 49, 56
K resource types
editing at submission 71, 72
kill command viewing job output
consumable 53
job canceling 36 conman command 36
resources
knowledge bases, searching for problem optimizable 53
resolution 109 roles 5
W
Web Console
L S roles 6
load-balancing policies 49 user groups 6
scan results 40
defining 56 users 6
Software Support
logical resource Web Console job statuses 73
contacting 110
related resource 53 Web service jobs
describing problems 112
logical resources sample JSDL files 11
determining business impact 111
configuring 39 welcome page 5
receiving weekly updates 110
creating 42 submitting problems 112
defining 42 specific job types
software information 39 sample JSDL files 11
status of a job 69
submitted jobs
M showing 74
monitoring TWS jobs syntax
conman command 36 command line 78
movehistorydata command 96

T
N technical training
network system See Tivoli technical training
related resource 53 Tivoli Dynamic Workload Console
accessibility x
Tivoli technical training xi
Tivoli Workload Scheduler agent
O computer scan 39
operating system environment scan 39
related resource 53 Tivoli Workload Scheduler UNISON
optimization policies 49 variables
in job definitions 28
training
P See also Tivoli technical training
physical resources technical xi
checking 40 TWS alias
priority 49 definition 34
assigning to jobs 49 TWS job status
problem determination job status mapping 36
describing problems 112 TWS jobs
determining business impact 111 submitting 70
submitting problems 112 TWS kill command
publications x job canceling 36

118 IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically




Program Number: 5698-WSH

Printed in USA

SC23-9856-01
Spine information:

IBM Tivoli Workload Scheduler Version 8.5.1 (Revised May 2010) Scheduling Workload Dynamically