Diagnostics for scripts that are launched by the IBM Tivoli Storage Manager client

Answer

NOTE: While the examples given in this article are oriented toward Windows, the principles discussed can apply to other operating systems as well.

There are many reasons why a script may fail to run successfully. Common reasons include:

o Syntax errors: The script has an outright error that prevents successful execution. Such a script will most likely fail whether it is run manually or by TSM.

o Environmental differences: The operating system environment settings may differ between the environment in which TSM runs and the environment in which an account runs. For example, suppose a script runs a custom program, like this:

REM Launch my custom program located in C:\MyPrograms\prog1
report.exe E:\stats\stats.in C:\reports\stats.out

When run manually, the script runs fine, but fails when run by TSM.

One likely possibility is that C:\MyPrograms\prog1 is not in the PATH environment variable when TSM runs it. If the user's personal Windows account includes C:\Programs\prog1 in the PATH environment variable, but TSM runs under a different account that does not include this directory in PATH, then the program will not be able to run. A couple of possible solutions are to either add the directory to the PATH variable, or to fully-qualify the program name. Both of these can be accomplished in the script:

REM Launch my custom program located in C:\MyPrograms\prog1
set PATH=%PATH%;C:\MyPrograms\prog1
report.exe E:\stats\stats.in C:\reports\stats.out

or

REM Launch my custom program located in C:\MyPrograms\prog1
C:\MyPrograms\prog1\report.exe E:\stats\stats.in C:\reports\stats.out

A third alternative is to simply add C:\MyPrograms\prog1 to the system PATH environment variable.

o Security differences: If the user account has privileges unavailable to the account under which TSM runs, and a program or command in the script requires one or more of those privileges, then TSM will not be able to run the script correctly. Alternative solutions include:

- Configure the TSM scheduler service to run under an account that has the necessary privileges.

- Modify the account in which the TSM scheduler service runs so that the account has the necessary privileges.

- Modify the program so that it does not require the privileges if those privileges are not really necessary.

Another problem related to security is if the script attempts to access network resources. If TSM runs under the local system account, then that account does not have access to network resources. In this case, try running TSM under a different account that does have network privileges.

o Insufficient diagnostics within the script itself to validate the results of commands or programs used in the script. For example, consider a script that contains the following:

net stop service1
net stop service2
net stop service3

The script will attempt to run each of these commands in turn, but it does not test the results of each "net stop" command to see if it really worked. The script should be enhanced to:

- execute the first "net stop" command
- test the return code from the command
- issue a message indicating whether the command succeeded
- repeat the above steps for the remaining commands
- exit with a return code that best represents the overall
status of the script (0 if all commands processed
successfully, or nonzero if one or more commands failed).

When implemented, these steps can help capture information that can be useful in validating the execution of the script and diagnosing problems.

The attached file, sample.txt, contains a sample implementation using the above steps. The script will write status messages to an output file (defined by the OUTFILE variable at the top of the script). The three service names are also specified in variables at the top of the script to avoid repeating each service name multiple times.

NOTE: This script is intended as a sample only, and is provided on an "as is" basis without warranty of any kind.