Professional Documents
Culture Documents
TWS
TWS
IBM Tivoli Workload Scheduler TWSD jobmanrc, .jobmanrc and djobmanrc.cmd Options Files
Pete Soto Jr
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 |
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 |
Windows jobmanrc
TWS 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 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 |
STE |
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 |
STE |
STE |
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 |
djobmanrc.cmd
TWS 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 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 |
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 |
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 |
15
STE |
16
STE |
17
STE |
18
STE |
19
STE |
3) The edited Tivoli Workload Scheduler 8.3 Windows jobmanrc.cmd should look like the following:
20
STE |
21
STE |
22
STE |
23
STE |
MAIL_ON_ABEND
26
STE |
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 |
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 |
29
STE |
30
STE |
31
STE |
Note: The email syntax in above example will be sent to the value in MAIL_ON_ABEND.
32
STE |
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 |
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 |
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 |
37
STE |
39
STE |
40
STE |
Edited jobmanrc.cmd
41
STE |
42
STE |
43
STE |
UNIX jobmanrc
TWS 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.
45
STE |
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 |
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 |
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 |
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 |
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 |
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
51
STE |
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 |
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 |
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 |
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 |
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 |
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 |
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.
59
STE |
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 |
63
STE |
64
STE |
There is a list of most US carriers and the address format supported at http://www.aipcom.com/support/email-finder.asp
65
STE |
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 |
67
STE |
68
STE |
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 |
70
STE |
71
STE |
72
STE |
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 |
.jobmanrc
TWS 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.
75
STE |
.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 |
77
STE |
.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 |
===========================================================
79 STE |
80
STE |
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 |
Any Questions
??
email: sotope@us.ibm.com
TWS 8.2.1
IBM Tivoli Workload Scheduler TWSD jobmanrc, .jobmanrc and djobmanrc.cmd Options Files
Pete Soto Jr