Chat now with support
Chat with Support

LiteSpeed for SQL Server 8.5 - Installation Guide

xp_restore_verifyonly

Verifies the backup, but does not restore the backup. It checks to see that the backup set is complete and that all volumes are readable. If the backup is valid, LiteSpeed returns the message from SQL Server: "The backup set is valid."

This topic covers:

Syntax

xp_restore_verifyonly (Disk or TSM)

EXEC master.dbo.xp_restore_verifyonly
@filename = 'backup_file_name' [,...n]
[, @filenumber = n]
[, @encryptionkey = 'encryption_key'| @jobp = 'encrypted_key' ) ]
[, @logging = 0 | 1 | 2 ]
[, @affinity = 0..2147483648]
[, @throttle = 1..100]
[, @ioflag = 'DISK_RETRY_COUNT=n']
[, @ioflag = 'DISK_RETRY_WAIT=n']
[, @buffercount = 'buffer_count']
[, @maxtransfersize = 'maximum_transfer_size']
[, @tsmclientnode = 'TSM_client_node']
[, @tsmclientownerpwd = 'TSM_client_owner_password']
[, @tsmobject = 'TSM_object']
[, @tsmconfigfile = 'TSM_configuration_file'] 
[, @tsmarchive = 1 | 0 ]
[, @tsmpointintime = 'date_time']
[, @returndetails = 0 | 1]

xp_restore_verifyonly (Tape)

EXEC master.dbo.xp_restore_verifyonly
@filename = 'tape_device_name'
[, @filenumber = n]
[, @encryptionkey = 'encryption_key' ]
[, @logging = 0 | 1 | 2 ]
[, @affinity = 0..2147483648]
[, @throttle = 1..100]
[, @unload = 0 | 1 ]
[, @buffercount = 'buffer_count']
[, @maxtransfersize = 'maximum_transfer_size'] 
[, @returndetails = 0 | 1] 

xp_restore_verifyonly (Amazon S3)

exec master.dbo.xp_restore_verifyonly

@filename = N'test\tlogl.bak',

@filenumber = 1,

@CloudVendor = N'AmazonS3',

@CloudBucketName = N'california',

@CloudAccessKey = N'************',

@CloudSecretKey = N'**********',

@UseSSL = 1,

@with = N'STATS = 10',

@with = N'RECOVERY',

@affinity = 0,

@logging = 0

xp_restore_verifyonly (Microsoft Azure)

exec master.dbo.xp_restore_verifyonly

@filename = N'test\test.bak',

@CloudVendor = N'AzureBlob',

@CloudAccessKeyEnc = N'*******',

@CloudSecretKeyEnc = N'******',

@CloudBucketName = N'test',

@UseSSL = 1,

@with = N'STATS = 10',

@with = N'RECOVERY',

@affinity = 0,

@logging = 0

Arguments

Tips:

  • To see the list of accepted arguments and data types for arguments, execute the following:
    exec master.dbo.<procedure_name> show_help

  • To convert the script for use with the command-line utilities, execute the following:
    exec master.dbo.<procedure_name> show_cmd, <xp_arguments>

@affinity

Processor affinity designates specific processors to run LiteSpeed, while not allowing LiteSpeed to run on the remaining processors.

This argument accepts decimal values and hexadecimal values. If a value begins with "0x" it is interpreted as hexadecimal. A positive 64-bit integer value translates to a binary mask where a value of 1 designates the corresponding processor to be able to run the LiteSpeed process.

NOTE: 32-bit Windows is internally limited to a 32-bit mask.

For example, you need to select processors 2, 3, and 6 for use with LiteSpeed. Number the bits from the right to left. The rightmost bit represents the first processor. Set the second, third, and sixth bits to 1 and all other bits to 0. The result is binary 100110, which is decimal 38 or hexadecimal 0x26. Review the following for additional information:

Decimal Value

Binary Bit Mask

Allow LiteSpeed Threads on Processors

0 0 All (default)

1

1

1

3

11

1 and 2

7 111 1, 2 and 3

38

100110

2, 3, and 6

205 11001101 1, 3, 4, 7, and 8

Tip: Before you start tuning the CPU Throttle or Affinity parameters to adjust backup performance, try limiting the number of threads. If you decide to use an affinity value other than default, it is recommended that you limit the threading as well. You may also want to consider using Adaptive Compression to maintain backup performance. For more information, see Adaptive Compression.

@AWSAccessKey

The @AWSAccessKey argument specifies the name of the unique Amazon Web Service alphanumeric access key that identifies each user.

Important: This @AWSAccessKey argument is replaced by @CloudAccessKey. The @AWSAccessKey argument is no longer valid in subsequent LiteSpeed versions after 8.2.

@AWSAccessKeyEnc

The @AWSAccessKeyEnc argument specifies the name of the encrypted unique Amazon Web Service alphanumeric access key that identifies each user.

Important: This @AWSAccessKeyEnc argument is replaced by @CloudAccessKeyEnc. The @AWSAccessKeyEnc argument is no longer valid in subsequent LiteSpeed versions after 8.2.

@AWSBucketName

The @AWSBucketName argument specifies the name of the container for AWS objects. Bucket names must be at least 3 and no more than 63 characters long.

Important: This @AWSBucketName argument is replaced by @CloudBucketName. The @AWSBucketName argument is no longer valid in subsequent LiteSpeed versions after 8.2.

@AWSRegionName

The @AWSRegionName argument specifies the name of the Amazon Web Service region to use for a bucket. Example values are but not limited to: us-east-1, us-west-2, us-west-1, eu-west-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, and sa-east-1.

Important: This @AWSRegionName argument is replaced by @CloudRegionName. The @AWSRegionName argument is no longer valid in subsequent LiteSpeed versions after 8.2.

@AWSSecretKey

The @AWSSecretKey argument specifies the name of the Amazon Web Service secret key that is assigned when you initially get an AWS account.

Important: This @AWSSecretKey argument is replaced by @CloudSecretKey. The @AWSSecretKey argument is no longer valid in subsequent LiteSpeed versions after 8.2.

@AWSSecretKeyEnc

The @AWSSecretKeyEnc argument specifies the name of the encrypted Amazon Web Service secret key that is assigned when you initially get an AWS account.

Important: This @AWSSecretKeyEnc argument is replaced by @CloudSecretKeyEnc. The @AWSSecretKeyEnc is no longer valid in subsequent LiteSpeed versions after 8.2.

@AWSUseGovCloud

The @AWSSecretKeyEnc argument specifies the name of the encrypted Amazon Web Service secret key that is assigned when you initially get an AWS account.

Important: This @AWSSecretKeyEnc argument is replaced by @CloudSecretKeyEnc. The @AWSSecretKeyEnc is no longer valid in subsequent LiteSpeed versions after 8.2.

@buffercount

Specifies the number of SQL Server buffers available for a LiteSpeed operation. The default value is set by SQL Server.

@CloudAccessKey

The @CloudAccessKey argument specifies the name of the unique Cloud Web Service alphanumeric access key that identifies each user. The selections include Amazon Access Key or Azure Account Name.

@CloudAccessKeyEnc

The @CloudAccessKeyEnc argument specifies the name of the encrypted unique Cloud Web Service alphanumeric access key that identifies each user.

@CloudBucketName

The @CloudBucketName argument specifies the name of the container for cloud objects. Bucket names must be at least 3 and no more than 63 characters long. The selections are Amazon Bucket Name or Azure Container Name.

@CloudGovRegion

The @CloudGovRegion argument enables a special restricted region for the US Government use in Amazon S3 and Azure Clouds. This argument accepts one of the following values:

  • 0—Do not use government cloud (default)
  • 1—Use government cloud

@CloudRegionName

The @CloudRegionName argument specifies the name of the Cloud Web Service region to use for a bucket. Example values are but not limited to: us-east-1, us-east-2, us-west-1, us-west-2, eu-west-1, ap-south-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, and sa-east-1.

@CloudSecretKey

The @CloudSecretKey argument specifies the name of the Cloud Web Service secret key that is assigned when you initially get a Cloud account. The selections are Amazon Secret Key or Azure Access Key.

@CloudSecretKeyEnc

The @CloudSecretKeyEnc argument specifies the name of the encrypted Cloud Web Service secret key that is assigned when you initially get a Cloud account.

@CloudVendor

The @CloudVendor argument specifies the name of the cloud service provider. The argument accepts one of the following values: "AmazonS3" or "AzureBlob."

@encryptionkey

Value used to generate the encryption key for the encryption algorithm. If you do not supply encryption key, then the program will not encrypt the backup. If you use the wrong encryption key, the restore will fail.

Caution: When encrypting data, take care not to lose the encryption key; a backup cannot be restored or recovered without the original encryption key.

Example of key: 'Mypassword'

@filename

Specifies a backup location (e.g. C:\backups\AdventureWorks.bak). This argument accepts network destinations. You can supply multiple instances of this argument to use stripe backups.

@filenumber

Disk restores:

Specifies the particular backup to use when recasting, restoring, extracting or reading from files with multiple appended backups. You can run xp_restore_headeronly to query the files contained within the backup set given by backup_file_name.

Tape restores:

Identifies the backup set to be restored. For example, a file number of 1 indicates the first backup set on the backup medium, and a file number of 2 indicates the second backup set.

@ioflag

Specifies if LiteSpeed should wait and retry the read or write operation on failure. You can define retry options using the following parameters:

  • DISK_RETRY_COUNT—Specifies the number of times that a specific operation will be retried on failure. The default is 4 retries, the maximum allowed setting is 1000.
  • DISK_RETRY_WAIT—Specifies the number of seconds to wait immediately following a failure before retrying. The default is 15 seconds, the maximum allowed setting is 300.

NOTE: This functionality is only available for disk and cloud operations.

For example, to specify a database backup where each failure can be retried once after a 30-second wait:

EXEC master.dbo.xp_backup_database
@filename='c:\test.bkp'
, @database='test'
, @ioflag='DISK_RETRY_COUNT=1'
, @ioflag='DISK_RETRY_WAIT=30'

Network Resilience

@jobp

Specifies an encrypted key. (Similar to @EncryptionKey).

You can use xp_encrypt_backup_key to convert the password (encryption_key) for use with @jobp. The original password (or encrypted key generated by xp_encrypt_restore_key) must be used to restore a backup.

@logging

Writes a log file for the operation. This argument accepts one of the following values:

  • 0—Logging off.

  • 1 or any odd value—Logging on. Log file is removed on success.

  • 2 or any even value—Logging on.

The default output directory is C:\Documents and Settings\All Users\Application Data\Quest Software\LiteSpeed\SQL Server\Logs (or C:\ProgramData\Quest Software\LiteSpeed\SQL Server\Logs) (or C:\ProgramData\Quest Software\LiteSpeed\SQL Server\Logs). To log to a different directory add @Trace='logpath=path'.

See Configure Logging in LiteSpeed for information about LiteSpeed logging.

@maxtransfersize

Specifies the largest unit of transfer in bytes to be used between SQL Server and LiteSpeed. The possible values are multiples of 65536 bytes (64 KB) ranging up to 4,194,304 bytes (4 MB). The default is 1048576 (1 MB).

@ProxyHost

The @ProxyHost argument is optional and specifies the name of the proxy host name that is running the proxy server.

note: If the @ProxyHost argument is not defined, then the LiteSpeed core engine checks the local .ini files for the proxy parameters. If the proxy parameters are not detected, then the LiteSpeed core engine connects directly to the proxy servers.

@ProxyLogin

The @ProxyLogin argument is optional and specifies the proxy server login credential.

note: If not defined, then the LiteSpeed core engine checks the local .ini files for the proxy parameters. If the proxy parameters are not detected, then the LiteSpeed core engine connects directly to the proxy servers.

@ProxyPassword

The @ProxyPassword argument is optional and specifies the proxy server password credential.

note: If the @ProxyPassword argument is not defined, then the LiteSpeed core engine checks the local .ini files for the proxy parameters. If the proxy parameters are not detected, then the LiteSpeed core engine connects directly to the proxy servers.

@ProxyPasswordEnc

The @ProxyPasswordEnc argument is optional and specifies the encrypted proxy server password credential.

note: If the @ProxyPasswordEnc argument is not defined, then the LiteSpeed core engine checks the local .ini files for the proxy parameters. If the proxy parameters are not detected, then the LiteSpeed core engine connects directly to the proxy servers.

@ProxyPort

The @ProxyPort argument is optional and contains the port number of the proxy server. The TCP/IP port values can be 1-65535.

note: If the @ProxyPort argument is not defined, then the LiteSpeed core engine checks the local .ini files for the proxy parameters. If the proxy parameters are not detected, then the LiteSpeed core engine connects directly to the proxy servers.

@returndetails

Generates a single-row result set.

  • 0—False (default)
  • 1—True

The result set contains the following details:

Column Name Data Type Description
Database nvarchar (128) Database name.
Operation nvarchar (30) Operation type: Backup or Restore.
Threads tinyint The number of threads used for a LiteSpeed backup.
CompressionLevel tinyint Compression level used for compressing the backup. The compression level can be NULL, if backed up with Adaptive Compression.
AdaptiveCompression nvarchar (max)

Adaptive Compression option used for compressing the backup: 'speed' or 'size'.

MaxTransferSize int Specifies the largest unit of transfer in bytes to be used between SQL Server and LiteSpeed. The possible values are multiples of 65536 bytes (64 KB) ranging up to 4,194,304 bytes (4 MB). The default is 1048576 (1 MB) .
BaseSize int The smallest chunk of memory LiteSpeed attempts to write to disk at any given time.
BufferCount smallint The number of SQL Server buffers available for a LiteSpeed operation.
StripeCount smallint Number of backup files in the stripe set.
OverlappedBuffers tinyint The number of buffers that any single VDI thread can use at a time.
CPUSeconds numeric (18, 3) Processor time used by the LiteSpeed operation.
ElapsedSeconds

numeric (18, 3)

Duration of the operation.
NativeSize bigint Backup size (in bytes) without LiteSpeed compression.
BackupSize bigint Size of the backup (in bytes).

Tip: In Toad, you can use Group Execute to produce a single result set for several server instances.

@throttle

Specifies the maximum CPU usage allowed. The argument accepts an integer value between 1 and 100. The default value is 100. This is the percentage of the total amount of CPU usage (across all enabled processors) available.

TIP: Before you start tuning the CPU Throttle or Affinity parameters to adjust backup performance, try limiting the number of threads. If you decide to use an affinity value other than default, it is recommended that you limit the threading as well. You may also want to consider using Adaptive Compression to maintain backup performance. For more information, see Adaptive Compression.

@tsmarchive

Specifies to store the backup as a TSM archive. This argument accepts one of the following values:

  • 0—False (default)
  • 1—True

@tsmclientnode

Specifies the TSM server LiteSpeed connects to during backups and restores. Not required, if specified in the options file or if backing up with the Passwordaccess Generate option.

@tsmclientownerpwd

Specifies the TSM client owner user password. Not required, if specified in the options file or if backing up with the Passwordaccess Generate option.

@tsmconfigfile

Specifies the TSM configuration file.

@tsmobject

Defines the TSM filespace, high level and low level. This argument accepts the following format:

tsm_filespace\tsm_high_level\tsm_low_level

where:

  • tsm_filespace is the logical space on the TSM server that contains a group of files. It can be the drive label name or UNC name.

  • tsm_high_level specifies the directory path in which the file belongs.

  • tsm_low_level specifies actual name of the file.

NOTE: You may only store one item the location specified by this argument. It is not possible to append an object to this location. You can use the -I command-line argument or @init to back up to a non-unique location.

@tsmpointintime

Specifies the date for restore/to filter results. If it is not passed, LiteSpeed will choose the most recent archived backup. The format is yyyy-mm-dd hh:mm:ss.

NOTE: If the backup was a striped backup and the point-in-times of the various striped files are different (rare but can be different a second or so), then the most recent of the times must be chosen.

@unload

Applies to tape backups and restores. This argument accepts one of the following values:

  • 0—Keep tape loaded (default)

  • 1—Unload and eject tape from the drive after operation

@UseSSL

The @UseSSL argument specifies that the connection uses SSL security. This argument accepts one of the following values:

  • 0—Do not use SSL
  • 1—Use SSL (default)

@with 

Each @with argument should be a syntactically complete and correct statement. Please refer to the SQL Server Transact-SQL backup and restore documentation for the syntax and usage.

The supported formats are:

  • @with='PARAMETER'
  • @with='PARAMETER=''accepted_value'''

NOTES:

  • Extended stored procedure arguments are limited to 255 characters. If you need more than 255 characters, use multiple @with arguments.
  • Do not supply the @with parameter if no additional features are required.

This extended stored procedure accepts the following @with parameters:

Parameter

Description

CHECKSUM

Causes checksums to be verified when a LiteSpeed backup is created.

NOTE: When you restore a backup containing checksum, it is automatically checked. If you do not want to check the checksums during a restore, supply 'NO_CHECKSUM' .

PASSWORD Specifies the password for the backup set.

Example

EXEC master.dbo.xp_restore_verifyonly  

@filename='C:\MSSQL\Backup\MyDB_Backup.BAK'

Returns

0 (success) or non-zero (failure). Return codes represent the native error number returned from SQL Server for any errors encountered during the operation.

To capture the output message, run the following:

declare @rmsg varchar(999)
exec master..<procedure_name> <arguments>, @resultmsg=@rmsg output
select @rmsg

To capture the output message and the result code, run the following:

declare @rc int
declare @rmsg varchar(999)
exec master..<procedure_name> <arguments>, @resultmsg=@rmsg output, @resultcode=@rc output
select @rc, @rmsg

 

Related Topic

Related Documents