LiteSpeed for SQL Server 8.9 - User Guide

Use Extended Stored Procedures

You can use extended stored procedures to perform LiteSpeed activities without using the LiteSpeed UI Console.

When you install LiteSpeed, the installer registers the LiteSpeed extended stored procedures with every instance of SQL Server selected at installation. These extended stored procedures contain a series of commands that you can execute in SQL Query Analyzer or other SQL scripting tool, such as Toad for SQL Server.

NOTES:

• You can only run LiteSpeed commands on SQL Servers on which the LiteSpeed stored procedures have been registered.
• Extended stored procedures are executed against the master database.

• Review the Syntax sections to see which arguments are mandatory, which are optional, and which are mutually exclusive. Mutually exclusive arguments are separated by a vertical bar. Optional arguments are enclosed in square brackets. Round brackets are used to group arguments.
• Review the Arguments sections for more information about the arguments and accepted values.

• LiteSpeed arguments are flexible and usually do not have any hard coded length limits. Review the following for additional information:

  • Path type parameters are the MAX_PATH for any filesystem being employed.
  • Backup name, database name, etc. are passed into SQL Server and have the same requirements.
  • TSM has a limit on object names.
  • Other than that, you are only limited by OS.

Create Backups

If you want to...	Use...
Back up a database (full, differential, file, or filegroup)	xp_backup_database
Back up a transaction log	xp_backup_log
Back up a database using Fast Compression	xp_slsFastCompression
Backup databases and perform other maintenance tasks	xp_slssqlmaint
Convert a backup to a Double Click Restore	xp_slsCreateDCR

Verify Backups

If you want to...	Use...
Verify the backup without restoring it	xp_restore_verifyonly
Validate that a file has not been corrupted	xp_restore_checksumonly

View Information about Backups

If you want to...	Use...
List header information for all LiteSpeed backups on a backup device	xp_restore_headeronly
View information about a stripe set	xp_restore_setinfo
List the logical file names in a backup	xp_restore_filelistonly
Check a password against a backup	xp_restore_checkpassword

Clean Up Old Backups

If you want to...	Use...
Delete old backups	xp_slsSmartCleanup

Restore Backups and Files

If you want to...	Use...
Restore a database	xp_restore_database
Restore transaction logs	xp_restore_log
Automate restore operations	xp_restore_automated
Restore only files attached to a backup	xp_restore_attachedfilesonly

Recover Objects from Backups

If you want to...	Use...
Restore tables from backups	xp_objectrecovery
List restorable objects in a backup	xp_objectrecovery_viewcontents
Create DDL scripts to recover objects	xp_objectrecovery_createscript
Execute a SELECT statement against the backup (can be used for row-level restores)	xp_objectrecovery_executeselect

Encrypt Passwords

If you want to...	Use...
Check a password against a backup	xp_restore_checkpassword
Encrypt a password for backup	xp_encrypt_backup_key
Encrypt a password for restore	xp_encrypt_restore_key

TSM-Specific Tasks

If you want to...	Use...
Delete an object from a specified TSM location	xp_delete_tsmfile
Retrieve TSM-specific information	xp_view_tsmcontents
See available TSM management classes	xp_view_tsmmc

Check Progress and Memory

If you want to...	Use...
Check the progress of an activity	xp_slsreadprogress
Check available memory	xp_memory_size

LiteSpeed Information

If you want to...	Use...
Manage licensing information	xp_sqllitespeed_licenseinfo
View LiteSpeed components version	xp_sqllitespeed_version

 

 

About Using Extended Stored Procedures

You can use extended stored procedures to perform LiteSpeed activities without using the LiteSpeed UI Console.

When you install LiteSpeed, the installer registers the LiteSpeed extended stored procedures with every instance of SQL Server selected at installation. These extended stored procedures contain a series of commands that you can execute in SQL Query Analyzer or other SQL scripting tool, such as Toad for SQL Server.

NOTES:

• You can only run LiteSpeed commands on SQL Servers on which the LiteSpeed stored procedures have been registered.
• Extended stored procedures are executed against the master database.

• Review the Syntax sections to see which arguments are mandatory, which are optional, and which are mutually exclusive. Mutually exclusive arguments are separated by a vertical bar. Optional arguments are enclosed in square brackets. Round brackets are used to group arguments.
• Review the Arguments sections for more information about the arguments and accepted values.

• LiteSpeed arguments are flexible and usually do not have any hard coded length limits. Review the following for additional information:

  • Path type parameters are the MAX_PATH for any filesystem being employed.
  • Backup name, database name, etc. are passed into SQL Server and have the same requirements.
  • TSM has a limit on object names.
  • Other than that, you are only limited by OS.

Create Backups

If you want to...	Use...
Back up a database (full, differential, file, or filegroup)	xp_backup_database
Back up a transaction log	xp_backup_log
Back up a database using Fast Compression	xp_slsFastCompression
Backup databases and perform other maintenance tasks	xp_slssqlmaint
Convert a backup to a Double Click Restore	xp_slsCreateDCR

Verify Backups

If you want to...	Use...
Verify the backup without restoring it	xp_restore_verifyonly
Validate that a file has not been corrupted	xp_restore_checksumonly

View Information about Backups

If you want to...	Use...
List header information for all LiteSpeed backups on a backup device	xp_restore_headeronly
View information about a stripe set	xp_restore_setinfo
List the logical file names in a backup	xp_restore_filelistonly
Check a password against a backup	xp_restore_checkpassword

Clean Up Old Backups

If you want to...	Use...
Delete old backups	xp_slsSmartCleanup

Restore Backups and Files

If you want to...	Use...
Restore a database	xp_restore_database
Restore transaction logs	xp_restore_log
Automate restore operations	xp_restore_automated
Restore only files attached to a backup	xp_restore_attachedfilesonly

Recover Objects from Backups

If you want to...	Use...
Restore tables from backups	xp_objectrecovery
List restorable objects in a backup	xp_objectrecovery_viewcontents
Create DDL scripts to recover objects	xp_objectrecovery_createscript
Execute a SELECT statement against the backup (can be used for row-level restores)	xp_objectrecovery_executeselect

Encrypt Passwords

If you want to...	Use...
Check a password against a backup	xp_restore_checkpassword
Encrypt a password for backup	xp_encrypt_backup_key
Encrypt a password for restore	xp_encrypt_restore_key

TSM-Specific Tasks

If you want to...	Use...
Delete an object from a specified TSM location	xp_delete_tsmfile
Retrieve TSM-specific information	xp_view_tsmcontents
See available TSM management classes	xp_view_tsmmc

Check Progress and Memory

If you want to...	Use...
Check the progress of an activity	xp_slsreadprogress
Check available memory	xp_memory_size

LiteSpeed Information

If you want to...	Use...
Manage licensing information	xp_sqllitespeed_licenseinfo
View LiteSpeed components version	xp_sqllitespeed_version

 

 

Backup examples - extended stored procedures

Backup examples are included for often used extended stored procedures. All backup type examples, disk backup examples, cloud backup examples, TSM backup examples, and tape examples are categorized. In each category locate the extended stored procedure in the Use this procedure.. column and then select the example link in the To run these backups... column.

All backup type examples

Use this procedure...	To run these backups...
xp_backup_database	Back Up Database with Init
''	Create Differential Backup
''	Back Up Database with Encryption
''	Back Up Database with Multiple Threads
''	Multiple Backup Devices (Striped Backup)
''	Create Filegroup Backup
''	Create Differential Filegroup Backup
''	Create Partial Backup (includes the primary filegroup, all read/write secondary filegroups, and a specified read-only file)
''	Backup all databases
''	Backup user databases
''	Backup selected databases
xp_slsFastCompression	Full backup change of 40%
''	Full backup to multiple locations
''	Force full backup
''	Backup showing FastCompressionExtension argument

Disk backup examples

Use this procedure...	To run these backups...
xp_backup_database	xp_backup_database (Disk)
xp_backup_log	Back Up Log (Disk)

Cloud backup examples

Use this procedure...	To run these backups...
xp_backup_database	Backup database to Amazon S3
"	Backup database to Amazon S3 using @CloudStorageClass
"	xp_backup_database (Amazon S3 using temporary security credentials)
"	Backup database to Microsoft Azure
xp_backup_log	Back Up Log (Microsoft Azure)
xp_slsFastCompression	sls_FastCompression (Microsoft Azure)

TSM backup examples

Use this procedure...	To run TSM backups...
xp_backup_database	xp_backup_database (TSM)
''	Create TSM Archive
xp_backup_log	Back Up Log (TSM)
xp_slsFastCompression	Backup to TSM change of 40%

Tape backup examples

Use this procedure...	To run these backups...
xp_backup_database	Back Up Database to Tape
''	xp_backup_database (Tape)
xp_backup_log	Back Up Log (Tape)

 

 

 

xp_backup_database

Performs full, differential, file, or partial filegroup backups.

This topic covers:

• Examples and Syntax

• Arguments

• Returns

Examples and Syntax

NOTE: You can replace argument values with variables. For more information, see LiteSpeed Variables.

All Backup Examples

Click one:

Back Up Database with Init

Create Differential Backup

Back Up Database with Encryption

Back Up Database with Multiple Threads

Multiple Backup Devices (Striped Backup)

Create Filegroup Backup

Create Differential Filegroup Backup

Create Partial Backup

Backup all databases

Backup user databases

Backup selected databases

xp_backup_database (partial backup)

Tape Backup Examples

Back Up Database to Tape

xp_backup_database (Tape)

Cloud Backup Examples

Backup database to Amazon S3

Backup database to Amazon S3 using @CloudStorageClass

Backup database to Amazon S3 using temporary security credentials

Backup database to Microsoft Azure

Backup database to Google Cloud Storage

Disk Backup Examples

xp_backup_database (Disk)

TSM Backup Examples

xp_backup_database (TSM)

Create TSM Archive

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>

@adaptivecompression @affinity @attachedfile @AWSAccessKey @AWSAccessKeyEnc @AWSBucketName @AWSMaxParts @AWSPartSize @AWSRegionName @AWSSecretKey @AWSSecretKeyEnc @AWSUseGovCloud @AWSUseReducedRedundancy @AWSUseServerSideEncryption @AzureBlobType @backupname @buffercount @CloudAccessKey @CloudAccessKeyEnc @CloudAutoStriping @CloudAutoStripingThreshold @CloudBucketName @CloudGovRegion @CloudParallelUpload @CloudPartSize @CloudRegionName @CloudSecretKey @CloudSecretKeyEnc xp_backup_database @CloudVendor @CloudSessionToken @comment @compressionlevel @cryptlevel @database @desc

@doubleclick @encryptionkey @excludedatabase @expiration @file @filegroup @filename @format @GSProject @init @ioflag @jobp @logging @LSECompatible @maxtransfersize @mirror @MultiDatabaseType @nowrite @olrmap @priority @ProxyHost @ProxyLogin @ProxyPassword @ProxyPasswordEnc @ProxyPort @read_write_filegroups @retaindays @returndetails @rewind @skip

@threads @throttle @tsmarchive @tsmclientnode @tsmclientownerpwd @tsmconfigfile @tsmmanagementclass @tsmobject @unload @UseSSL @verify @with

@adaptivecompression

Automatically selects the optimal compression level based on CPU usage or Disk IO. For more information, see Compression Methods.

You can tell Adaptive Compression to optimize backups either for size or for speed. This argument accepts one of the following values:

• Size
• Speed

@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.

@attachedfile

Specifies filepaths to include in both backup and restore operations. The filepath can be either a single file or a directory. If it is a directory, then LiteSpeed recursively includes all files and subdirectories. All attached files are encrypted and compressed, with all pertinent backup parameters supported. This feature works for disk, tape, TSM, and Double Click Restore as well. You can supply multiple instances of this argument.

When used within the context of a restore operation, the path parameter can be expanded to include a new destination. This form will take the syntax of <file_path> to <new_file_path>. The new filepath can be used to specify a new location but cannot rename a file.

This argument only restores the attached files. It does not restore the database, just the files that were attached to that backup.

NOTES:

• The original entire directory path need not be supplied (e.g. c: to c:\testadSattsm is allowed).

• c:\testad to testadr would restore all files in directory c:\testad to c:\testadr.

@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.

@AWSMaxParts

Is the number of parts that are simultaneously uploaded to Amazon S3. The LiteSpeed default is 3 parts. The number of parts can be up to 5 if there is enough memory available during the upload. If you override this parameter, you may impact memory usage.

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

@AWSPartSize

The size of each part that is uploaded to Amazon S3 (in MB). The LiteSpeed default for Part Size is calculated as a database size divided into 9,000. The default Part Size = 25MB.

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

Notes:

• Amazon S3 has a maximum allowable 10,000 parts per file. If you override this parameter, you may inadvertently go over the 10,000 limit.
• Minimum and maximum values for Part Size are defined by Amazon S3: 5MB and 5120MB (5GB) relatively.
• The maximum object size is 5TB.

TIP: Quest Software recommends using LiteSpeed defaults.

@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 @AWSUseGovCloud argument enables a special restricted region for the US Government use in Amazon S3. This argument accepts one of the following values:

• 0—Do not use government cloud
• 1—Use government cloud

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

@AWSUseReducedRedundancy

The @AWSUseReducedRedundancy argument specifies the use of reduced redundancy storage in Amazon S3. This argument accepts one of the following values:

• 0—Do not use reduced redundancy storage
• 1—Use reduced redundancy storage

Note: This @AWSUseReducedRedundancy argument is replaced with the @CloudStorageClass = 'rrs' argument.

@AWSUseServerSideEncryption

The @AWSUseServerSideEncryption argument enables the encryption of data stored at rest in Amazon S3. This argument accepts one of the following values:

• 0—Do not use Server Side Encryption
• 1—Use Server Side Encryption

@AzureBlobType

The @AzureBlobType argument specifies the types of blobs that can be stored in the Microsoft Azure cloud storage. This argument accepts one of the following values: "Block", "Page".

note: The LiteSpeed auto striping logic used in the @CloudAutoStriping and @CloudAutoStripingThreshold parameters can override the Azure blob limit for LiteSpeed backups.

@backupname

Specifies the name of the backup set.

This argument accepts variables. For more information, see LiteSpeed Variables.

@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, Azure Account Name, Google e-mail styled account.

@CloudAccessKeyEnc

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

@CloudAutoStriping

This parameter enables automatic file striping for LiteSpeed cloud backups.

@CloudAutoStripingThreshold

This parameter contains the stripe size in GBs. LiteSpeed logic uses the database size to make a decision about the number of stripes needed for LiteSpeed cloud backups. For example, if you have a database with a size of 200GB and set @CloudAutoStripingThreshold = 50, then LiteSpeed uses 200/50 = 4 stripes.

@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, Azure Container Name, Google Bucket Name. Google Bucket Name requirements are described at https://cloud.google.com/storage/docs/naming.

@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

@CloudParallelUpload

The @CloudParallelUpload argument, parallel parts transfers, is used to create fast uploads to the Azure Cloud or Amazon S3. The default number of parallel uploads:

• Amazon S3 = 3
• Azure Blob = 20

@CloudPartSize

The @CloudPartSize argument determines the size of each part that is uploaded to the cloud. The default part size:

• Amazon S3 = 25MB
• Azure Blob = 4MB

notes: Minimum part size for Azure Blob = 4MB Minimum part size for Amazon S3 = 5MB

TIP: Quest Software recommends using LiteSpeed defaults.

@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, ca-central-1, eu-central-1, eu-west-1, eu-west-2, ap-south-1, ap-southeast-1, ap-southeast-2, ap-northeast-1, ap-northeast-2, sa-east-1, N'Germany' and N'China'.

@CloudSecretKey

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

@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.

@CloudStorageClass

The @CloudStorageClass argument specifies a range of storage classes established for different use cases including:

For Amazon S3:

• Standard: Standard storage - for general-purpose storage of frequently accessed data.
• Standard-IA: Standard Infrequent Access - for long-lived, but less frequently accessed data.

• RRS: Reduced Redundancy Storage - for non-critical data considering lower level of redundancy rather than Standard storage.

Important: : In versions less than 8.5 you should use --AWSStorageClass. The @AWSStorageClass argument is no longer valid in subsequent LiteSpeed versions after 8.5.

For Google Storage:

• Multi_regional - for frequently accessed data around the world as per serving website content, streaming videos, or gaming and mobile applications.
• Regional - for frequently accessed data in the same region as your Google Cloud DataProc or the Google Compute Engine instances that use it, as per data analytics.
• Nearline - for infrequently accessed data (data you expect to access no more than once per month).
• Coldline - for infrequently accessed data (data you expect to access no more than once per year).

@CloudVendor

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

@CloudSessionToken

Amazon Web Services specific argument.

The @CloudSessionToken argument specifies the session token required for temporary security credentials (see Amazon Web Services SDK documentation for details).

@comment

Appends a user comment to the backup.

This argument accepts variables. For more information, see LiteSpeed Variables.

@compressionlevel

Specifies the compression level for the backup. Valid values are 0 through 8. 0 bypasses the compression routines. The remaining values of 1 through 8 specify compression with increasingly aggressive computation. 2 is the default value for disk backups and 7 is the default value for cloud backups.

When choosing a compression level, it is best to try various options using your equipment and data to determine the best option for your environment. Use the Backup Analyzer to test the performance of different compression levels. For more information, see Test Optimal Backup Settings.

NOTE: If both the compression level and Adaptive Compression option are passed in, LiteSpeed will not error out and will select and use Adaptive Compression.

@cryptlevel

Works in conjunction with the @encryptionkey parameter.

Specify the encryption level. Higher levels improve security, but they require more CPU and take longer. Test Optimal Backup Settings on analyzing the best backup settings for your environment.

This argument accepts one of the following values:

• 0—40-bit RC2

• 1—56 bit RC2

• 2—112 bit RC2

• 3—128 bit RC2

• 4—168 bit 3DES

• 5—128 bit RC4

• 6—128 bit AES

• 7—192 bit AES

• 8—256 bit AES

• 9—MS_AES_128

• 10—MS_AES_192

• 11—MS_AES_256

@database

Name of database to be backed up or restored.

This parameter specifies a database:

• to be backed up (xp_backup_database and xp_slsFastCompression)

• containing the transaction log to be backed up (xp_backup_log)

• to be restored (xp_restore_database and xp_restore_log)

• on which you wish to check the progress of an activity (xp_slsReadProgress)

• for which you want to delete old backups (xp_slsSmartCleanup)

If supplied as a variable (@database), this name can be specified either as a string constant (@database = database name) or as a variable of character string data type, except for the ntext or text data types.

@desc

Specifies a description to store with the backup.

This argument accepts variables. For more information, see LiteSpeed Variables.

@doubleclick

Creates a Double Click Restore executable. This argument accepts one of the following values:

• 1—Creates one Double-Click Restore executable file. Note the following warning: The executable may be greater than 4GB for large databases. Windows Server is unable to run executable files larger than 4GB. However, the file will be convertible/restorable by LiteSpeed file.
• 2—Creates a Double Click Restore loader in the same location. (Default)

For more information, see Double Click Restore Executables.

@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'

@excludedatabase

Name of database(s) to exclude from this backup.

If @ExcludeDatabase is supplied as a variable, this name can be specified either as a string constant (@ExcludeDatabase = database name) or as a variable of character string data type, except for the ntext or text data types.

Tip: The @ExcludeDatabase argument can be applied together with @MultiDatabaseType to exclude several databases from the process.

@expiration

Specifies the date and time when the backup expires. LiteSpeed will not overwrite this file until expiration datetime is passed. This argument accepts one of the following formats:

• yyyy-mm-dd
• yyyy-mm-dd hh:mm:ss

@file

Specifies a logical database file used for file or filegroup backups. You can supply multiple instances of this argument.

@filegroup

Specifies a database filegroup to include in the backup or restore. You can supply multiple instances of this argument.

A filegroup backup is a single backup of all files in the filegroup and is equivalent to explicitly listing all files in the filegroup when creating the backup. Files in a filegroup backup can be restored individually or as a group.

@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.

This argument accepts variables. For more information, see LiteSpeed Variables.

@format

Initializes the media on the device. This argument only applies to tape backups. This argument accepts one of the following values:

• 0—Do not format (default)

• 1—Write new header

• 2—Long erase / write new header

• 3—Low level controller format / write new header

NOTE: Any successful format operation (values 1, 2, and 3; not all are available to all drive types) lays down a LiteSpeed tape header that will identify this tape as containing LiteSpeed backups. Using @init=1 (or -I in the command line) will not lay down a tape header.

@GSProject

DEPRECATED LiteSpeed 8.8: Was used to store for the Google Cloud Storage project ID; the project ID is now obtained from login. This parameter is retained for compatibility with old backup/restore scripts.

@init

Disk or TSM backups

• 0—Appends the backup to an existing backup file set. For TSM backups, it results in an error if the file object already exists.
• 1—Re-initializes (overwrites and replaces) the target backup files. For TSM backups, this will create the TSM object and version the backup based on the retention policy.

Tape backups

• 0—Appends the backup to tape.
• 1—If the tape was previously formatted by LiteSpeed, it wipes out all the backups by writing at the tape's beginning.

See also @format.

NOTE: 0 is the default value if you do not provide this parameter.

@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.

@LSECompatible

Produces a backup that is compatible for use with LiteSpeed Engine for SQL Server. The parameter can be used whenever a new backup file is created and should only be set when backups are needed for cross-compatibility between the products. This switch will force modifications to internal settings such as the thread count, striping model, and encryption levels. In some cases, performance may be degraded. The parameter is ignored when appending to a backup file created without the switch.

This argument accepts one of the following values:

• 0—False (default)
• 1—True

@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).

@mirror

Mirrors the backup file (copies the backup to multiple locations). If you back up the primary to a set of striped files, all mirrored backups must match the primary in the number of stripes in each mirror.

This argument accepts variables. For more information, see LiteSpeed Variables.

@MultiDatabaseType

Produces a backup that includes several types of databases. Types can include: all, system, user, or selected databases.

This argument accepts one of the following values:

• All - Backup all system and user databases.
• System - Backup only system databases.
• User - Backup only user databases.
• Selected - Backup specifically selected databases.

@nowrite

When the backup is completed, it is not written to disk (similar to the native the SQL Native Backup commands: backup database xxx to disk = 'NUL' or backup log xxx to disk = 'NUL' command). This argument accepts one of the following values:

• 0—False (default)
• 1—True

The MSDB history tables are updated with the file name specified, but the file will not get created and no IO is performed.

If compression or encryption parameters are specified, then the data will get compressed or encrypted before being thrown away.

@olrmap

Generates a map file during a backup for Object Level Recovery. This argument accepts one of the following values:

• 0—False (default)
• 1—True

@priority

Specifies the priority of the LiteSpeed process compared to other processes running on the same server. This argument accepts one of the following values:

• -1—Below Normal

• 0—Normal (Default)

• 1—AboveNormal

• 2—High

@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.

@read_write_filegroups

Specifies a partial backup, which includes all the read/write files in a database: the primary filegroup, any read/write secondary filegroups, and any specified read-only files or filegroups. If the database is read-only, @read_write_filegroups includes only the primary filegroup.

@retaindays

Specifies a number of days to retain the backup. LiteSpeed will not overwrite this file for this number of days. 

@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.

@rewind

Applies only to backing up and restoring tape. This argument accepts one of the following values:

• 0—Leave the tape unwound (default)

• 1—Rewind the tape after writing/reading

@skip

Skips normal retention checks and overwrites the backup that has not expired.

• 0—False (default)
• 1—True

@threads

Determines the number of threads used for the backup. You will achieve the best results by specifying multiple threads, but the exact value depends on several factors including: processors available, affinity setting, compression level, encryption settings, IO device speed, and SQL Server responsiveness. The default is n-1 threads, where n is the number of processors.

@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.

You can use the %TSMDEFAULTPATH% variable to make LiteSpeed detect the default TSM configuration file path automatically (by getting from LiteSpeed defaults as a priority or the registry - HKEY_LOCAL_MACHINE\SOFTWARE\IBM\ADSM\CurrentVersion\BackupClient)

@tsmmanagementclass

Specifies the TSM management class. If not specified, LiteSpeed uses the default management class.

@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.

@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)

@verify

Performs a restore verification on the backup file just created (if backup was successful). This argument accepts one of the following values:

• 0—False (default)
• 1—True

@verify is similar to an xp_restore_verifyonly call following xp_backup_database (or log). But if you use variables in the file names, then the caller does not need to determine what file names were chosen. xp_restore_verifyonly

@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
DIFFERENTIAL	Specifies that the database or file backup should consist only of the portions of the database or file changed since the last full backup. A differential backup is usually smaller than a full backup. Use this option so that all individual log backups since the last full backup do not need to be applied.
STATS	Specifies the percentage at which SQL Server returns backup progress. It defaults to 10%.
COPY_ONLY	Specifies the copy-only backup.
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' .
CONTINUE_AFTER_ERROR	Causes the backup be executed despite encountering an invalid backup checksum.
BLOCKSIZE	Specifies the physical block size, in bytes. Supported values are: 512, 1024, 2048, 4096, 8192, 16384, 32768, and 65536 (Default).
PASSWORD	Specifies the password for the backup set.

NOTE: During a full database or differential backup, LiteSpeed backs up enough of the transaction log to produce a consistent database when the database is restored.

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

NOTE: For tape backups, LiteSpeed returns the size and dataset number of the backup file. This number is used in the restore when multiple backups are sent to the same tape.

 

Related Topic

About Using Extended Stored Procedures