1. IBM Software Group © 2006 IBM Corporation Pete Soto Jr IBM Tivoli Workload Scheduler TWSD jobmanrc,.jobmanrc and djobmanrc.cmd Options Files

2. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 2 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

3. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 3 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.

4. IBM Software Group © 2006 IBM Corporation Windows jobmanrc TWS Local Configuration Script

5. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 5 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.

6. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 6 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

7. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 7 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.

8. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 8 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.

9. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 9 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%

10. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 10 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%

11. IBM Software Group © 2006 IBM Corporation djobmanrc.cmd TWS User Configuration Script

12. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 12 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.

13. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 13 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.

14. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 14 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:

15. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 15 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:

16. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 16 Cont’d 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:

17. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 17 Cont’d 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:

18. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 18 Sample djobmanrc.cmd File

19. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 19 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 user’s “documents and settings” directory. Note: Value in LOCAL_RC_OK is case sensitive, use uppercase.

20. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 20 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:

21. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 21 Edited jobmanrc.cmd File

22. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 22 Con’d Edited jobmanrc.cmd File

23. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 23 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.

24. IBM Software Group © 2006 IBM Corporation Optional Windows jobmanrc.cmd Customizing

25. IBM Software Group © 2006 IBM Corporation MAIL_ON_ABEND

26. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 26 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 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 Craig.Peacock@beyondlogic.org.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 user’s email program.

27. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 27 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.

28. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 28 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.

29. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 29 MAIL_ON_ABEND Sample Functions

30. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 30 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.

31. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 31 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.

32. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 32 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.

33. IBM Software Group © 2006 IBM Corporation Implementing Basic MAIL_ON_ABEND using Single email id

34. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 34 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.

35. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 35 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.

36. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 36 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. Craig.Peacock@beyondlogic.org

37. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 37 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.

38. IBM Software Group © 2006 IBM Corporation Implementing Basic MAIL_ON_ABEND using logon user email id

39. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 39 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_ID=user_email@domain.comEMAIL_ID=user_email@domain.com Where: user_email@domain.comuser_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.

40. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 40 MAIL_ON_ABEND using djobmanrc.cmd and email_id Edited djobmanrc.cmd with email_id.

41. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 41 Edited jobmanrc.cmd

42. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 42 Cont’d Edited jobmanrc.cmd

43. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 43 Cont’d Edited jobmanrc.cmd

44. IBM Software Group © 2006 IBM Corporation UNIX jobmanrc TWS Local Configuration Script

45. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 45 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.

46. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 46 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"

47. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 47 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.

48. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 48 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"

49. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 49 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”.

50. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 50 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

51. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 51 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

52. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 52 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

53. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 53 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"

54. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 54 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.

55. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 55 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 ! 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 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.

56. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 56 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"

57. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 57 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".

58. IBM Software Group © 2006 IBM Corporation Abend Notification Notify when jobs abend

59. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 59 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.

60. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 60 Notification Methods Notification of abended jobs requires configuration of either the jobmanrc,.jobmanrc or creation of djobmanrc.cmd. The TWSHome/jobmanrc file is used when notification of any abended job is required. The person notified will be identified in the jobmanrc file. The /userhome/.jobmanrc or drive:\documents and settings\djobmanrc.cmd (new user created option) file is used when notification of abended job is required for a specific user. The person notified is the owner of the job. The TWSHome/jobmanrc must be configured if these methods will be used. Note: The jobmanrc and the.jobmanrc must be executable.

61. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 61 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

62. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 62 Notification – Paging (UNIX) Another option is to use a specific system device and settings in addition to the TWS “parms” command (refer to TWS 8.2 Reference Guide for parms command usage). The syntax below uses the standard UNIX cu command, it pages the pager that is assigned to the TWS parameter “oncall” with the text 2453000. You will need to determine pager limitations. The use of the TWS “parms” allows change only the contact number assigned to the parameter called “oncall” without needing to change the paging syntax. Solution 2: cu –lcu1p6 –s19200 `parms oncall` --2453000 Note: A man of the cu command will give you more specifics on the cu options. man cu

63. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 63 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

64. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 64 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.

65. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 65 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. CarrierSend Email to phonenumber@.... Alltel@message.alltel.com Cingular@cingularme.com Nextel @messaging.nextel.com Sprint @messaging.sprintpcs.com SunCom@tms.suncom.com T-mobil@tmobil.net VoiceStream@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 http://www.aipcom.com/support/email-finder.asp

66. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 66 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 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 – TWS’s production date: yyyymmdd UNISON_SCHED_EPOCH – TWS’s production date expressed in epoch form UNISON_SCHED – The schedule name for job UNISON_SHELL – The user’s login shell UNISON_STDLIST - The fully qualified path for the job stdlist: TWSHome/stdlist/yyyy.mm.dd/Ojobnum.hhmm

67. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 67 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.)

68. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 68 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”.

69. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 69 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.

70. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 70 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.

71. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 71 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

72. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 72 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..

73. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 73 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.

74. IBM Software Group © 2006 IBM Corporation.jobmanrc TWS User Configuration Script

75. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 75.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.

76. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 76.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.

77. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 77 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

78. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 78.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.

79. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 79 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 ===========================================================

80. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 80.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.

81. IBM Software Group | Tivoli software STE | TWSd Jobmanrc and dJobmanrc © 2007 IBM Corporation 81 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

82. IBM Software Group © 2006 IBM Corporation Any Questions ?? TWS 8.2.1 email: sotope@us.ibm.com

83. IBM Software Group © 2006 IBM Corporation Pete Soto Jr IBM Tivoli Workload Scheduler TWSD jobmanrc,.jobmanrc and djobmanrc.cmd Options Files