Tivoli Workload Automation, Version 9.1

Job definition

A job is an executable file, program, or command that is scheduled and launched by Tivoli Workload Scheduler. You can write job definitions in edit files and then add them to the Tivoli Workload Scheduler database with the composer program. You can include multiple job definitions in a single edit file.

Each job definition has the following format and arguments:

Syntax

$jobs
[workstation#]jobname
   {scriptname filename  streamlogon username |
     docommand “command” streamlogon username |
     task job_definition [streamlogon username]}
   [description “description”]
   [tasktype tasktype]
   [interactive]
   [rccondsucc "Success Condition"]
   [recovery
        {stop | continue | rerun}
        [after [workstation#]jobname]
        [abendprompt “text”] ]

A job itself has no settings for dependencies, these must be added to the job when it is included in a job stream definition.

You can add or modify job definitions from within job stream definitions. Modifications to jobs definitions made in job streams definitions are reflected in the job definitions stored in the database. This means that if you modify the job definition of job1 in job stream definition js1 and job1 is used also in job stream js2, also the definition of job1 in js2 definition is modified accordingly.

Note: Wrongly typed keywords used in job definitions lead to truncated job definitions stored in the database. In fact the wrong keyword is considered extraneous to the job definition and so it is interpreted as the job name of an additional job definition. Usually this misinterpretation causes also a syntax error or an inexistent job definition error for the additional job definition.

Special attention is required in the case where an alias has been assigned to a job. You can decide to use a different name to refer to a particular job instance within a job stream, but the alias name must not conflict with the job name of another job in the same job stream. If a job definition is renamed then jobs having the same name as the job definition modify the name in accordance with the job definition name. Here are some examples to understand the behavior of jobs when the job definition name is modified:

Table 1. Examples: renaming the job defintion
Original job definition names in job stream	Rename job definition	Outcome
SCHEDULE WKS#JS : FTA1#A FTA1#B as C END	Rename job A to D	SCHEDULE WKS#JS : FTA1#D FTA1#B as C END
	Rename job B to D	SCHEDULE WKS#JS : FTA1#A FTA1#D as C END
	Rename job A to C	An error occurs when renaming job A to C because job C already exists as the alias for job B.

Refer to section Job stream definition for information on how to write job streams definitions.

Arguments

workstation#

Specifies the name of the workstation or workstation class on which the job runs. The default is the workstation specified for defaultws when starting the composer session.

For more information on how to start a composer session refer to Running the composer program.

The pound sign (#) is a required delimiter. If you specify a workstation class, it must match the workstation class of any job stream in which the job is included.

If you are defining a job that manages a workload broker job, specify the name of the workstation where the workload broker workstation is installed. Using the workload broker workstation, Tivoli Workload Scheduler can submit job in the Tivoli dynamic workload broker environment using the dynamic job submission.

jobname

Specifies the name of the job. The name must start with a letter, and can contain alphanumeric characters, dashes, and underscores. It can contain up to 40 characters.

scriptname filename

Specifies the name of the file the job runs. Use scriptname for UNIX and Windows jobs. For an executable file, enter the file name and any options and arguments. The length of filename plus the length of Success Condition (of the rccondsucc keyword) must not exceed 4095 characters. You can also use Tivoli Workload Scheduler parameters.

See Using variables and parameters in job definitions for more information.

For Windows jobs, include the file extensions. Universal Naming Convention (UNC) names are permitted. Do not specify files on mapped drives.

If you are defining a job that manages a workload broker job specify the name of the workload broker job. Additionally you can specify variables and the type of affinity that exists between the Tivoli Workload Scheduler job and the workload broker job using the syntax outlined in the list below. To identify an affine job using the:

Tivoli Workload Scheduler job name: jobName [-var var1Name=var1Value,...,varNName=varNValue] [-twsAffinity jobname=twsJobName]
Tivoli dynamic workload broker job ID: jobName [-var var1Name=var1Value,...,varNName=varNValue] [-affinity jobid=jobid]
Tivoli dynamic workload broker job alias: jobName [-var var1Name=var1Value,...,varNName=varNValue] [-affinity alias=alias]

Refer to the IBM® Tivoli® Workload Scheduler: Scheduling Workload Dynamically for detailed information.

If the file path or the file name of the scriptname argument contains spaces, the entire string must be enclosed between "\" and \" " as shown below:

scriptname "\"C:\Program Files\tws\myscript.cmd\""

If special characters are included, other than slashes (/) and backslashes (\), the entire string must be enclosed in quotes (").

The job fails if the script specified in the scriptname option is not found or does not have execute permission. It abends if the script that is not found or does not have execute permission includes parameters.

docommand command

Specifies a command that the job runs. Enter a valid command and any options and arguments enclosed in double quotes ("). The length of command plus the length of Success Condition (of the rccondsucc keyword) must not exceed 4095 characters. You can also enter Tivoli Workload Scheduler parameters.

The job abends if the file specified with the docommand option is not found or does not have execute permission.

See Using variables and parameters in job definitions for more information.

task job_definition

Specifies the XML syntax for job types with advanced options and shadow jobs. To define existing job types, use the docommand keyword. This keyword applies only to workstations of the following types:

agent
pool
d-pool
rem-eng

The syntax of the job depends on the job type you define.

For a complete list of supported job types, see Creating job types with advanced options.

streamlogon username

The user name under which the job runs. This attribute is mandatory when scriptname or docommand are specified. The name can contain up to 47 characters. If the name contains special characters it must be enclosed in double quotes ("). Specify a user that can log on to the workstation on which the job runs. You can also enter Tivoli Workload Scheduler parameters.

See Using variables and parameters in job definitions for more information.

For Windows jobs, the user must also have a user definition.

See User definition for user requirements.

If you are defining a job that manages a dynamic workload broker job, specify the name of the user you used to install Tivoli dynamic workload broker.

The job fails if the user specified in the streamlogon option does not exist.

description “description”

Provides a description of the job. The text must be enclosed in double quotes.The maximum number of characters allowed is 120.

tasktype tasktype

Specifies the job type. It can have one of the following values:

UNIX: For jobs that run on UNIX platforms.
WINDOWS: For jobs that run on Windows operating systems.
OTHER: For jobs that run on extended agents. Refer to IBM Tivoli Workload Scheduler for Applications: User's Guide for information about customized task types for supported vendor acquired applications.
BROKER: For jobs that manage the lifecycle of a Tivoli dynamic workload broker job. Refer to IBM Tivoli Workload Scheduler: Scheduling Workload Dynamically for information about how to use Tivoli dynamic workload broker.

interactive

If you are defining a job that manages a Tivoli dynamic workload broker job ignore this argument. Specifies that the job runs interactively on your desktop. This feature is available only on Windows environments.

rccondsucc "Success Condition"

An expression which determines the return code (RC) required to consider a job successful. The success condition can be a maximum of 256 characters. This expression can be one of the following:

COMPLETE_IF_BIND_FAILS

This setting applies to shadow jobs only. When specified, the shadow job status is automatically set to SUCC if the bind with the remote job fails.

Comparison expression

Specifies the job return codes. The syntax is:

(RC operator operand)

RC

The RC keyword.

operator

Comparison operator. It can have the following values:

Table 2. Comparison operators
Example	Operator	Description
RC<a	<	Less than
RC<=a	<=	Less than or equal to
RC>a	>	Greater than
RC>=a	>=	Greater than or equal to
RC=a	=	Equal to
RC!=a	!=	Not equal to
RC<>a	<>	Not equal to

operand

An integer between -2147483647 and 2147483647.

For example, you can define a successful job as a job that ends with a return code less than or equal to 3 as follows:

rccondsucc "(RC <= 3)"

Boolean expression

Specifies a logical combination of comparison expressions. The syntax is:

comparison_expression operator comparison_expression

comparison_expression

The expression is evaluated from left to right. You can use parentheses to assign a priority to the expression evaluation.

operator

Logical operator. It can have the following values:

Table 3. Logical operators
Example	Operator	Result
expr_a and expr_b	And	TRUE if both expr_a and expr_b are TRUE.
expr_a or expr_b	Or	TRUE if either expr_a or expr_b is TRUE.
Not expr_a	Not	TRUE if expr_a is not TRUE.

For example, you can define a successful job as a job that ends with a return code less than or equal to 3 or with a return code not equal to 5, and less than 10 as follows:

rccondsucc "(RC≤3) OR ((RC≠5) AND (RC<10))"

recovery

Recovery options for the job. The default is stop with no recovery job and no recovery prompt. Enter one of the recovery options, stop, continue, or rerun. This can be followed by a recovery job, a recovery prompt, or both.

stop

If the job ends abnormally, do not continue with the next job.

continue

If the job ends abnormally, continue with the next job. The job is not listed as abended in the properties of the job stream. If no other problems occur, the job stream completes successfully.

rerun

If the job ends abnormally, rerun the job.

after [workstation#]jobname

Specifies the name of a recovery job to run if the parent job ends abnormally. Recovery jobs are run only once for each abended instance of the parent job.

You can specify the recovery job's workstation if it is different from the parent job's workstation. The default is the parent job's workstation. Not all jobs are eligible to have recovery jobs run on a different workstation. Follow these guidelines:

If either workstation is an extended agent, it must be hosted by a domain manager or a fault-tolerant agent with a value of on for fullstatus.
The recovery job workstation can be in the same domain as the parent job workstation or in a higher domain.
If the recovery job workstation is a fault-tolerant agent, it must have a value of on for fullstatus.

abendprompt “text”

Specifies the text of a recovery prompt, enclosed in double quotes, to be displayed if the job ends abnormally. The text can contain up to 64 characters. If the text begins with a colon (:), the prompt is displayed, but no reply is required to continue processing. If the text begins with an exclamation mark (!), the prompt is displayed, but it is not recorded in the log file. You can also use Tivoli Workload Scheduler parameters.

See Using variables and parameters in job definitions for more information.

Table 4 summarizes all possible combinations of recovery options and actions.

The table is based on the following criteria from a job stream called sked1:

Job stream sked1 has two jobs, job1 and job2.
If selected for job1, the recovery job is jobr.
job2 is dependent on job1 and does not start until job1 has completed.

Table 4. Recovery options and actions
	Stop	Continue	Rerun
Recovery prompt: No Recovery job: No	Intervention is required.	Run `job2`.	Rerun `job1`. If `job1` ends abnormally, issue a prompt. If reply is yes, repeat above. If `job1` is successful, run `job2`.
Recovery prompt: Yes Recovery job: No	Issue recovery prompt. Intervention is required.	Issue recovery prompt. If reply is yes, run `job2`.	Issue recovery prompt. If reply is yes, rerun `job1`. If `job1` ends abnormally, repeat above. If `job1` is successful, run `job2`.
Recovery prompt: No Recovery job: Yes	Run `jobr`. If it ends abnormally, intervention is required. If it is successful, run `job2`.	Run `jobr`. Run `job2`.	Run `jobr`. If `jobr` ends abnormally, intervention is required. If `jobr` is successful, rerun `job1`. If `job1` ends abnormally, issue a prompt. If reply is yes, repeat above. If `job1` is successful, run `job2`.
Recovery prompt: Yes Recovery job: Yes	Issue recovery prompt. If reply is yes, run `jobr`. If it ends abnormally, intervention is required. If it is successful, run `job2`.	Issue recovery prompt. If reply is yes, run `jobr`. Run `job2`.	Issue recovery prompt. If reply is yes, run `jobr`. If `jobr` ends abnormally, intervention is required. If `jobr` is successful, rerun `job1`. If `job1` ends abnormally, repeat above. If `job1` is successful, run `job2`.

Notes:

"Intervention is required" means that job2 is not released from its dependency on job1, and therefore must be released by the operator.
The continue recovery option overrides the ends abnormally state, which might cause the job stream containing the ended abnormally job to be marked as successful. This prevents the job stream from being carried forward to the next production plan.
If you select the rerun option without supplying a recovery prompt, Tivoli Workload Scheduler generates its own prompt.
To reference a recovery job in conman, use the name of the original job (job1 in the scenario above, not jobr). Only one recovery job is run for each abnormal end.

Examples

The following is an example of a file containing two job definitions:

$jobs
cpu1#gl1
     scriptname "/usr/acct/scripts/gl1"
     streamlogon acct
     description "general ledger job1"
bkup
     scriptname "/usr/mis/scripts/bkup"
     streamlogon "^mis^"
     recovery continue after recjob1

The following example shows how to define the Tivoli Workload Scheduler TWSJOB job that manages the workload broker broker_1 job that runs on the same workload broker agent where the TWSJOB2 ran:

ITDWBAGENT#TWSJOB
SCRIPTNAME "broker_1 -var var1=name,var2=address
            -twsaffinity jobname=TWSJOB2" 
STREAMLOGON brkuser
DESCRIPTION "Added by composer."
TASKTYPE BROKER
RECOVERY STOP

The following example shows how to define a job which is assigned to a dynamic pool of UNIX agents and runs the df script:

DPOOLUNIX#JOBDEF7
 TASK
    <?xml version="1.0" encoding="UTF-8"?>
    <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">
    <jsdl:application name="executable">
    <jsdle:executable interactive="false">
    <jsdle:script>df</jsdle:script>
    </jsdle:executable>
    </jsdl:application>
    </jsdl:jobDefinition>
 DESCRIPTION "Added by composer."
 RECOVERY STOP

The following example shows how to define a job which is assigned to a dynamic pool of Windows agents and runs the dir script:

DPOOLWIN#JOBDEF6
 TASK
    <?xml version="1.0" encoding="UTF-8"?>
    <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">
    <jsdl:application name="executable">
    <jsdle:executable interactive="false">
    <jsdle:script>dir</jsdle:script>
    </jsdle:executable>
    </jsdl:application>
    </jsdl:jobDefinition>
 DESCRIPTION "Added by composer."
 RECOVERY STOP

The following example shows how to define a job which is assigned to the NC115084 agent and runs the dir script:

NC115084#JOBDEF3
 TASK
    <?xml version="1.0" encoding="UTF-8"?>
    <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">
    <jsdl:application name="executable">
    <jsdle:executable interactive="false">
    <jsdle:script>dir</jsdle:script>
    </jsdle:executable>
    </jsdl:application>
    </jsdl:jobDefinition>
 DESCRIPTION "Added by composer."
 RECOVERY STOP

The following example shows how to define a job which is assigned to a pool of UNIX agents and runs the script defined in the script tag:

POOLUNIX#JOBDEF5
 TASK
    <?xml version="1.0" encoding="UTF-8"?>
    <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">
    <jsdl:application name="executable">
    <jsdle:executable interactive="false">
    <jsdle:script>#!/bin/sh
sleep 60
dir</jsdle:script>
    </jsdle:executable>
    </jsdl:application>
    </jsdl:jobDefinition>
 DESCRIPTION "Added by composer."
 RECOVERY STOP

The following example shows how to define a job which is assigned to a pool of Windows agents and runs the script defined in the script tag:

POOLWIN#JOBDEF4
 TASK
    <?xml version="1.0" encoding="UTF-8"?>
    <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">
    <jsdl:application name="executable">
    <jsdle:executable interactive="false">
    <jsdle:script>ping -n 120 localhost</jsdle:script>
    </jsdle:executable>
    </jsdl:application>
    </jsdl:jobDefinition>
 DESCRIPTION "Added by composer."
 RECOVERY STOP

Job definition

Syntax

Arguments

Examples

See also