Restore optional parameters

Optional parameters are used with the restore command and positional parameters.

The following are detailed descriptions of each of the optional parameters:

/CONFIGfile=configfilename

The /CONFIGfile parameter specifies the name of the IBM Storage Protect Snapshot configuration file, which contains the values for the IBM Storage Protect Snapshot configurable options. See Set command for details on the contents of the file. Considerations:

configfilename can include a fully qualified path. If configfilename does not include a path, it uses the directory where IBM Storage Protect Snapshot is installed.
If configfilename includes spaces, place it in double quotation marks.
If you do not specify /CONFIGfile, the default value is tdpsql.cfg.
If you specify /CONFIGfile but not configfilename, the default value tdpsql.cfg is used.

/FCMOPTFile=dsmoptfilename

The /FCMOPTFile parameter specifies the IBM Storage Protect Snapshot options file to use. Considerations:

The dsmoptfilename variable can include a fully qualified path. If you do not include a path, the IBM Storage Protect Snapshot installation directory is used.
If the dsmoptfilename variable spaces, enclose it in double quotation marks.
If you do not specify /FCMOPTFile, the default value is dsm.opt.
If you specify /FCMOPTFile but not dsmoptfilename, the default is also dsm.opt.

/FROMSQLSERVer=sqlservername

For restore, the /fromsqlserver parameter specifies the SQL server that backup objects were backed up from. This parameter is necessary only when the name of the SQL Server to restore to, as determined by the /sqlserver parameter, is different from the name of the SQL Server that the backup objects were created from. Use /fromsqlserver for query FCM commands, but use /sqlserver for query SQL commands. The default value is the /sqlserver value or the value that is set in the IBM Storage Protect Snapshot configuration file. If the two SQL Server names are different, you must use this parameter even if /fromsqlserver was a non-clustered default instance.

/INSTANTRestore=Yes|No

Use the /INSTANTRestore parameter to specify whether to use volume level snapshot or file level copy to restore a VSS backup that is stored on local shadow volumes. An IBM® Systems Storage SAN Volume Controller, DS8000®, the XIV® system, and IBM Storwize® V7000 storage subsystem is required to run VSS instant restores.

You can specify:

Yes: Use volume level snapshot restore for a VSS backup that is stored on local shadow volumes if the backup exists on volumes that support it. This option is the default.
No: Use file-level copy to restore the files from a VSS backup that is stored on local shadow volumes. Bypassing volume-level copy means that SQL database files and log files are the only data overwritten on the source volumes.

When you are running VSS instant restore on DS8000 and Storwize family, ensure that any previous background copies that involve the volumes you are restoring, complete before you initiate the VSS instant restore operation.

/INTO=dbname

For restore operations, /INTO specifies the SQL Server database that you want a backup object that is restored into. This parameter is necessary only when the name of the SQL Server database to restore into is different from the backup object database name. Considerations:

When you specify /INTO, the asterisk (*) wildcard character might not be used in either the command dbname variable or the /INTOdbname variable.
There must be exactly one item in the /INTO dbname variable list in addition to in the command dbname list.
Make sure to use the /relocatedir parameter when you specify /INTO dbname.

/KEEPCdc

If change data capture is enabled for an SQL Server database and database tables, change-data-capture records that recorded activity, such as insertions, deletions, and edits to the database tables can be retained when you restore the database. The /KEEPCdc parameter is necessary if you are restoring the database to a different database name on the same SQL Server instance or to a different SQL Server instance. When you run restore operations with the /KEEPCdc parameter, you must also set /RECOVery=Yes.

This parameter applies to the following types of legacy backups: full, copy-only full, differential, file, set, and group. For VSS restore operations, you do not need to maintain change data capture information.

Note: If you are restoring the database to its original location, that is the SQL Server instance and database name, change data capture records are retained automatically.

For more information about change data capture, see Microsoft documentation.

/LOGFile=logfilename

The /LOGFile parameter specifies the name of the activity log that is generated by IBM Storage Protect Snapshot. This activity log records significant events such as completed commands and error messages. The IBM Storage Protect Snapshot activity log is distinct from the SQL Server error log. The /LOGFile= variable identifies the name to be used for the activity log generated by IBM Storage Protect Snapshot. Considerations:

If the specified file does not exist, it is created. If it does exist, new log entries are appended to the file.
The file name can include a fully qualified path; however, if you specify no path, the file is written to the directory where IBM Storage Protect Snapshot is installed.
You cannot turn off IBM Storage Protect Snapshot logging activity. If you do not specify /LOGFile, log records are written to the default log file. The default log file is tdpsql.log.
When you use multiple simultaneous instances of IBM Storage Protect Snapshot for operations, use the /LOGFile parameter to specify a different log file for each instance used. This function directs logging for each instance to a different log file and prevents interspersed log file records. Failure to specify a different log file for each instance can result in unreadable log files.

/LOGPrune=numdays|No

When you prune log data, you can discard some of the generated logs according to detailed filtering criteria that you set. Depending on the option that you set for the /LOGPrune parameter, a certain number of days of data are saved. By default, 60 days of log entries are saved. The option No can be entered to disable log pruning.

Regardless of the option that you set for this parameter, you can explicitly request log pruning at any time.

Considerations:

For numdays, the range is 0 to 9999. A value of 0 deletes all entries in the activity log file except for the current command entries.
If you specify no, the log file is not pruned.
If you do not specify /LOGPrune, the default value is that specified by the logprune configurable option in the configuration file. The default value is 60.
If you specify /LOGPrune, its value is used instead of the value that is stored in the configuration file. Specifying this parameter does not change the value in the configuration file.
You can specify /LOGPrune without specifying numdays or no; in this case, the default value, 60, is used.
Changes to the value of the TIMEformat or DATEformat parameter can result in an unwanted pruning of the log file. If you are running a command that might prune the log file, and the value of the TIMEformat or DATEformat parameter is changed, complete one of the following to prevent unintentional pruning of the log file:
- Make a copy of the existing log file.
- Specify a new log file with the /LOGFile parameter or logfile setting.

/OBJect=*|objectname,...

For restore and deactivate operations, /OBJect specifies that only particular backup objects for the specified SQL databases and backup object type if specified are restored. For query operations, /OBJect includes particular objects and object types in the display. The objectname variable specifies the names of the backup objects you want to restore or deactivate. The object name uniquely identifies each backup object and is created by IBM Storage Protect Snapshot. Use query to view the names of backup objects. Considerations:

If you do not specify restore, only the active backup object is included in the restore.
You can specify the asterisk (*) wildcard character in objectname to replace zero or more characters for each occurrence. Specifying only the wildcard character indicates all backup objects of the specified SQL databases and backup object type.

/QUERYNode=DP|ALWAYSON

Specify whether you want to query standard databases from SQL Server 2012 that were backed up from a standard IBM Storage Protect Snapshot for Microsoft SQL Server node or the AlwaysOn node. This parameter is ignored for availability databases because the availability databases are always backed up under the AlwaysOn node. The default value is DP. To query backups of AlwaysOn Availability databases, specify

/QUERYNode =
ALWAYSON

/Quiet

The /Quiet parameter omits displaying status information from the command. However, the information is appended to the IBM Storage Protect Snapshot activity log.

/RECOVery=Yes|No

For restore operations, /RECOVery specifies whether you want to restore more to an SQL database that is not on a standby SQL Server. A restored database cannot be used until the /RECOVery=yes parameter is administered to the database. You can specify:

Yes (default): Use when you make a sequence of restores to an SQL database and the current restore is the final in the sequence. Also, use this option when the restore operation is the only restore operation to an SQL database. This option informs the SQL Server that the restore is complete and ready for incompleted transactions to be rolled back.
No: Whenever you make a sequence of restores to an SQL database and the current restore is not the final restore in the sequence.

Not specifying this option automatically rolls back incomplete transactions for the database.

IBM Storage Protect Snapshot sorts the restore objects by database name, and, within database name, by backup time from earliest to latest time. A query FCM command also displays this order.

/RELOCATEDir=dbfiledir [,logiledir [,otherfiledir] [,filestream files]]

The /RELOCATEDir parameter specifies the new destination locations in which to restore the backed up SQL databases, logs, and SQL Server full-text index files. FILESTREAM files are included for SQL Server 2008 or later versions.

The dbfiledir variable specifies the directory location of the SQL database you want to relocate. Note, if the logfiledir and otherfiledir variables are not specified, the logs and SQL Server full-text index files are restored to the directory specified by dbfiledir.

The logfiledir variable specifies the directory location of the SQL log files you want to relocate. Note, if the logfiledir variable is not specified, the SQL log files are restored to the directory specified by dbfiledir.

The otherfiledir variable specifies the directory location of the SQL Server full-text index files you want to relocate. Note, that if the otherfiledir variable is not specified, the SQL Server full-text index files are restored to the directory specified by dbfiledir.

The filestream files variable specifies the directory location of the SQL Server FILESTREAM data files (SQL Server 2008 or later versions) you want to relocate. Note, if the filestream files variable is not specified, the SQL Server FILESTREAM data files are restored to the directory specified by dbfiledir. Filestream files is available for SQL Server 2008 only.

/RESTOREDAte=date

The /RESTOREDAte parameter specifies a date to which the database identified by dbname is to be recovered. The date value must be specified in the same date format that is defined in the IBM Storage Protect Snapshot preferences file. If /RESTOREDAte is not specified but /RESTORETime is specified, the /RESTOREDAte value is the current date. It can be specified only when you restore a full database backup. The /RESTORETime parameter cannot be used to restore file, group, and set backups.

/RESTORETime=time

The /RESTORETime parameter specifies the time of day to which the database identified by dbname is to be recovered. The time value must be specified in the same time format that is defined in the IBM Storage Protect Snapshot preferences file. If /RESTORETime is not specified but /RESTOREDAte is specified, the /RESTORETime is the current time. It can be specified only when you restore a full database backup. The /RESTORETime parameter cannot be used to restore file, group, and set backups.

/SQLAUTHentication=INTegrated | SQLuserid

This parameter specifies the authorization mode that is used when you log on to the SQL Server. The integrated value specifies Windows authentication. The user ID you use to log on to Windows is the same id you use to log on to the SQL Server. This option is the default value. Use the sqluserid value to specify SQL Server user ID authorization. The user ID specified by the /sqluserid parameter is the id that you use to log on to the SQL Server. Any SQL user ID must have the SQL Server SYSADMIN fixed server role.

/SQLPassword=sqlpasswordname

This parameter specifies the SQL password that IBM Storage Protect Snapshot uses to log on to the SQL Server that objects are backed up from or restored to. Considerations:

Using this parameter means that you are using SQL Server authentication. The SQL Server and the SQL user ID for this password must both be configured for SQL Server authentication.
If you do not specify /SQLPassword, the default value is blank (" ").
If you specify /SQLPassword but not sqlpasswordname, the default is also blank (" ").

This parameter is ignored if you use the /sqlauth=integrated parameter with it.

/SQLSERVer=sqlserver-connection

The /SQLSERVer= parameter specifies the SQL Server that IBM Storage Protect Snapshot logs on to. For restore operations, this SQL Server is the one to which backup objects are restored. However, if the backup objects were created from a different SQL Server name, you must use the /fromsqlserver parameter. Use /sqlserver for the query SQL and backup commands, but use /fromsqlserver for query FCM commands.

The sqlprotocol variable specifies the communication protocol to use. With this variable, you can specify an sqlservername. You can check the SQL connection by using the SQL Server Configuration Manager tool (under SQL Server Native Client Configuration client protocols). You can choose from the following protocols:

Table 1. Table 1. SQL Server connection protocols
Protocol Name	Description	Example Usage (with sqlserver-connection details)
lpc	Shared Memory	/sqlserver=lpc:<servername>\<instancename>
np	Named Pipes	/sqlserver=np:<servername>\pipe You can optionally specify a specific named pipe instance. For example, /sqlserver=np: \\hostname\pipe\pipe name By default, the pipe name is sql\query. If you connect to a named instance, the pipe name is typically in the following format: \\<servername>\pipe\MSSQL$<instancename>\SQL\query
tcp	Transmission Control	/sqlserver=[tcp:]<servername>[\<instancename>][,port]
via	Virtual Interface Adapter	/sqlserver=via:<virtualservername>[\<instancename>]

Note:

For tcp protocols only, you have the option of defining a port. If you do not define a port, the default port value is the SQL default port 1433.
For the via protocol, SQL Server supports this protocol only through SQL Server 2008 R2.
To enable Data Protection for SQL Server to communicate with AlwaysOn Availability Group (AAG) instances, it is not possible to connect to the SQL Server using AAG listeners. For backup and restore operations, you must use the local SQL Server instance name (or instance name and port number) to communicate with the AAG. For AAG (or non-AAG instances), you can also specify non-default port numbers.

If you do not specify a protocol, IBM Storage Protect Snapshot logs on to the SQL Server according to the first protocol that becomes available.

Considerations:

The default value is the value that is specified by the SQL Server configurable option in the IBM Storage Protect Snapshot configuration file. This value is initially the local computer name.
If you specify /sqlserver but not sqlservername, the local computer name is used.
The following two shortcuts are accepted as the local computer name: . (local) These shortcuts are a period or the word local within parentheses.
You must specify the name if the SQL Server is not the default instance or is a member of a failover cluster.
The format of sqlservername depends on what type of instance it is and whether it is clustered or not:
Format Instance? Clustered? Name required?
local-computername default no no
local-computername\instancename named no yes
virtualservername default yes yes
virtualservername\instancename named yes yes

Format	Instance?	Clustered?	Name required?
local-computername	default	no	no
local-computername\instancename	named	no	yes
virtualservername	default	yes	yes
virtualservername\instancename	named	yes	yes

localcomputername: The network computer name of the computer on which the SQL Server and IBM Storage Protect Snapshot are stored. The TCP/IP host name might not always be the same.
instancename: The name given to the named instance of the SQL Server that is specified during installation of the instance.
virtualservername: The name that is given to the clustered SQL Server specified during clustering service setup. This name is not the cluster or node name.

/SQLUSer=sqlusername

The /SQLUSer parameter specifies the name that IBM Storage Protect Snapshot uses to log on to the SQL Server. Considerations:

Using this parameter means that you are using SQL Server authentication. The SQL Server and the SQL user ID for this password must both be configured for SQL Server authentication.
The SQL user ID must have the SQL Server SYSADMIN fixed server role.
If you do not specify /SQLUSer, the default is sa.
If you specify /SQLUSer but not sqlusername, the default is also sa.
This parameter is ignored if you use the /sqlauth=integrated parameter with it.

/VerifyOnly

The /VerifyOnly parameter specifies that a database restore action reads backup data to verify the integrity of the data only; it does not save the backup to disk or overwrite the current database of that name on the SQL server. Before you restore a backup, you can use this parameter to evaluate whether the backup volume is complete and can be read.

If this parameter is not specified, the restore action both verifies the integrity of the backup and also saves the backup to disk on the SQL server.

Restriction: The /VerifyOnly parameter is available only for legacy database backups. This parameter is only a command optional parameter, and it cannot be set as a configuration option.

To verify a backup done with multiple stripes, set the Verify Only parameter to Yes and ensure that the number of stripes that are used for the restore is equal to or greater than the number of stripes that are used for the backup you are verifying. If it is not, the Restore VerifyOnly operation terminates with an error.