Pre-Scripts and Post-Scripts
This topic discusses how to use scripts that can be run before a job (Pre-Job Script) or after a job (Post-Job Script). It also discusses how to use scripts in conjunction with DPX Block Data Protection to support applications not directly supported by DPX Block Data Protection.
General Remarks
DPX allows you to automatically run scripts on UNIX, Linux, OES Linux, or Windows nodes before or after a job. Scripts on Unix may be shell scripts (Bourne, csh, or Korn shell), Perl scripts, or a boolean return from another program on your system. On Windows, the script may be a batch file, a Perl file, a single system command, a program you have written, or anything else you would be able to execute from the DOS command line that runs in text mode.
DPX does not parse the script to ensure that the syntax is correct. DPX merely passes it to the operating system. You can use scripts to change the state of a database, gather information at the time of a job, or perform manual tasks. Following are some common situations in which a script can be useful:
To keep a number of jobs from running simultaneously.
To retrieve the return code of the job.
To launch a second job only if the first job succeeded.
Scripts may be located on either the master server or on any of your client nodes. However, the default is the master server. If you want to use a client node, use the format scriptname@hostname.
Important. In order for any script to be effectively called by DPX, it must be located in the right directory (or folder).
for master server, this is
/opt/DPX/sched/scripts
;for Linux DPX client, if installed under the default directory, this is
/opt/DPX/sched/scripts
;for Windows DPX client, if installed under the default directory, this is
C:\Program Files\DPX\sched\scripts
.
Valid Syntax
Following are three separate examples of acceptable specifications for scripts on remote nodes:
The hostname of the client node is either the name by which the node is known (perhaps through a DNS server) or the IP address, not necessarily the name assigned to the node during configuration of your Enterprise.
The ownership and permissions of the script must be appropriate for the account under which DPX runs. In other words, if you are logged in as that account, you should be able to execute the script successfully from the command line.
You can pass arguments to a script at the time you set the Source Options. The following examples pass the parameters disk1 and 5 to the unmount.sh
script:
Note. The argument list elements use space as delimiters, as shown in the example above.
All valid forms for pre- and post-job script definitions are as follows:
<script>
– run it on the local node<script> <argument_list>
– run it on the local node with arguments<script>@<local_node>
– run it on the local node<script>@<local_node> <argument_list>
– run it on the local node with arguments<script>@<remote_node>
– run it on a remote node<script>@<remote_node> <argument_list>
– run in on a remote node with arguments
A script may call another script. This may be useful in a number of circumstances:
You may need to execute script commands under a different user ID than the one under which DPX is running on the node. On UNIX, the
su
orrsh
commands are ways to do this.You may want to use a modular structure with common elements in different job scripts.
You may want to run a script with parameters assigned dynamically by a calling script.
Important. When using a script to call another script or program, make sure to provide the absolute path, as the script’s working directory when called by DPX will most likely be different from the script’s location.
When a script initiates a process in the background that continues after the script completes, you must direct any output from the background process away from the script. If you do not, the job waits for the output, causing a hang condition. For example, the following pre-job script on UNIX keeps the job from executing:
There are two ways to fix this problem:
You can use the standard file descriptors to redirect all output.
Example:
You can use the
at
orbatch
commands to queue the command.Example:
In both examples, the output from the tail command will be held until the process is terminated later. The script will exit, and the job will start normally.
If a script hangs, kill the script process manually outside the management console (through the operating system).
If a pre-job script ends with a nonzero exit code (ERRORLEVEL, for Windows), DPX considers the script to have failed. The If Pre-Script Fails option determines what action DPX takes. You can either direct DPX to run the job anyway or to skip the job.
If a post-job script ends with a nonzero exit code this will not affect the completion status of the job. If you need to trap these kinds of error conditions, you should incorporate them into the script itself (for example, sending an email to the administrator).
Warning! A post-job script that fails (i.e. returns non-zero code) will pass its failure code down and the job will fail with the same return code. For important additional information about post-job script return codes, read the knowledge base article 42352.
Job Definition Scripting Fields
In the job definition Source Options pane (for the web interface) or dialog (for the desktop interface), four fields instruct DPX how to behave before, during, and after a job runs. They are:
Pre-Job Script field
If Pre-Script Fails field
If Job Fails field
Post-Job Script field
Editing Job Definition Scripting Fields
To edit the job definition scripting fields, do the following:
In the job definition view, scroll down to Advanced Options and click the section to expand it.
Find the Script Options subsection and click it to expand it.
Edit the fields as needed. See valid syntax for calling scripts above.
Continue with defining the job and select Save. To save the changes.
Pre-Job Script field
Tells DPX to run a script prior to an operation. On UNIX, the script may be a shell script (Bourne, csh, or Korn shell), a Perl script, or a script written in any scripting language on your system. On Windows, the script may be a batch file, a Perl file, a single system command, or anything executable from the DOS command line that runs in text mode.
Use this option if you want DPX to perform certain operations, such as shutting down a database, before it performs an operation. Use the If Pre-Script Fails option to specify how you want DPX to behave if the pre-job script fails. If you use a pre-job script, it must be located in the directory SCHED/SCRIPTS
in the directory in which DPX is installed on UNIX and SCHED\SCRIPTS
in the directory in which is DPX installed on Windows.
Note. For Windows, the bexit command passes the exit status of batch execution to DPX. If this command is omitted, DPX receives an undefined exit status.
Sample DOS batch file using the bexit command
If Pre-Script Fails field
Determines how DPX behaves if the pre-job script fails.
Run Job/Run Post-Job Script
Runs both the job and the post-job script if the pre-job script fails.
Skip Job/Run Post-Job Script
Skips the job and runs the post-job script.
Skip Job/Skip Post-Job Script
Skips both the job and the post-job script.
If Job Fails field
Determines whether DPX runs the post-job script if the job fails.
Run Post-Job Script
Runs the post-job script if the job fails.
Skip Post-Job Script
Skips the post-job script if the job fails.
Post-Job Script field
Tells DPX to run a script after the operation. On UNIX, the script may be a shell script (Bourne, csh, or Korn shell), a Perl script, or a script written in any scripting language on your system. On Windows, the script may be a batch file, a Perl file, a single system command, or anything executable from the DOS command line that runs in text mode.
Use this option if you want DPX to perform certain operations such as bringing up a database after it performs an operation. Use the If Job Fails option to determine whether the post-job script runs if the job fails. If you use a post-job script, it must be located in SCHED/SCRIPTS
(UNIX) or SCHED\SCRIPTS
(Windows) in the directory in which is installed.
Note. For Windows, the bexit command passes the exit status of batch execution to DPX. If this command is omitted, receives an undefined exit status.
Sample DOS batch file using the bexit command
Retrieving Backup Information Using Pre-Script and Post-Script variables
DPX enables you to use variables in a pre-job or post-job script to retrieve general information about a backup job. The information is obtained by the scripts at runtime.
Variables
The following keywords serve as parameters, each preceded by a percent sign, that should be added to the script. The variables are then used to read the arguments from within the script.
JOBNAME
The name.
JOBID
The decimal unique ID.
RC
The return code.
JOBLOG
The filename of the main job log.
BACKUPTYPE
BASE: For base backups. INCR: For incremental backups. DIFR: For differential backups.
The following example is based on a Microsoft Windows batch script. Save the following as:
keyword_test.cmd
in the Backup Express\sched\scripts
folder.
Example:
In the task panel, select Other Tasks > Set Source Options > Script Options and in the Pre-job script or Post-job script field, enter:
DPX then substitutes the variable with the value retrieved at runtime and writes the values to the job log file.