Why doesn’t my job run under TWS?

by Pete Meechan

One of the most common questions asked when adding new workloads to TWS is “Why doesn’t my job run under TWS when it runs perfectly okay from the command line?” This tip explains possible reasons and provides troubleshooting techniques that should help to answer that question.

The login environment

If you are familiar with login procedures you may want to skip to the “Sourcing the environment” section.

When you login to a computer, irrespective of whether it is a Windows, Linux, UNIX, Mac or any other operating system, there are a number of actions that are performed automatically in the background to prepare the computer “environment” for your use. What actions are performed will vary greatly from one operating system to another, as well as from one organisation to another as the actions performed are usually specified by the system administrator responsible for the computer systems being used.

Typically, actions such as setting up the location of the programs that will be used are defined so that they can be automatically located when required. If your organisation uses shared resources such as printers or storage area networks (SAN), these will also be allocated and defined automatically at login time. How these are defined will also vary depending upon the operating system and command environment being used, but generically speaking they will be allocated using a “login profile”.

The “login profile” consists of a series of commands that define, amongst other things, the printer to be used by default, which locations need to be referenced when looking for the commands or programs that you will execute, etc. This process is generally referred to as “setting up the environment”.

When your login profile has executed it will usually set up the location of programs or commands that are executed using an environment variable known as the “PATH”. The PATH variable contains multiple locations (paths) that contain programs and commands that are available to your login session. This allows you to execute programs and commands by only specifying their name (e.g. copy) and the operating system will automatically locate and execute the requested program.

The “environment” contains many other settings that are required either by the operating system itself or set by the system administrator responsible for the management of the computers in your organisation. In the example shown below (taken from a Linux system) the “HOSTNAME” environment variable contains the name of the computer (e.g. clynelish.scotchwhisky.local) and the “PATH” environment variable contains the names of the paths (or directories) that will be searched for any programs or commands that you may execute. On UNIX and Linux systems the “environment” settings can be listed using the “env” command as shown below.

[  orb@clynelish ~]$ env

HOSTNAME=clynelish.scotchwhisky.local

SHELL=/bin/bash

TERM=xterm

HISTSIZE=1000

QTDIR=/usr/lib64/qt-3.3

QTINC=/usr/lib64/qt-3.3/include

USER=orb

LS_COLORS=rs=0:di=01;34:ln=01;36:mh=00:pi=40;33:so=01;35:do=01;35:bd=40;33;01:cd=40;33;01:

or=40;31;01:mi=01;05;37;41:su=37;41:sg=30;43:ca=30;41:tw=30;42:ow=34;42:st=37;44:ex=01;32:

*.tar=01;31:*.tgz=01;31:*.arj=01;31:*.taz=01;31:*.lzh=01;31:*.lzma=01;31:*.tlz=01;31:

*.txz=01;31:*.zip=01;31:*.z=01;31:*.Z=01;31:*.dz=01;31:*.gz=01;31:*.lz=01;31:*.xz=01;31:

*.bz2=01;31:*.tbz=01;31:*.tbz2=01;31:*.bz=01;31:*.tz=01;31:*.deb=01;31:*.rpm=01;31:

*.jar=01;31:*.rar=01;31:*.ace=01;31:*.zoo=01;31:*.cpio=01;31:*.7z=01;31:*.rz=01;31:

*.jpg=01;35:*.jpeg=01;35:*.gif=01;35:*.bmp=01;35:*.pbm=01;35:*.pgm=01;35:*.ppm=01;35:

*.tga=01;35:*.xbm=01;35:*.xpm=01;35:*.tif=01;35:*.tiff=01;35:*.png=01;35:*.svg=01;35:

*.svgz=01;35:*.mng=01;35:*.pcx=01;35:*.mov=01;35:*.mpg=01;35:*.mpeg=01;35:*.m2v=01;35:

*.mkv=01;35:*.ogm=01;35:*.mp4=01;35:*.m4v=01;35:*.mp4v=01;35:*.vob=01;35:*.qt=01;35:

*.nuv=01;35:*.wmv=01;35:*.asf=01;35:*.rm=01;35:*.rmvb=01;35:*.flc=01;35:*.avi=01;35:

*.fli=01;35:*.flv=01;35:*.gl=01;35:*.dl=01;35:*.xcf=01;35:*.xwd=01;35:*.yuv=01;35:

*.cgm=01;35:*.emf=01;35:*.axv=01;35:*.anx=01;35:*.ogv=01;35:*.ogx=01;35:*.aac=01;36:

*.au=01;36:*.flac=01;36:*.mid=01;36:*.midi=01;36:*.mka=01;36:*.mp3=01;36:*.mpc=01;36:

*.ogg=01;36:*.ra=01;36:*.wav=01;36:*.axa=01;36:*.oga=01;36:*.spx=01;36:*.xspf=01;36:

MAIL=/var/spool/mail/orb

PATH=/usr/lib64/qt-3.3/bin:/usr/local/bin:/bin:/usr/bin:/usr/local/sbin:/usr/sbin:/sbin:/home/orb/bin

PWD=/home/orb

LANG=en_US.UTF-8

KDE_IS_PRELINKED=1

KDEDIRS=/usr

SSH_ASKPASS=/usr/libexec/openssh/gnome-ssh-askpass

HISTCONTROL=ignoredups

SHLVL=1

HOME=/home/orb

LOGNAME=orb

QTLIB=/usr/lib64/qt-3.3/lib

CVS_RSH=ssh

LESSOPEN=|/usr/bin/lesspipe.sh %s

DISPLAY=:0.0

G_BROKEN_FILENAMES=1

_=/usr/bin/env

[  orb@clynelish ~]$

For the Windows “environment” similar information can be obtained using the “set” command from a Windows command prompt as shown below. The “COMPUTERNAME” environment variable contains the hostname of the computer (e.g. BALBLAIR) and the “PATH” environment variable contains the names of the paths (or directories) that will be searched for any programs or commands that you may execute.

C:>set

ALLUSERSPROFILE=C:Documents and SettingsAll Users

APPDATA=C:Documents and SettingsAdministratorApplication Data

CLASSPATH=.;C:PROGRA~1IBMSQLLIBjavadb2java.zip;C:PROGRA~1IBMSQLLIBjavadb2jcc.jar;C:PROGRA~1IBMSQLLIB

javasqlj.zip;C:PROGRA~1IBMSQLLIBjavadb2jcc_license_cu.jar;C:PROGRA~1IBMSQLLIB in;C:PROGRA~1IBMSQLLIBjavacommon.jar

ClusterLog=C:WINDOWSClustercluster.log

CommonProgramFiles=C:Program FilesCommon Files

COMPUTERNAME=BALBLAIR

ComSpec=C:WINDOWSsystem32cmd.exe

DB2INSTANCE=DB2

FP_NO_HOST_CHECK=NO

HOMEDRIVE=C:

HOMEPATH=Documents and SettingsAdministrator

INCLUDE=C:PROGRA~1IBMSQLLIBINCLUDE;C:PROGRA~1IBMSQLLIBLIB

J2D_D3D=false

LIB=;C:PROGRA~1IBMSQLLIBLIB

LOGONSERVER=BALBLAIR

MAESTROCOLUMNS=0

MAESTROLINES=0

MAESTRO_OUTPUT_STYLE=LONG

NLSPATH=”C:Program FilesTivoliDesktopmsg_cat%L%N.cat”

NUMBER_OF_PROCESSORS=1

OS=Windows_NT

Path=C:WINDOWSsystem32;C:Perlsite in;C:Perl in;C:Program FilesSupport Tools;C:Program FilesWindows Resource KitsTools;C:WINDOWS;C:WINDOWSSystem32Wbem;C:WINDOWSsystem32WindowsPowerShell 1.0;C:PROGRA~1IBMSQLLIBBIN; C:PROGRA~1IBMSQLLIBFUNCTION;C:PROGRA~1IBMSQLLIBSAMPLESREPL;C:WINDOWSsystem32WindowsPowerShell 1.0

PATHEXT=.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.PSC1;.PSC1

PROCESSOR_ARCHITECTURE=x86

PROCESSOR_IDENTIFIER=x86 Family 6 Model 23 Stepping 10, GenuineIntel

PROCESSOR_LEVEL=6

PROCESSOR_REVISION=170a

ProgramFiles=C:Program Files

PROMPT=$P$G

PSModulePath=C:WINDOWSsystem32WindowsPowerShell 1.0Modules

SESSIONNAME=Console

SystemDrive=C:

SystemRoot=C:WINDOWS

TEMP=C:Temp

TISDIR=C:WINDOWSsystem32driversetcTivoli

TMP=C:Temp

TWS4APPS_JDKHOME=C:Program FilesIBMTWATWSmethods_tools

USERDOMAIN=BALBLAIR

USERNAME=Administrator

USERPROFILE=C:Documents and SettingsAdministrator

windir=C:WINDOWS

C:>

 

Sourcing the environment

Not all programs that you may use are automatically added to the “PATH” environment variable so that they can be automatically located when required. On Windows systems for example, the program shortcut used to start a program (e.g. Microsoft Word) contains the location of the program and the directory path where the program is located. Similar shortcut definitions can be created on UNIX or Linux systems and are usually known as program or application launchers.

A program can also be executed by entering the full path to the program e.g. /usr/orb/bin/program1 (UNIX/Linux) or C:OrbProgramsprogram1.exe (Windows), but this technique requires knowledge of where the program is located and is therefore considered rather user unfriendly.

A common practice to avoid having to enter the full path to programs is to provide a “sourcing” script that sets up the correct environment to allow the program to execute successfully. Whilst the individual actions performed by the “sourcing” script are determined by the requirements of the individual program, they will almost always temporarily modify the “PATH” environment variable to include the location of the program for which it was supplied. Common examples of products that use “sourcing” scripts are database applications and java programs.

TWS is another program that employs a “sourcing” script as part of the installation process. If you need to use the TWS command line interface (for command such as composer or conman), you will need to “source” the TWS environment to provide this capability. This is achieved by executing the TWS supplied script – twa_env.sh (UNIX/Linux) or twa_env.cmd (Windows) found within the TWS installation directory. Part of the processing performed by these scripts is to add the location of the TWS programs to the “PATH” environment variable so that the “conman” and “composer” commands can be executed successfully from the command line.
Note: The TWS “sourcing” script is only required when using the TWS command line interface – it is not required for execution of non-TWS programs (e.g. database, sales forecast update, etc.) that execute under TWS.

In summary, successful execution of a program within an interactive login command prompt/shell is achieved by using one or more of the techniques listed above.

 

TWS Environment

So why doesn’t my program run under TWS? In most cases, it is because the TWS environment is not the same as the interactive login environment described above. The simplest way to determine what is different between the two environments is to list the environment settings in both the TWS and the interactive login environments.

The previous section showed how to use the “env” (UNIX/Linux) and “set” (Windows) command to list the interactive login environment settings. Within TWS these same commands can be used in a TWS job definition to obtain the TWS environment settings.

The sample jobs shown below can be used to do this for the UNIX/Linux and Windows environments respectively. It is very important that the user specified in the job definition STREAMLOGON is the same user that is logged in to the interactive login described earlier in this article. If the user specified is not the same, the differences in the environment settings may be caused by the different user environments.

UNIX/Linux job definition

CLYNELISH#ORB_ENV_JOB

DOCOMMAND “/usr/bin/env”

STREAMLOGON orb

DESCRIPTION “List TWS environment”

TASKTYPE UNIX

RECOVERY STOP

Windows job definition

BALBLAIR#ORB_ENV_JOB

DOCOMMAND ” C:WINDOWSsystem32cmd.exe set”

STREAMLOGON orb

DESCRIPTION “List TWS environment”

TASKTYPE WINDOWS

RECOVERY STOP

As can be seen from the results of these jobs below, the TWS environment does not contain all of the environment settings that are found within the interactive login environment, but contains a lot of additional environment variable settings that are set and used by TWS (e.g. all of the UNISON_xxx variables).

UNIX/Linux TWS environment settings

UNISON_SCHED_EPOCH=1337126400

UNISON_CPU=CLYNELISH

UNISON_DIR=/opt/ibm/TWA/TWS

UNISON_SCHED_ID=0AAAAAAAAAAAADJP

UNISON_SCHED=ORB_ENV

UNISON_HOST=CLYNELISH

UNISON_SCHED_IA=201205160939

UNISONHOME=/opt/ibm/TWA/TWS

UNISON_MASTER=CLYNELISH

UNISON_JCL=/usr/bin/env

LD_LIBRARY_PATH=/usr/Tivoli/TWS/GSKit64/8/lib64

TWS_GSKIT_PATH=/usr/Tivoli/TWS/GSKit64/8/lib64

LIBPATH=/usr/Tivoli/TWS/GSKit64/8/lib64

UNISON_EXEC_PATH=/opt/ibm/TWA/TWS/jobmanrc

NLSPATH=/opt/ibm/TWA/TWS/catalog/%L/%N.cat:

PATH=/bin:/usr/bin

LD_RUN_PATH=

UNISON_RUN=167

PWD=/home/orb

TWS_TISDIR=/opt/ibm/TWA/TWS

LANG=en_US.UTF-8

MAESTRO_OUTPUT_STYLE=LONG

TWS_PROMOTED_JOB=NO

MECHO=/opt/ibm/TWA/TWS/bin/mecho

UNISON_JOB=CLYNELISH#(0AAAAAAAAAAAADJP.ORB_ENV_JOB

SHLVL=1

HOME=/home/orb

UNISON_SYM=307

UNISON_JOBNUM=19581

LOGNAME=orb

UNISON_STDLIST=/opt/ibm/TWA/TWS/stdlist/2012.05.16/O19581.0939

SHLIB_PATH=/usr/Tivoli/TWS/GSKit64/8/lib64

UNISON_SHELL=/bin/bash

TIVOLI_JOB_DATE=20120516

UNISON_SCHED_DATE=20120516

_=/usr/bin/env

Windows TWS environment settings

ARGS=”C:Windowssystem32cmd.exe” /c set    

BANNER=TWS for Windows NT/JOBMANRC.CMD 8.5.1

CANDLE_HOME=C:IBMITM

CLASSPATH=.;C:PROGRA~1IBMSQLLIBjavaDB2JCC~1.JAR;C:PROGRA~1IBMSQLLIBjavadb2java.zip; C:PROGRA~1IBMSQLLIBjavadb2jcc.jar;C:PROGRA~1IBMSQLLIBjavasqlj.zip; C:PROGRA~1IBMSQLLIBjavadb2jcc_license_cu.jar;C:PROGRA~1IBMSQLLIB in; C:PROGRA~1IBMSQLLIBjavacommon.jar

COMPUTERNAME=BALBLAIR

ComSpec=C:Windowssystem32cmd.exe

COPYRIGHT_CONST=1

DB2INSTANCE=DB2

FP_NO_HOST_CHECK=NO

HOME=C:Program FilesIBMTWATWS

HOMEDRIVE=

HOMEPATH=

INCLUDE=C:PROGRA~1IBMSQLLIBINCLUDE;C:PROGRA~1IBMSQLLIBLIB

KUIFILEPATH=C:IBMITM inxml

LANG=C

LIB=;C:PROGRA~1IBMSQLLIBLIB

LIBPATH=C:IBMITMTMAITM6;C:IBMITMInstallITM

LOGNAME=BALBLAIRorb

MAESTRO_OUTPUT_STYLE=

MAE_COPYRIGHT_SET=234

NUMBER_OF_PROCESSORS=2

OS=Windows_NT

Path=C:Program FilesIBMTWATWSGSKit8lib64;c:perl64site in;c:perl64 in;C:Windowssystem32; C:Windows;C:Windowssystem32wbem;C:Windowssystem32windowspowershell 1.0; c:progra~2window~3 ools;c:ibmitm in;c:ibmitm maitm6;c:ibmitminstallitm; c:program filesibmgsk8lib64;C:PROGRA~1IBMSQLLIBBIN; C:PROGRA~1IBMSQLLIBFUNCTION;C:PROGRA~1IBMSQLLIBSAMPLESREPL

PATHEXT=.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC

POSIXHOME=C:/Program Files/IBM/TWA/TWS

PROCESSOR_ARCHITECTURE=AMD64

PROCESSOR_IDENTIFIER=Intel64 Family 6 Model 23 Stepping 10, GenuineIntel

PROCESSOR_LEVEL=6

PROCESSOR_REVISION=170a

PROMPT=$P$G

PSModulePath=C:Windowssystem32WindowsPowerShell 1.0Modules

SystemDrive=C:

SystemRoot=C:Windows

TEMP=D:Temp

TEMP=D:Temp

TIVOLI_JOB_DATE=20120516

TMP=D:Temp

TMP=D:Temp

TMPDIR=D:Temp

TWS4APPS_JDKHOME=C:Program FilesIBMTWATWSmethods_tools

TWS_GSKIT_PATH=C:Program FilesIBMTWATWSGSKit8lib64

TWS_PROMOTED_JOB=NO

UNISON_CPU=BALBLAIR

UNISON_DIR=C:Program FilesIBMTWATWS tjobs

UNISON_EXEC_PATH=C:Program FilesIBMTWATWSjobmanrc.cmd

UNISON_HOST=BALBLAIR

UNISON_JOB=BALBLAIR#0AAAAAAAAAAAAD4P.ORB_ENV

UNISON_JOBNUM=11527

UNISON_MASTER=BALBLAIR

UNISON_RUN=349

UNISON_SCHED=ORB_ENV

UNISON_SCHED_DATE=20120516

UNISON_SCHED_EPOCH=1337126400

UNISON_SCHED_IA=201205161402

UNISON_SCHED_ID=0AAAAAAAAAAAAD4P

UNISON_SHELL=C:Windowssystem32cmd.exe

UNISON_STDLIST=C:Program FilesIBMTWATWSstdlist/2012.05.16/O11527.1402

UNISON_SYM=303

UNISONHOME=

USERDOMAIN=BALBLAIR

USERNAME=SYSTEM

USERNAME=BALBLAIRorb

USERPROFILE=C:Usersorb

VERSION=8.5.1

windir=C:Windows

windows_tracing_flags=3

windows_tracing_logfile=C:BVTBinTestsinstallpackagecsilogfile.log

 

Modifying TWS environment settings

If it is necessary to change the default TWS environment settings to make specific settings available for ALL jobs executed under TWS, the TWS supplied jobmanrc (UNIX/Linux) or jobmanrc.cmd (Windows) script can be modified accordingly. The script can be found within the TWS installation directory.

If the changes affect only the jobs executed by a specific user such as a database user, instead of modifying the common jobmanrc script the user specific script can be updated. This script does not exist and must be created in the home directory of the user (e.g. /home/user for UNIX/Linux or the value in the %USERPROFILE% environment variable for Windows). For UNIX/Linux the script must be named “.jobmanrc” and be marked as executable. For Windows the script must be named “djobmanrc.cmd”.

 

Troubleshooting the TWS environment

When trying to determine why a job does not execute successfully under TWS, the first option to consider is the different environmental settings as described earlier. If correction to the environment settings does not resolve the issue, review the following items to see if they could be the cause of further inconsistencies.

  • Ensure that the user logged in to the system where the program executes successfully from an interactive command line, is the same user specified in the TWS job definition STREAMLOGON parameter. If they are different, this can cause inconsistency in the environment settings in addition to permission issues
  • Particularly within the Windows environment, consider the following
    1. Most programs have been developed for use in an interactive login environment and consequently assume that certain environmental variables will be set when the program executes. These may not be set by default within the TWS environment.
    2. Some programs make use of the Windows desktop heap and require the “interactive job” setting to be specified. Normally this will be indicated by the error message in the job log or the Windows event log mentioning errors relating to the “desktop heap”
    3. Some programs assume that temporary files are set to the user home directory, but this is not always the case in background processing. It may be necessary to check the program documentation to see if it is possible to override this assumption with a program specific parameter. An example of this is for the SAS Institute business analytics program, where the “-WORK C:Temp” parameter can be specified when executing SAS jobs under TWS.
  • Use the program and operating system log files to assist with the problem determination process and identify the error. Typical places for locating errors are
  1. TWS job log output
  2. TWS TWMERGE log file in the TWS installation directory stdlist/logs directory
  3. Windows event log
  4. UNIX/Linux /var/log/messages
  5. home directory for the user executing the job

Visits: 2925