tws

IBM Software Group

© 2006 IBM Corporation

Pete Soto Jr

IBM Tivoli Workload SchedulerTWSD jobmanrc, .jobmanrc and djobmanrc.cmd Options Files

IBM Software Group | Tivoli software

STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation2

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



jobmanrc, .jobmanrc and djobmanrc.cmdThe 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.

IBM Software Group


Windows jobmanrcTWS Local Configuration Script



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 user’s 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.



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



Windows jobmanrc – CustomizedJobmanrc 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.



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.



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 outif “%RETVAL%”==“1” set RETVAL=0if “%RETVAL%”==“6” set RETVAL=0....goto out

:outexit %RETVAL%



Windows jobmanrc – Customized@ECHO OFFrem message set idset MAE_COPYRIGHT_SET=234

rem messge ids.set COPYRIGHT_CONST=1

set HOME=c:\win32app\TWS\peteset POSIXHOME=/win32app/TWS/pete

rem set MECHO=%HOME%\bin\mecho defect 158633 (not needed)

set VERSION=8.2.1set 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 versiongoto getargs:versionecho $Revision: 1.6 $goto out

:getargsset ARGS=%1 %2 %3 %4 %5 %6 %7 %8 %9:loopshiftif "%9" == "" goto doneset ARGS=%ARGS% %9goto loop:done

REM This is where environment can be customizedset PATH=TWS_Home;%PATH%

call %ARGS%

REM ***Additional successful Return Codes***REM ***This is where non-zero return code is customized ***set RETVAL=%ERRORLEVELif “%RETVAL%”==“0” goto outif “%RETVAL%”==“1” set RETVAL=0if “%RETVAL%”==“6” set RETVAL=0goto out

:outexit %RETVAL%

IBM Software Group


djobmanrc.cmdTWS User Configuration Script



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 user’s 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.



djobmanrc.cmd ImplementationImplementing 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.



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:



Cont’d 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:




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




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:



Sample djobmanrc.cmd File



Editing jobmanrc.cmd FileThe 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 user’s “documents and settings” directory.

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



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:



Edited jobmanrc.cmd File



Con’d Edited jobmanrc.cmd File



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.

IBM Software Group


Optional Windows jobmanrc.cmd Customizing

IBM Software Group


MAIL_ON_ABEND



MAIL_ON_ABEND for WindowsNormally 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 user’s 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 [email protected].

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 user’s email program.



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= [email protected]” 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.



MAIL_ON_ABEND OptionThe 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= [email protected] as a variable.



MAIL_ON_ABEND Sample Functions



MAIL_ON_ABEND Sample FunctionsThe 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 andredirect 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.jobUNISON_JOBNUM is the job number (ppid)You can also remove the above three lines and just have goto :email.




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.




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.

IBM Software Group


Implementing Basic MAIL_ON_ABEND using Single email id



Editing jobmanrc.cmd FileThe 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.



Editing jobmanrc.cmd File2) 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.



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 [email protected]. This section can be changed to use any email program that can be executed from a batch file.



Editing jobmanrc.cmd FileThe following example is for MAIL_ON_ABEND using djobmanrc.cmd. If djobmanrc.cmd is

not used remove first line and uncomment the second line.

IBM Software Group


Implementing Basic MAIL_ON_ABEND using logon user email id



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 user’s “Documents and Settings”

directory. 4) Insert the following text after the last “set..” line and before the “%ARGS

%” line:set [email protected]

Where:[email protected] 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.



MAIL_ON_ABEND using djobmanrc.cmd and email_id

Edited djobmanrc.cmd with email_id.



Edited jobmanrc.cmd



Cont’d Edited jobmanrc.cmd

IBM Software Group


UNIX jobmanrcTWS Local Configuration Script



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.



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"



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.



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"



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



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



LOCAL_RC_OK LogicLOCAL_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 fifi

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



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 user’s name must appear in the file.

If the allow file does not exist, the user’s 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



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"



Mail On Abend BasicsThe “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 email2) Send a page (provided CPU is UNIX and includes access to a modem)3) Send a text message to a pager or cell phone4) Execute a third party application that has a command line interface5) Execute any command, script or binary

Note: The “Mail on Abend” option will apply to all jobs on the local cpu.



MAIL_ON_ABEND Logic

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.

# 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! fielif [ "$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! fielif [ "$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! fifi

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.



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"



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

IBM Software Group


Abend Notification Notify when jobs abend



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.



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/bWhere ####### = pager numberTTTTTTT= text to send to pager/dev/cua/b = serial port on UNIX system



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



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.



Cell Phone Carriers Text Message DomainsThe major US cellular carriers use the [email protected]_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 Send Email to phonenumber@.... Alltel @message.alltel.comCingular @cingularme.comNextel @messaging.nextel.com Sprint @messaging.sprintpcs.comSunCom @tms.suncom.comT-mobil @tmobil.netVoiceStream @voicestream.net Verizon @vtext.com

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



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 user’s home directoryLOGNAME - Login userMAEHOME – TWS home directoryTIVOLI_JOB_DATE – Day job ranUNISON_CPU – Name of the local cpuUNISON_DIR - TWS home directoryUNISON_HOST – The name of the host cpuUNISON_JCL – Command or script that executesUNISON_JOB – The fully qualified job name: cpu#job_stream.jobUNISON_JOBNUM – Job number (For UNIX, pid )UNISON_MASTER – The name of master domain managerUNISON_RUN – TWS current production run numberUNISON_SCHED_DATE – TWS’s production date: yyyymmddUNISON_SCHED_EPOCH – TWS’s production date expressed in epoch formUNISON_SCHED – The schedule name for jobUNISON_SHELL – The user’s login shellUNISON_STDLIST - The fully qualified path for the job stdlist:

TWSHome/stdlist/yyyy.mm.dd/Ojobnum.hhmm



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



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



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.



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.



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! fielif [ "$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! fielif [ "$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! fifi



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



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.

IBM Software Group


.jobmanrcTWS User Configuration Script



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



.jobmanrc Requirements

The .jobmanrc must:

1) Exist in the UNIX users home directory.

2) Have execute permissions.

3) Include the $PATH variable.

4) Should include the TWSHome and TWSHome/bin directories as the first entries in the PATH variable.

5) Must not contain any “stty” settings.

6) Must not contain any syntax that requires a reply to a prompt.

7) Must include the “/bin/sh –c $UNISON_JCL” as the last line.

8) 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.



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 codeif [ "$RETVAL" -ne 0 ]then

trap '(echo "mailing...stdlist to $LOGNAME"; sleep 30; mailx -s "Maestro job $UNISON_JOB" $LOGNAME < $UNISON_STDLIST) & ' 0

fiexit $RETVAL



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



Notification – Sample EmailTo:Pete Sotocc: 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.2AWSBJA001I Licensed Materials Property of IBM5698-WKB(C) Copyright IBM Corp 1998,2001US Government User Restricted RightsUse, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.AWSBIS307I Starting /tivbkups/maestro/mae82/maestro/jobmanrc heheTWS for UNIX (HPUX)/JOBINFO 8.2 (9.4)Licensed Materials Property of IBM5698-WKB(C) Copyright IBM Corp 1998,2001US Government User Restricted RightsUse, 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 Jobmailing...stdlist to [email protected]================================================================ Exit Status : 127= System Time (Seconds) : 0 Elapsed Time (Minutes) : 0= User Time (Seconds) : 0= Wed 07/07/04 11:49:08CDT===========================================================



.jobmanrc Email Syntax

The previous email was generated with the following syntax in .jobmanrc:

trap '(echo "mailing...stdlist to [email protected]";sleep 30;mailx -s "TWS job $UNISON_JOB Job # $UNISON_JOBNUM Abended" [email protected] <$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.



Jobmanrc and .jobmanrc ReviewThe 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 email2) Send a page (provided CPU is UNIX and includes access to a modem)e3) Send a text message to a pager or cell phone4) Execute a third party application that has a command line interface5) Execute any command, script or binary

IBM Software Group


Any Questions??

TWS 8.2.1

email:

[email protected]

IBM Software Group


Pete Soto Jr

IBM Tivoli Workload SchedulerTWSD jobmanrc, .jobmanrc and djobmanrc.cmd Options Files

tws

Documents

unix jobmanrc

jobmanrc unix

jobmanrc customizing

jobmanrc files

djobmanrc windows

use of jobmanrc

windows version

ste twsd jobmanrc