Vous êtes sur la page 1sur 81

IBM Software Group

IBM Tivoli Workload Scheduler TWSD jobmanrc, .jobmanrc and djobmanrc.cmd Options Files

Pete Soto Jr

2006 IBM Corporation

IBM Software Group | Tivoli software

Abstract
This session discusses the use of jobmanrc, .jobmanrc and Windows djobmanrc (new) option files. It will focus on:
Optional Windows djobmanrc file concept Differences between jobmanrc, .jobmanrc and djobmanrc.cmd files Jobmanrc limitations on Windows The different configuration options in jobmanrc Customizing Windows and UNIX jobmanrc, including mail on abend for UNIX and Windows (new user customizable option) and djobmanrc (Windows only)

Using Mail_On_Abend to perform other tasks beside emails when a job abends.
When should you use a .jobmanrc or djobmanrc

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

jobmanrc, .jobmanrc and djobmanrc.cmd


The jobmanc file is used to setup the environment for all jobs that will launch on a local TWS instance. A jobmanrc files exists on UNIX and Windows but the Windows version has limited functionality. The jobmanrc created by the TWS install must exist while the .jobmanrc is optional.

The .jobmanrc exists only on UNIX.


The .jobmanrc file is used to setup the environment for jobs that will launch for a specific user on a local TWS instance. The .jobmanrc is similar to the UNIX .profile. The jobmanrc and .jobmanrc files must be executable. djobmanrc.cmd is an user created optional file that can be created on Windows workstations to setup the environment for jobs that will launch for a specific user on a local TWS instance. djomanrc.cmd file is necessary for sending emails to the logon user if a job abends on Windows. The djobmanrc.cmd will be similar to the UNIX .jobmanrc and requires customizing the Windows jobmanrc.cmd file.

NOTE: Settings in jobmanrc will apply to all jobs that are launched by TWS. These are global settings for the local cpu. Settings in .jobmanrc (UNIX only) or djobmanrc.cmd (Windows) will only apply to the logon user.

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group

Windows jobmanrc
TWS Local Configuration Script

2006 IBM Corporation

IBM Software Group | Tivoli software

Windows jobmanrc
Jobmanrc on Windows does not have customizable options like the jobmanrc for UNIX.
Jobmanrc for Windows should be customized so batch jobs that may interact with other Windows applications work correctly. Jobmanrc for Windows may be customized to invoke a users environment prior to launching a job by creating and invoking the djobmanrc.cmd file (discussed later) or to send emails when jobs abend. Note: The "interactive" box may need to be checked in the TWS job definition window for some types of jobs.

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Standard Windows jobmanrc


@ECHO OFF rem message set id set MAE_COPYRIGHT_SET=234 rem messge ids. set COPYRIGHT_CONST=1 set HOME=c:\win32app\TWS\pete set POSIXHOME=/win32app/TWS/pete rem set MECHO=%HOME%\bin\mecho defect 158633 (not needed) set VERSION=8.2.1 set BANNER=TWS for Windows NT/JOBMANRC.CMD %VERSION% echo %BANNER% rem %MECHO% %MAE_COPYRIGHT_SET% %COPYRIGHT_CONST% defect 158633 (not needed) if "%1" == "-V" goto version goto getargs :version echo $Revision: 1.6 $ goto out :getargs set ARGS=%1 %2 %3 %4 %5 %6 %7 %8 %9 :loop shift if "%9" == "" goto done set ARGS=%ARGS% %9 goto loop :done REM This is where environment can be customized call %ARGS% :out

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Windows jobmanrc Customized


Jobmanrc suggested minimum requirements: 1) Add a "set PATH" statement that includes the path to the Windows TWSHome directory on line after REM This is where environment can be customized. The Path statements will apply to Windows 2003, Windows XP, or Windows 2000 environments. Setting the PATH variable permits executing TWS commands from within batch files or scripts with out having to fully qualify the path of the command. REM This is where environment can be customized

set PATH=TWS_Home;%PATH%
2) Replace call %ARGS% with %ARGS% Original syntax: call %ARGS% Suggested syntax: %ARGS% Note: 1) If "call %ARGS%" is kept as is, then the DOS interpreter will be used. Therefore, eight character directory names are required in any path statements. Example: Directory name progra~1 will need to be used for the Program Files directory 2) If "call %ARGS%" is modified to just "%ARGS%", the NT command interpreter is used and there is no eight character limitation.

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Windows jobmanrc Customized


TWS 8.2 and TWS 8.2.1 include a feature that allows you to specify in each job definition additional return (exit) code(s) that will be considered a success. A sample of the syntax is: rccondsucc "(RC=3) OR ((RC>=5) AND (RC<10)) rccondsucc "(RC <= 3) Note: Refer to Managing Scheduling Objects for jobs in the Reference Guide for more detailed discussion. Jobmanrc may be customized for common return codes that will always need to be considered as successful, minimizing the number of job definitions that need to use the above customization.

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Windows jobmanrc Customized


The following section could be added to define additional return codes that will be considered as success. Below is syntax that can be added after either CALL %ARGS% or %ARGS% line. %ARGS% REM ***Additional successful Return Codes*** REM ***This is where non-zero return code is customized *** set RETVAL=%ERRORLEVEL% if %RETVAL%==0 goto out if %RETVAL%==1 set RETVAL=0 if %RETVAL%==6 set RETVAL=0 .. .. goto out :out exit %RETVAL%

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Windows jobmanrc Customized


@ECHO OFF rem message set id set MAE_COPYRIGHT_SET=234

rem messge ids. set COPYRIGHT_CONST=1


set HOME=c:\win32app\TWS\pete set POSIXHOME=/win32app/TWS/pete rem set MECHO=%HOME%\bin\mecho defect 158633 (not needed) set VERSION=8.2.1 set BANNER=TWS for Windows NT/JOBMANRC.CMD %VERSION% echo %BANNER% rem %MECHO% %MAE_COPYRIGHT_SET% %COPYRIGHT_CONST% defect 158633 (not needed) if "%1" == "-V" goto version goto getargs :version echo $Revision: 1.6 $ goto out :getargs set ARGS=%1 %2 %3 %4 %5 %6 %7 %8 %9 :loop shift if "%9" == "" goto done set ARGS=%ARGS% %9 goto loop :done REM This is where environment can be customized

set PATH=TWS_Home;%PATH%
call %ARGS%

REM ***Additional successful Return Codes*** REM ***This is where non-zero return code is customized *** set RETVAL=%ERRORLEVEL if %RETVAL%==0 goto out if %RETVAL%==1 set RETVAL=0 if %RETVAL%==6 set RETVAL=0 goto out :out exit %RETVAL%

10

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group

djobmanrc.cmd
TWS User Configuration Script

2006 IBM Corporation

IBM Software Group | Tivoli software

Djobmanrc Concept
Djobmanrc.cmd is a user created file used to invoke a Window users environment before launching a job via Tivoli Workload Scheduler.
This concept is similar to the Tivoli Workload Scheduler for UNIX .jobmanrc and should work on any supported Tivoli Workload Scheduler version. Invoking a users environment is necessary so that Tivoli Workload Scheduler is aware of any paths or variables unique to a user or application before launching a Tivoli Workload Scheduler job. A common issue is that a script, binary or command may work if executed on the workstation as the user but may not work if executed via Tivoli Workload Scheduler. The djobmanrc.cmd option may resolve this issue on some applications by specifying the path for the application but may not work if applications use settings that exist in the Windows registry.

12

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

djobmanrc.cmd Implementation
Implementing will require creating a new script (wrapper) called djobmanrc.cmd and editing (discussed later) the Tivoli Workload Scheduler jobmanrc.cmd file. jobmanrc.cmd file, which is located in the Tivoli Workload Scheduler Home directory, will launch the djobmanrc.cmd (if it exists in the users Documents and Settings directory) provided that the option LOCAL_RC_OK= is set to YES (case sensitive) in the edited jobmanrc.cmd file. The djobmanrc.cmd will setup the specified user environment and then launch the defined job script, binary or command. The djobmanrc.cmd file should contain all environment variables necessary for Tivoli Workload Scheduler jobs to launch correctly. Implementing djobmanrc.cmd should be performed on a test or development workstation first before implementing on a production workstation. This is suggested because the jobmanrc.cmd file is used to launch all jobs on a workstation. If the jobmanrc.cmd is compromised then jobs may fail or abend.

13

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

djobmanrc.cmd Creation
To create a djobmanrc.cmd you must do the following:

1) Logon as user that will be source of environment variables for launching Tivoli Workload Scheduler jobs.
2) Open a DOS window. 3) Issue the following command: set > flatfilename 4) Create a file called djobmanrc.cmd in the users Document and Settings directory. The file should have the following text (See Example Below) at the beginning of the file:

14

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Contd djobmanrc.cmd Creation


5) Edit the file generated from step 3.
6) Insert the text set on each line before each variable. The text should look something like the following:

15

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Contd djobmanrc.cmd Creation


7) Add the edited text from step 6 to the end of the djobmanrc.cmd file. The djobamnrc file should look like the following:

16

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Contd djobmanrc.cmd Creation


8) The following text should be added to the end of the djobmanrc.cmd file after all the set variables lines.

9) The created djobamanrc.cmd file should look similar to the following:

17

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Sample djobmanrc.cmd File

18

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Editing jobmanrc.cmd File


The jobmanrc.cmd file exists in the Tivoli Workload Scheduler home directory. Make a backup copy of the original jobmanrc.cmd before making the following changes: 1) Edit and insert before line if x%1x == x-Vx goto version line, the following text shown below. This option permits the execution of djobmanrc.cmd if the file exists in the users documents and settings directory.

Note: Value in LOCAL_RC_OK is case sensitive, use uppercase.

19

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Editing jobmanrc.cmd File


2) After the line REM This is where environment can be customized remove call%ARGS% line and insert the following text as shown below:

3) The edited Tivoli Workload Scheduler 8.3 Windows jobmanrc.cmd should look like the following:

20

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Edited jobmanrc.cmd File

21

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Cond Edited jobmanrc.cmd File

22

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Editing jobmanrc.cmd File


4) Submit a test job to verify that the setting are invoked. conman sbd set;logon=username
5) The job stdlist should display the variables that were defined in the djobmanrc.cmd file.

23

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group

Optional Windows jobmanrc.cmd Customizing

2006 IBM Corporation

IBM Software Group

MAIL_ON_ABEND

2006 IBM Corporation

IBM Software Group | Tivoli software

MAIL_ON_ABEND for Windows


Normally MAIL_ON_ABEND is used to send an email when a job abends. This concept already exists on UNIX but was not available for Windows. Use of the MAIL_ON_ABEND option requires use of a users local workstation email program. This function can be added by user to Windows with some editing of the Windows jobmanrc.cmd file provided that the user has access to an email program that can be invoked from a batch file. Tivoli Workload Scheduler does not provide the email program to use. The user will need to acquire the email program to use the MAIL_ON_ABEND option. The example presented here uses a freeware email application called Bmail from Copyright(C) 2002-2004 Craig.Peacock@beyondlogic.org. Customizing suggestion is generic, specific email syntax will depend on the email application. The concept has generic procedures and syntax that can be used to integrate the email feature. L2 will not provide support on using the users email program.

26

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Email Options
The user will need to determine who will receive emails when a job abends. This is necessary to determine which files and options must be created, edited or added.
Emails can be sent to: 1) A specific user when any job abends. This will require that EMAIL_ID= user_email be added as a variable in the jobmanrc.cmd. 2) Job logon user. This will require editing the jobmanrc.cmd, create a djobmanrc.cmd and include set EMAIL_ID= user_email@domain.com as a variable after the last set line of the djobmanrc.cmd file and before the %ARGS% line. Using the MAIL_ON_ABEND option requires editing the jobmanrc.cmd file.

27

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

MAIL_ON_ABEND Option
The value in variable MAIL_ON_ABEND determines the task performed if a job abends. The task can be customized to fit user specific requirements (discussed later).

The MAIL_ON_ABEND value will be used as an email id if set to anything other than YES or NO and ignore the value specified for EMAIL_ID. The value for variable EMAIL_ID option will be user that will receive email for any job that abends. It may also serve as a default id. If the logon user needs to receive email for and abended job then the djobmanrc.cmd file must be created and include the EMAIL_ID= user_email@domain.com as a variable.

28

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

MAIL_ON_ABEND Sample Functions

29

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

MAIL_ON_ABEND Sample Functions


The following syntax shows what can be done when a job abends and MAIL_ON_ABEND is yes. If the exit error code is 5, it will call the email function. If the exit error code is 1, it will call the task function. If none of the above apply it will issue the DOS set command and redirect the output to a file called c:\tmp\abend_jobs\%UNISON_JOB%.j%UNISON_JOBNUM% Where: UNISON_JOB is the fully qualified job name cpu#sched.job UNISON_JOBNUM is the job number (ppid) You can also remove the above three lines and just have goto :email.

30

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

MAIL_ON_ABEND Sample Functions


The email_gen function has two call options, email and task function. The email option will send an email to user specified in the EMAIL_ID variable. The below syntax is using freeware software Bmail and syntax is specific to Bmail. Any email may be specified in this function. The email function can also be used execute any command or binary like submit and adhoc TWS job via the conman command. The task function below is issuing set command and re-directing output to a flat file.

31

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

MAIL_ON_ABEND Sample Functions


If MAIL_ON_ABEND is not set to YES or NO, value for MAIL_ON_ABEND is assumed to be a valid email and the function email_spec will be executed.

Note: The email syntax in above example will be sent to the value in MAIL_ON_ABEND.

32

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group

Implementing Basic MAIL_ON_ABEND using Single email id

2006 IBM Corporation

IBM Software Group | Tivoli software

Editing jobmanrc.cmd File


The jobmanrc.cmd file exists in the Tivoli Workload Scheduler home directory. Make a backup copy of the original jobmanrc.cmd before making the following changes: 1) Edit and insert before line if x%1x == x-Vx goto version line, the following text shown below:

Note: The variable EMAIL_ID option is suggested and should be a default user that will receive emails when jobs abend if an email application exists. This concept will be discussed in more detail later.

34

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Editing jobmanrc.cmd File


2) Insert the text after either the call %ARGS% or if "%LOCAL_RC%"==YES" (call "%USERPROFILE%\djobmanrc.cmd") else (%ARGS%) line (if using djobmanrc.cmd) but before the :out line:

The RETVAL captures the ERRORLEVEL (exit error code) of the job which is used to determine if the job is SUCC or ABEND. If job abends, function will determine if the MAIL_ON_ABEND option is set to YES to determine next function to call. The following function calls can be edited to fit specific needs or requirements. Since the jobmanrc.cmd is being customized changes will affect all job launches.

35

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Editing jobmanrc.cmd File


3) Add the following text after text added in step 2. The following specifies functions executed based on the MAIL_ON_ABEND setting.

Note: The EMAIL_ID variable must exist and have a valid email id. The above example for email uses a freeware application called Bmail from Copyright(C) 2002-2004 Craig.Peacock@beyondlogic.org. This section can be changed to use any email program that can be executed from a batch file.

36

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Editing jobmanrc.cmd File


The following example is for MAIL_ON_ABEND using djobmanrc.cmd. If djobmanrc.cmd is not used remove first line and uncomment the second line.

37

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group

Implementing Basic MAIL_ON_ABEND using logon user email id

2006 IBM Corporation

IBM Software Group | Tivoli software

MAIL_ON_ABEND With Logon User Email Id


Use of MAIL_ON_ABEND an logon user email id will require use of the djobmanrc.cmd (discussed previously). The necessary steps are: 1) Implement djobmanrc.cmd procedures. 2) Implement MAIL_ON_ABEND procedures. 3) Edit the djobmanrc.cmd file in the logon users Documents and Settings directory. 4) Insert the following text after the last set.. line and before the %ARGS% line: set EMAIL_ID=user_email@domain.com Where: user_email@domain.com is the email id for job logon user. Note: This value will over-ride the value specified for EMAIL_ID in the MAIL_ON_ABEND option in jobmanrc.

39

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

MAIL_ON_ABEND using djobmanrc.cmd and email_id


Edited djobmanrc.cmd with email_id.

40

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Edited jobmanrc.cmd

41

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Contd Edited jobmanrc.cmd

42

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Contd Edited jobmanrc.cmd

43

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group

UNIX jobmanrc
TWS Local Configuration Script

2006 IBM Corporation

IBM Software Group | Tivoli software

UNIX Jobmanrc
The jobmanrc consists of several environmental variables that determine the operation of TWS and how it launches jobs.
Since the jobmanrc setups up the environment for all jobs that launch via TWS, any customization may impact the operation of TWS. Changes to this file should be evaluated after it has been customized. Under normal circumstances the file may not require customization. The MAIL_ON_ABEND variable for UNIX will be the only one that may need to be customized.

45

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

USE_EXEC Variable

# VARIABLE #

: USE_EXEC

# USE_EXEC is used to eliminate extra shell processes. If it is set # to "YES" the exec command will be used to start the script. If a # sub-shell is requested (see SHELL_TYPE), the shell being used will # be exec'ed. If a local jobmanrc file is used exec will be used # there as well. Certain options will override this one, such as # MAIL_ON_ABEND being set to anything but "NO". # # DEFAULT : "YES" # CRON Equivalent : "YES" USE_EXEC="YES"

46

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

USE_EXEC Basics
USE_EXEC ito eliminate extra shell processes
If USE_EXEC is set to "YES" the exec command will be used to start the script. Setting USE_EXEC to NO will invoke an additional shell process to execute the job. Normally you would like to limit the number of processes that run so setting to YES is not efficient, but is an option that is available.

47

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

UNISON_EXIT Variable
# VARIABLE : UNISON_EXIT # # UNISON_EXIT is used to set the behavior of the script in case of an # error occuring. If UNISON_EXIT is set to "YES" then the first # command which returns a non-zero exit code in the script will cause # the script to terminate. The script would then return the same exit # code as the command which resulted in the "abend". Setting # UNISON_EXIT to "NO" will result in the script continuing after a # command returns a non-zero exit code. All other values are # equivalent to "NO". # # DEFAULT : "NO" # CRON Equivalent : "NO" UNISON_EXIT="NO"

48

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

UNISON_EXIT Basics
Setting UNISON_EXIT to YES will cause a job to abend as soon as a non-zero return code is encountered within the script thus causing a script to exit prematurely.
Since scripts consist of several tasks or commands that must be processed, getting a non-zero return code may be normal. The script may have internal checks for non-zero return codes and perform additional routines. Since this setting will be applied to all jobs on the local TWS instance this should not be changed from the default of UNISON_EXIT=NO.

49

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

LOCAL_RC_OK Variable

# VARIABLE : LOCAL_RC_OK # # LOCAL_RC_OK is used to allow or disallow the use of local .jobmanrc # files by individual users. If LOCAL_RC_OK is set to "YES" and there # is a .jobmanrc file in $HOME it will be executed passing $UNISON_JCL # as its first argument. If LOCAL_RC_OK is set to "NO" the presence # of a .jobmanrc is ignored and $UNISON_JCL is executed directly. # Setting LOCAL_RC_OK to any other value is equivalent to "NO". # # DEFAULT : "YES" # CRON Equivalent : "NO" # Restrictions : The logon user must have read and execute # access to .jobmanrc

50

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

LOCAL_RC_OK Logic
LOCAL_RC_OK="YES" if [ "$LOCAL_RC_OK" = "YES" ] then if [ -f $UNISON_DIR/localrc.allow ] then if grep $LOGNAME $UNISON_DIR/localrc.allow >/dev/null; then echo else LOCAL_RC_OK="NO" fi elif [ -f $UNISON_DIR/localrc.deny ] then if grep $LOGNAME $UNISON_DIR/localrc.deny >/dev/null; then LOCAL_RC_OK="NO" fi fi fi

if [ "$LOCAL_RC_OK" = "YES" ] then if [ -x .jobmanrc ] then LOCAL_RC_OK="YES" else LOCAL_RC_OK="NO" fi fi

51

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

LOCAL_RC_OK Basics
This module will determine if an existing .jobmanrc in a users home directory is executed. Note: It does not check to see if the .jobmanrc is executable.

If the file maestrohome/localrc.allow exists, the users name must appear in the file.
If the allow file does not exist, the users name must not appear in the file, maestrohome/localrc.deny. If neither of these files exists, the user is permitted to use a local configuration script.
if [ -f $UNISON_DIR/localrc.allow ] then if grep $LOGNAME $UNISON_DIR/localrc.allow >/dev/null; then echo else LOCAL_RC_OK="NO" fi elif [ -f $UNISON_DIR/localrc.deny ] then if grep $LOGNAME $UNISON_DIR/localrc.deny >/dev/null; then LOCAL_RC_OK="NO" fi fi

52

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

MAIL_ON_ABEND Variable

# VARIABLE : MAIL_ON_ABEND # # MAIL_ON_ABEND is used to cause a message to be mailed when a job # fails to run correctly (returns a non-zero exit code). Setting # MAIL_ON_ABEND to "YES" will cause a message to be mailed to the # mailbox for the logon user. This message will indicate the name of # the stdlist file to be examined to determine the cause of the # failure. Setting it to "NO" will skip the mail step. Any other # value will be considered to be a user id to mail output to. A list # could be specified if several users should be notified. # # DEFAULT : "NO" # CRON Equivalent : "YES" MAIL_ON_ABEND="NO"

53

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Mail On Abend Basics


The Mail on Abend is area of the jobmanrc where you define that an email be sent when any job abends in TWS. Though the section is called mail_on_abend, other tasks may be executed when a job abends (Discussed later, in more detail).

Tasks that may be executed include: 1) Send an email 2) Send a page (provided CPU is UNIX and includes access to a modem) 3) Send a text message to a pager or cell phone 4) Execute a third party application that has a command line interface 5) Execute any command, script or binary
Note: The Mail on Abend option will apply to all jobs on the local cpu.

54

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

MAIL_ON_ABEND Logic
This section sends an email to user. The user that will receive the email will depend on the value assigned to the MAIL_ON_ABEND variable.

If MAIL_ON_ABEND is YES then the email will be sent to the job logon user If MAIL_ON_ABEND is ROOT then the email will be sent to the root user If MAIL_ON_ABEND is a value other than NO then the it will assume that value specified is a valid user and send them the email.
55

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

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

SHELL_TYPE Variable
# VARIABLE : SHELL_TYPE # # SHELL_TYPE is used to configure the method of executing the job # script ($UNISON_JCL). Setting it to "STANDARD" will cause the # script to be executed with the shell specified in the first line of # the script (or "/bin/sh" if none is there) echoing commands to the # standard list. This is the most "MPE-like" option. Setting it to # "USER" will cause the script to be executed with $UNISON_SHELL # echoing commands to the standard list. This is only slightly less # "MPE-like" then "STANDARD". Using "SCRIPT" will cause the script to # be executed as directly using the standard shell protocol for # determining which shell to use. This last option will not echo # commands to the standard list; only output from the commands will be # shown. This is the mose "CRON-like" option. Any other value is # equivalent to "STANDARD". # # DEFAULT : "SCRIPT" # CRON Equivalent : "SCRIPT" SHELL_TYPE="SCRIPT"

56

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

SHELL_TYPE Basics
SHELL_TYPE defines how a job script is executed
If SHELL_TYPE is "STANDARD, script will be executed with the shell specified in the first line of the script (or use "/bin/sh" if no shell is specified) echoing commands to the standard list.

If SHELL_TYPE is "USER, the script will be executed with the value in $UNISON_SHELL echoing commands to the standard list.
If SHELL_TYPE is "SCRIPT, the script will be executed using the standard shell protocol for determining which shell to use. This last option will not echo commands to the standard list, but echo only the output from the commands. Note: Any other value is equivalent to "STANDARD".

57

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group

Abend Notification
Notify when jobs abend

2006 IBM Corporation

IBM Software Group | Tivoli software

Notification Types
Notification of abended jobs can be via: 1) pager 2) email 3) Cell phone text message 4) Other third party applications that have a command line interface. 5) Recovery job that executes any of the above.

59

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Notification Paging (UNIX)


Commands can be used to page someone. Using UNIX commands require that a modem exists and that it is connected to a phone line
This solution uses a specific system device, please identify the correct device name for the com port.

Solution 1: echo ATDT########@TTTTTTT >> /dev/cua/b Where ####### = pager number TTTTTTT= text to send to pager /dev/cua/b = serial port on UNIX system

61

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Notification Email Examples(UNIX)


The following will email the job stdlist to the logon user of a TWS job:
Example 1: trap '(echo "mailing...stdlist to $LOGNAME"; sleep 30; mailx -s TWS job $UNISON_JOB" $LOGNAME < $UNISON_STDLIST) & '0 Or Example 2: trap '(mailx -s TWS job $UNISON_JOB Job Number $UNISON_JOBNUM abended" johnsmith@domain_name.com < $UNISON_STDLIST) & ' 0

63

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Notification Cell Phone Text Message (UNIX or Windows)


Mail on Abend function can be used to send text messages to a cell phone when a job abends. The amount of data that can be sent will depend on the carrier and the cell phone. Many cellular carriers assign email addresses to cellular phone numbers and support SMS or text messaging by email. The recipient will need text messaging enabled on their cellular plan and have a phone capable of receiving text messages To use, compose a short email message using less than 160 total characters and address it to the cellular number at the carrier's email domain. Remember to remove your signature from the message before sending. Phones only support plain text messages.

64

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Cell Phone Carriers Text Message Domains


The major US cellular carriers use the 10_digit_number@cell.carrier_domain.com format for SMS to text capable cell phones, with a limit of 160 characters in the subject and message body (total). You will need to determine limitations of what may be used in the subject and body of the email for the respective carrier. Carrier Alltel Cingular Nextel Sprint SunCom T-mobil VoiceStream Verizon Send Email to phonenumber@.... @message.alltel.com @cingularme.com @messaging.nextel.com @messaging.sprintpcs.com @tms.suncom.com @tmobil.net @voicestream.net @vtext.com

There is a list of most US carriers and the address format supported at http://www.aipcom.com/support/email-finder.asp

65

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

TWS variables
Below are some of the variables that exist for TWS jobs that may be used in the notification. This list is obtained by issuing the UNIX env or Windows set command via a TWS job.
HOME - Login users home directory LOGNAME - Login user MAEHOME TWS home directory TIVOLI_JOB_DATE Day job ran UNISON_CPU Name of the local cpu UNISON_DIR - TWS home directory UNISON_HOST The name of the host cpu UNISON_JCL Command or script that executes UNISON_JOB The fully qualified job name: cpu#job_stream.job UNISON_JOBNUM Job number (For UNIX, pid ) UNISON_MASTER The name of master domain manager UNISON_RUN TWS current production run number UNISON_SCHED_DATE TWSs production date: yyyymmdd UNISON_SCHED_EPOCH TWSs production date expressed in epoch form UNISON_SCHED The schedule name for job UNISON_SHELL The users login shell UNISON_STDLIST - The fully qualified path for the job stdlist: TWSHome/stdlist/yyyy.mm.dd/Ojobnum.hhmm

66

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Notification Third Party Applications (UNIX or Windows)


Other applications may be executed when jobs abend provided that they have a command line interface.
Since TWS can execute one or more commands when a job abends, it is capable of running an application that can be executed via command line interface. Possible options: Applications that generate trouble tickets. Applications that trap events written to a log configured by BmEvents.conf file (Please refer to Integration with Other Products in the ITWS Reference Guide for further discussion.)

67

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Notification Recovery job


When a job is created, an option exists that allows you to specify a recovery job that will launch when the job abends.
The recovery job can used to execute a script that executes any of the previous notification options discussed earlier. The only requirement for the recovery job is that it the script must abend once it has executed the defined task. This is necessary so that the recovery job will abend and be flagged as ABEND, otherwise the recovery job will be flagged as SUCC and the original job that abended will be also be flagged as SUCC.

68

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Implementing Notification
Notification for abended jobs can be implemented via: Jobmanrc Notification will be sent when any job abends if MAIL_ON_ABEND option exists and set to YES.

.jobmanrc Notification will be sent when jobs that logon on as a specific user abend.
djobmanrc.cmd Notification will be sent when jobs that logon on as a specific user abend provided MAIL_ON_ABEND option has been added to jobmanrc and EMAIL_ID variable and value exists in djobmanrc.cmd. Recovery Job Notification will be sent when specific jobs abend.

69

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Notification jobmanrc Configuration (UNIX)


The following changes must be made to jobmanrc for emailing of message of abended jobs. # VARIABLE : MAIL_ON_ABEND # # MAIL_ON_ABEND is used to cause a message to be mailed when a job # fails to run correctly (returns a non-zero exit code). Setting # MAIL_ON_ABEND to "YES" will cause a message to be mailed to the # mailbox for the logon user. This message will indicate the name of # the stdlist file to be examined to determine the cause of the # failure. Setting it to "NO" will skip the mail step. Any other # value will be considered to be a user id to mail output to. A list # could be specified if several users should be notified. # # DEFAULT : "NO" # CRON Equivalent : "YES" MAIL_ON_ABEND="YES #The above value must have a "YES, ROOT or a valid user instead of a "NO to invoke mail on abend.

70

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Notification Original jobmanrc (UNIX)


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

71

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Notification Modified Jobmanrc Example


When jobmanrc is set to YES it will perform the task specified when a job abends. # Perform xxxxxx if the job fails. if [ "$MAIL_ON_ABEND" = "YES" ] then # if [ $UNISON_RETURN -ne 0 ] then **Notification Task** fi .. ..

72

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

MAIL_ON_ABEND Basics
The default options for MAIL ON ABEND will send email to the logon user If ABEND is set to YES.
If ABEND is set to ROOT (UNIX only )then the email will be sent to the root user.

If the option is anything else other than NO then it will treat the option as a user id and email them that the job has abended.
The action that is preformed when an abend occurs can be customized to perform any action/task.

NOTE: Settings in jobmanrc will apply to all jobs that are launched by TWS. These are global settings for the local cpu. Use will .jobmanrc will only apply to the logon user.

73

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group

.jobmanrc
TWS User Configuration Script

2006 IBM Corporation

IBM Software Group | Tivoli software

.jobmanrc Basics
The .jobmanrc (UNIX only) is used to setup the environment for the TWS user. This is necessary when a specific environment must exist for the user when executing a job.
Since a TWS job consists of script, binary or command that is executed, TWS must be aware of the paths or environment variables for job to launch correctly. The .jobmanrc file must exist in the logon users home directory and must be executable. The .jobmanrc is very similar to the .profile for a UNIX user. The .profile may be used as a base for creating a .jobmanrc.

75

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

.jobmanrc Requirements
The .jobmanrc must:
1) 2) 3) 4) 5) 6) 7) 8) Exist in the UNIX users home directory. Have execute permissions. Include the $PATH variable. Should include the TWSHome and TWSHome/bin directories as the first entries in the PATH variable. Must not contain any stty settings. Must not contain any syntax that requires a reply to a prompt. Must include the /bin/sh c $UNISON_JCL as the last line. Additional lines may be included it exit code handling will be used.

Note: Though the .jobmanrc is similar to the .profile, copying the .profile as .jobmanrc and just adding in the /bin/sh c $UNISON_JCL is not suggested unless it meets the above requirements.

76

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Notification - .jobmanrc Configuration


A variable must be set and an if condition must be included in the .jobmanrc to determine how to handle exit/return codes not equal to 0.
Example of a .jobmanrc (UNIX): # PATH=/usr/lib/TWS . . ./bin/sh -c "$UNISON_JCL" RETVAL=$? # Check for exit code if [ "$RETVAL" -ne 0 ] then trap '(echo "mailing...stdlist to $LOGNAME"; sleep 30; mailx -s "Maestro job $UNISON_JOB" $LOGNAME < $UNISON_STDLIST) & ' 0 fi exit $RETVAL

77

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

.jobmanrc Basics
The exit code is captured and stored along with the required action if a job abends. This logic must be specified after the following line: /bin/sh c $UNISON_JCL
The action must include an exit with the original exit code (see above example). The above notification sends an email to the logon user of the job if it abends. The email includes the job stdlist This maybe customized by the user to execute any notification task.

78

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Notification Sample Email


To: Pete Soto cc: Subject: TWS job M82#JOBS.HEHE Job # 1369 Abended =============================================================== = JOB : M82#JOBS.HEHE = USER : mae82 mae82,,, = JCLFILE : hehe = Job Number: 1369 = Wed 07/07/04 11:49:06 CDT =============================================================== TWS for UNIX/JOBMANRC 8.2 AWSBJA001I Licensed Materials Property of IBM 5698-WKB (C) Copyright IBM Corp 1998,2001 US Government User Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. AWSBIS307I Starting /tivbkups/maestro/mae82/maestro/jobmanrc hehe TWS for UNIX (HPUX)/JOBINFO 8.2 (9.4) Licensed Materials Property of IBM 5698-WKB (C) Copyright IBM Corp 1998,2001 US Government User Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Installed for user ''. Locale LANG set to "C" /tivbkups/maestro/mae82/maestro/jobmanrc[333]: hehe: not found. AWSBIS308I End of Job mailing...stdlist to XXXXX@us.ibm.com =============================================================== = Exit Status : 127 = System Time (Seconds) : 0 Elapsed Time (Minutes) : 0 = User Time (Seconds) : 0 = Wed 07/07/04 11:49:08CDT

===========================================================
79 STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

.jobmanrc Email Syntax


The previous email was generated with the following syntax in .jobmanrc:
trap '(echo "mailing...stdlist to XXXXX@us.ibm.com";sleep 30;mailx -s "TWS job $UNISON_JOB Job # $UNISON_JOBNUM Abended" XXXXX@us.ibm.com <$UNISON_STDLIST)& ' 0 Syntax is very important for the command, the single quote is used after the word trap and before the zero, all others are double quotes.

80

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group | Tivoli software

Jobmanrc and .jobmanrc Review


The jobmanc file is used to setup the environment for all jobs that will launch on a local TWS instance. A jobmanrc files exists on UNIX and Windows but the Windows version has limited functionality.

The jobmanrc created by the TWS install must exist while the .jobmanrc is optional.
The .jobmanrc exists only on UNIX. The djobmanrc.cmd can be created for Windows The .jobmanrc and djobamanrc.cmd files are used to setup the environment for jobs that will launch for a specific user on a local TWS instance provided that launching of .jobmanrc and djobmanrc.cmd is permitted. Jobmanc and .jobmanrc files must be executable. Notification for abended jobs can be via a task that can: 1) Send an email 2) Send a page (provided CPU is UNIX and includes access to a modem)e 3) Send a text message to a pager or cell phone 4) Execute a third party application that has a command line interface 5) Execute any command, script or binary

81

STE |

TWSd Jobmanrc and dJobmanrc

2007 IBM Corporation

IBM Software Group

Any Questions

??

email: sotope@us.ibm.com
TWS 8.2.1

2006 IBM Corporation

IBM Software Group

IBM Tivoli Workload Scheduler TWSD jobmanrc, .jobmanrc and djobmanrc.cmd Options Files

Pete Soto Jr

2006 IBM Corporation