Pre-command and post-command script settings

About pre-command and post-command settings

When you start a SnapManager backup, database verification, restore, or clone operation, you have the option to automatically run a command (a user executable program or script) either before the operation starts or after the operation is complete. You can also choose how script errors are handled.

Where to specify a command before an operation

You can set up commands or scripts to run before SnapManager operations in the following ways:

From the backup, restore, or clone wizards
From the Quick Backup, Quick Restore, and Quick Clone dialog boxes
From the Run Commands dialog box

How to specify a script to run before an operation from a wizard or quick dialog box

From within the context of a SnapManager backup, verification, restore, or clone operation, you can use the Run Commands dialog box to do the following:

Specify the details of the command:
- Whether you want to continue or stop the operation for errors that occur during or prior to the script-command
- The computer where you want to run the command
- The full path to the command
- The sequence of SnapManager variables that you want to pass to the command
Specify whether you want to save the current settings as the default settings

Note: If you want to change the default values specified in the Run Commands dialog box without starting an SMSQL operation like backup, verify, restore, or clone you can open the Run Commands dialog box from the Option menu. This is described in the next section.

When you choose to run a script before an operation from a wizard or quick dialog box, you are prompted to specify the following information before the operation begins:

Whether you want to stop the SnapManager operation (for example, backup, verify, restore, or clone) if the user script has an error.
The host system from which the command is to be run
The full path of the command that you want SnapManager to run after the backup or database verification is complete
Any parameters that are to be passed to the command
Because the command (your own program or script) is invoked from within the context of a SnapManager operation, you can pass the command information about the components of that operation. For example, if the pre- or post-command is a batch file that is launched, it will look like c:\bat\mytestCommand.bat $SqlSnapshot $Database. In this example, inside the batch file, the %1 batch parameter corresponds to the first parameter $SqlSnapshot passed to the batch script; the %2 string will corresponds to the second $Database parameter passed, and so on, because it is running in the context of the SMSQL operation.

To run a script from a wizard or a Quick dialog box, see one of the following procedures:

"Full database backup using Backup and Verify" in Backing up, replicating, and archiving databases using SnapManager
"Restoring using the SnapManager Restore Wizard" in Performing a restore operation
"Cloning a database that is in production" in Types of clone operations performed using SnapManager
"Cloning a database in a backup set" in Types of clone operations performed using SnapManager

Setting pre-command or script defaults

You can use the Run Commands dialog box to configure default values that you want used to prepopulate the Run Commands dialog box when it is opened from either the Backup, Verify, Clone, or Restore wizards and options.

To run a script from the Run Commands dialog box, complete the following steps.

Step	Action
1	From the Actions menu, click the Run Commands option. Result SnapManager displays the Run Commands dialog box with the current default settings.
2	Select the list box item value for the operation (for example, backup, verify, restore, or clone) where you want these default Run Commands settings to apply.
3	Make sure that the Pre-Operation Command tab is selected.
4	Choose whether to stop the pre-command operation if an error occurs.
	If...	Then ..
	You want the SnapManager for SQL Server operation to stop when an error occurs in the custom user command	Select the check box labeled, "Treat pre command errors as fatal by stopping the remaining SnapManager operation..."
	You want to ignore errors that occurred during the user command or script, and want to continue to run the SnapManager for SQL Server operation regardless of those script errors	Do not select the check box labeled "Treat pre command errors as fatal by stopping the remaining SnapManager operation..."
5	In the "Specify a computer where..." box, enter or browse to the name of the host on which your program or script resides.
6	In the "Specify the full path..." box, browse to your program or script.
7	Form the command input string in the Command Arguments box. You can do this using any combination of the following methods: To enter text directly into the Command Arguments box, click in the box and type the desired text. To enter a SnapManager variable into the Command Arguments box, do the following: If necessary, click in the Command Arguments box to position the cursor. In the SnapManager Variables list, select the variable you want to enter. For more information, see "Running a command or script after an operation" and "Command arguments that are operation-specific" later in this section. Click Select. Note: Several parameters like $SnapInfoPath and $LogBackupFile variables are enclosed within double quotes by default, so that the actual path name can contain spaces without affecting the script invocation on the Windows command line. If you do not want the double quotes to appear in your command line, remove them from the Command Arguments field in the Run Commands dialog box.
8	Repeat step 4 as needed until the Command Arguments box contains the arguments you want to pass to your program or script.
9	Click OK to apply your changes and close the Run Commands dialog box. Your changes are saved as the default.

Running a command or script after an operation

SnapManager provides the ability to run scripts after database backup, verify, restore, or clone operations. SnapManager also enables you to choose how operation errors are handled. You can choose to stop the SnapManager for SQL Server operation if an error occurs during the script launch.

You can set up commands or scripts to run after SnapManager operations in the following ways:

From the backup, restore, or clone wizards
From the Quick Backup, Quick Restore, and Quick Clone dialog boxes
From the Run Commands dialog box

How to specify a script to run after an operation from a wizard or quick dialog box

From within the context of a SnapManager backup, verification, restore, or clone operation, you can use the Run Commands dialog box to do the following:

Specify the details of the command:
- Whether you want the pre-command to run regardless of the SQL operation's result
- The computer where you want to run the command (your own program or script)
- The full path to the command
- The sequence of SnapManager variables that you want to pass to the command
Specify whether you want to save the current settings as the default settings

Note: If you want to change the default values specified in the Run Commands dialog box without starting or scheduling a database backup, transaction log only backup, or database verification, you can open the Run Commands dialog box from the Option menu.

To run a script from a wizard or a Quick dialog box, see one of the following procedures:

"Full database backup using Backup and Verify" in Backing up, replicating, and archiving databases using SnapManager
"Restoring using the SnapManager Restore option" in Performing a restore operation
"Cloning a database that is in production" in Types of clone operations performed using SnapManager

When you choose to run a script after an operation from a wizard or quick dialog box, you are prompted to specify the following information before the operation begins:

Whether to run the post-command regardless of the SMSQL operation's result.
The host system on which the command is to be run
The full path of the command that you want SnapManager to run after the backup or database verification is complete
Any parameters that are to be passed to the command
Because the command (your own program or script) is invoked from within the context of a specific backup or database verification, you can pass the command information about the components of that operation. For example, if you run the following batch file script after the operation, following c:\myPostCmd.bat $Database $SqlInstance, the first parameter passed, $Database, corresponds to the %1 batch parameter, and the second parameter, $SqlInstance, corresponds to the batch %2 parameter.

After you have completed specifying the command and parameters, you can start the operation.

Setting post-command or script defaults

To specify the default command or script information to be run after a backup, verify, clone or restore wizard operation, complete the following steps:

Step	Action
1	From the Actions menu, click the Run Commands option. Result SnapManager displays the Run Commands dialog box with the current default settings.
2	Select the list box item value for the SnapManager or SQL Server operation where you want these default run command settings to apply.
3	Make sure that the Post Operation Command tab is selected.
4	Choose whether to stop the post-command operation if an error occurs.
	If...	Then...
	You want the SnapManager for SQL Server operation (for example, backup, verify, restore, or clone) to stop when an error occurs in the custom user command	Select the check box labeled, "Treat pre command errors as fatal by stopping the remaining SnapManager operation..."
	You want to ignore errors that occurred during the user command or script, and want to continue to run the SnapManager for SQL Server operation regardless of those script errors	Do not select the check box labeled "Treat pre command errors as fatal by stopping the remaining SnapManager operation..."
5	In the "Specify a computer where..." box, enter or browse to the name of the host on which your program or script resides.
6	In the "Specify the full path..." box, browse to your program or script.
7	Form the command input string in the Command Arguments box. You can do this using any combination of the following methods: To enter text directly into the Command Arguments box, click in the box and type the desired text. To enter a SnapManager variable into the Command Arguments box, do the following: If necessary, click in the Command Arguments box to position the cursor. In the SnapManager Variables list, select the variable you want to enter. For more information, see "Running a command or script after an operation" and "Command arguments that are operation-specific" in this section. Click Select. Note: Several parameters like $SnapInfoPath and $LogBackupFile variables are enclosed within double quotes by default, so that the actual path name can contain spaces without affecting the script invocation on the Windows command line. If you do not want the double quotes to appear in your command line, remove them from the Command Arguments field in the Run Command Operation dialog box.
8	Repeat step 6 as needed until the Command Arguments box contains the arguments you want to pass to your program or script.
9	Click Save to save your changes as the default run commands settings for the operation selected, then close the Run Command dialog box. Repeat Steps 2 through 7 to set up the default for each operation type. Your changes are saved as the default.

Pre-command arguments

The following pre-command arguments apply to backup, verify, restore, and clone operations.

Variable	Description
$Database	Specifies the logical name of the database processes. Note: To prevent PowerShell from interpreting the value of this parameter, be sure to enclose the entire parameter value with single quotes. For example: -PreCmdArg '$Database $ServerInstance' Example: DatabaseAccounting If you want to have more than one database expanded, repeat the parameter as many times as you want. Example: AccountingDB1 AcmeServer1/SqlInst1 FinanceDB2 AcmeServer1/SqlInst2
$ServerInstance	Specifies the name of the SQL server instance that is actually processed. Example: ACMESERVER1\SQLINSTANCE1

Variable

Description

$Database

Specifies the logical name of the database processes.

Note: To prevent PowerShell from interpreting the value of this parameter, be sure to enclose the entire parameter value with single quotes. For example: -PreCmdArg '$Database $ServerInstance'

Example:

DatabaseAccounting

If you want to have more than one database expanded, repeat the parameter as many times as you want.

Example:

AccountingDB1 AcmeServer1/SqlInst1 FinanceDB2 AcmeServer1/SqlInst2

$ServerInstance

Specifies the name of the SQL server instance that is actually processed.

Example:

ACMESERVER1\SQLINSTANCE1

Post-command arguments

The following post-command arguments apply to backup, verify, restore, and clone operations.

Note: To prevent PowerShell from interpreting the value of a parameter, be sure to enclose the entire parameter value with single quotes. For example: -PostCmdArg ‘$Database $ServerInstance $SqlSnapshot'

Variable	Description
$InfoSnapshot	Expands to the name of a SnapInfo directory Snapshot copy. Examples: sqlinfo__winsrvr2__01-31-2005_15.03.09 sqlinfo__winsrvr2__recent
$LogBackupFile	Expands to the full path name of the transaction log backup file. Example: I:\SMSQL_SnapInfo\SQL__WINSRVR2\DB__Northwind\LogBackup\ 11-01-2004_13.34.59__Northwind.TRB
$OperationStatus	Provides the status of the SMSQL operation. Example: 5234
$PreCommandStatus	Provides the pre-command status to the post-command if the post-command is executed based on the status of the earlier pre-command. Example: 5234
$SnapInfoName	Expands to the name of the SnapInfo directory. Examples: WINSRVR2__recent WINSRVR2_11-23-2004_16.21.07__Daily Note: If you use this variable, you must also provide the correct path to the directory.
$SnapInfoPath	Expands to the name of the SnapInfo subdirectory. This argument is used in backup and verification operations. Example: I:\SMSQL_SnapInfo\SQL__WINSRVR2\DB__Northwind For restore and clone operations, this argument specifies the path to the Snapshot copy information metadata that is being used for the database restore. Example: U:\SMSQL_SnapInfo\VDISK__E\FG__\05-14-2010_15.33.41\SnapInfo__05-14-2010_15.33.41.sml
$SqlSnapshot	Expands to the name of an SQL Server database Snapshot copy. This argument is used for backup and verification operations. Examples: sqlsnap__winsrvr2__01-31-2005_15.03.09 sqlsnap__winsrvr2__recent Note: The number of database Snapshot copies in a SnapManager backup set depends on the number of volumes used to store the databases included in the backup. For restore and clone operations, this argument specifies the name of the Snapshot copy to be restored. Example: sqlsnap__winsrvr2__01-31-2005_15.03.09 sqlsnap__winsrvr2__recent

Note: Several parameters like $SnapInfoPath and $LogBackupFile variables are enclosed within double quotes by default, so that the actual path name can contain spaces without affecting the script invocation on the Windows command line. If you do not want the double quotation marks to appear in your command line, remove them from the Command Arguments field in the Run Commands dialog box.

The following post-command arguments apply only to restore and clone operations.

Variable	Description
$StandbyFile	This is the full file system path of the SQL standby file used on a restore. This file path is calculated during the restore-clone operation as a temporary file when incomplete transactions are removed from the database and stored in the file for later use. The user requests to generate a standby (or undo) file in a certain directory, but the full file name path actually used is not known until the restore or clone operation is launched. This happens when several databases are restored at the same time to the same LUNs. By default, this is created in the snap-info directory. Example: U:\SMSQL_SnapInfo\VDISK__E\UNDO_SECLOCSYS_db5.dat
$TargetDatabase	Specifies the destination name of the database to restore. Example: DatabaseAccountingRestoredCopy
$TargetServerInstance	Specifies the destination SQL Server instance to be used. Example: ACMESERVER2\SQLINSTANCECOPY
$TargetDatabaseFile	Specifies the target file system database path to be used. Example: Z:\MNT\NETAPP1\Program Files\Microsoft SQL Server\MSSQL.1\MSSQL\Data\DatabaseAccounting.mdf

Command arguments that are operation-specific

Each SnapManager operation that supports the Run Commands feature parses only the variables that apply to the operation as you have specified it.

The following table shows which of the command variables are available to the Run Commands feature, depending on which SnapManager operation is used to invoke the feature.

Variable	SnapManager operation that is used to invoke the Run Commands feature
Variable	Full backup	Transaction log backup	Verification of full backup	Restore	Clone
$Database	Parsed	Parsed	Parsed	Parsed	Parsed
$InfoSnapshot	Parsed	Parsed	—	—	—
$LogBackupFile	Parsed	Parsed	—	—	—
$ServerInstance	Parsed	Parsed	Parsed	Parsed	Parsed
$OperationStatus	Parsed	Parsed	Parsed	Parsed	Parsed
$PreCommandStatus	Parsed	Parsed	Parsed	Parsed	Parsed
$SnapInfoName	Parsed	Parsed	Parsed	—	—
$SnapInfoPath	Parsed	Parsed	Parsed	—	—
$SqlSnapshot	Parsed	—	Parsed	Parsed	Parsed
$StandbyFile	—	—	—	Parsed	Parsed
$TargetDatabase	—	—	—	Parsed	Parsed
$TargetDatabaseFile	—	—	—	Parsed	Parsed
$TargetServerInstance	—	—	—	Parsed	Parsed

Any argument can be repeated, and if multiple databases or servers are backed up, they are substituted in order. If no value that corresponds to the $NNNN parameter exists, then a string that reads "NULL" is substituted for the $NNNN parameter.
Full backup with the Run Transaction Log Backup option selected: The $LogBackupFile variable is parsed only when the transaction logs are backed up after full backup.