LiteSpeed for SQL Server 8.6 - User Guide

About Backing Up/Restoring with LiteSpeed LiteSpeed User Interface Configure LiteSpeed for First Use Cloud Back Up Databases Automate Maintenance Tasks Restore Databases Restore Objects View Activity and History Use Command-Line Interface Use Extended Stored Procedures Troubleshoot LiteSpeed Review Additional Resources

xp_slsCreateDCR

xp_slsCreateDCR

This stored procedure converts a Native or LiteSpeed backup file to a Double Click Restore backup, a self-executing and self-extracting backup that can be restored on a server instance that does not have LiteSpeed installed. It also performs a rename on the file if applicable. Double Click Restore Executables

NOTE: A Double Click Restore can only be created for a disk file.

Syntax

exec xp_slsCreateDCR
@FileName='<path>'
[, @doubleclick = 1 | 2 ]

Agruments

@filename

Specifies the path to the backup.

@doubleclick

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

  • 1—Converts a LiteSpeed backup to a Double Click Restore executable, if the size of the backup is less than 4GB. If a backup is a native SQL Server backup or it is larger than 4 GB, it creates a Double Click Restore loader in the same location.
  • 2—Creates a Double Click Restore loader in the same location.

For more information, see Double Click Restore Executables.

Example

exec xp_slscreatedcr
@FileName = N'I:\test\test.bak'

Returns

0 (success) or non-zero (failure).

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 Topics

xp_slsFastCompression

xp_slsFastCompression

xp_slsFastCompression (previously known as xp_slsSmartDiff) performs a full, partial, or differential database backup using Fast Compression technology. Fast Compression

This topic covers:

Syntax

EXEC master.dbo.xp_slsFastCompression
@database = 'database_name'
, @BackupDirectory = 'backup_directory'
{ @ForceFull = 0 | 1
| @ForceDifferential = 0 | 1
| ( @ExtentsChgRatioRequireFull = '1%'..'100%'
| @DiffToFullRatioRequireFull = '1%'..'100%')
[, @CheckForFullBackup = 0 | 1 ]
[, @ElapsedDaysRequireFull = 1...n]
([, @SpecificDaysForbidFull = '1'...'7' ] [,...n])}
[, @FullBackupEscalation = 0 | 1 ]
[, @SearchAlternateBackup = 'backup_directory' ]
[, @MirrorDirectory = 'mirror_directory'] [,...n]
[, @AppendDifferential = 0 | 1 ]
[, @Verify = 'Last' | 'Full' | 'Last,Full' | 'All']
[, @retaindays = 0...2147483647 ]
[, @expiration = 'date_time']
[, @desc = 'backup_description']
[, @backupname = 'backupset_name']
[, @threads = 1..32]
[, @encryptionkey = 'encryption_key']
[, @cryptlevel = 'encryption_level']
[, @file = 'logical_file_name'] [,...n]
[, @filegroup = 'logical_filegroup_name'] [,...n]
[, @priority = -1 | 0 | 1 | 2 ]
[, @with = 'additional_with_parameters'] [,...n]
[, @logging = 0 | 1 | 2 ]
[, @ioflag = 'DISK_RETRY_COUNT=n']
[, @ioflag = 'DISK_RETRY_WAIT=n'] 
[, @affinity = 0..2147483647]
[, @throttle = 1..100]
[, @comment = 'comment']
[, @buffercount = 'buffer_count']
[, @maxtransfersize = 'maximum_transfer_size']
[, @adaptivecompression = 'size' | 'speed' ]
[, @compressionlevel = 'compression_level']
[, @attachedfile = 'pathname']
[, @tsmclientnode = 'TSM_client_node']
[, @tsmclientownerpwd = 'TSM_client_owner_password']
[, @tsmfilespace = 'TSM_file_space'] [,...n]
[, @tsmconfigfile = 'TSM_configuration_file']
[, @tsmmanagementclass = 'TSM_management_class']
[, @tsmdevicetimeoutminutes = n] 
[, @tsmdsmi_dir = 'path']
[, @tsmdsmi_log = 'path']
[, @tsmlogname = 'log_name']
[, @with = 'option_name']
 

xp_slsFastCompression (restore partial backup with fast compression)

NOTE: The following example shows the syntax for performing partial restores using the “read_write_filegroups” parameter. The database used in the example below, FGBackups_PROD, contains the following filegroups: Primary, FG1, FG2, and FG3).

Tip: This example takes a partial backup of the primary and secondary read write filegroups (Primary, FG1, and FG2).

EXEC master.dbo.xp_slsFastCompression

@database = N'FGBackups_PROD'

, @BackupDirectory = 'I:\SQLbackups'

, @ExtentsChgRatioRequireFull = '.4',

@ForceFull = 1,

@read_write_filegroups = 1

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>

FastCompression Arguments: Accepted LiteSpeed Arguments:

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

@AlterDir

Specifies the directory where to search for the backup file.

Note: @AlterDIr replaced @SearchAlternateBackupDirectory in LiteSpeed 8.6. Support for the old @SearchAlternateBackupDirectory parameter will be gradually phased out.

@AppendDifferential

Appends data to an existing full backup file.This argument accepts one of the following values:

  • 0—False (default)
  • 1—True

@attachedfile

  • 0—False (default)
  • 1—True

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

@AWSStorageClass

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

  • 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: This @AWSStorageClass argument is replaced by @CloudStorageClass. The @AWSStorageClass argument is no longer valid in subsequent LiteSpeed versions after 8.5.

@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 @AWSStorageClass = '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.

@BackupDirectory

Specifies a directory for the backup file.

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

@CheckForFullBackup

Checks if the expected full backup exists when backing up to separate files and returns a failure message if it is not found. If the full backup file does not exist, it performs a full backup. If the full backup file does exist, the decision to perform a new full or a differential backup will depend on other conditions specified. Accepts the following values:

  • 0—False (default)
  • 1—True

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

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

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

@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

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

@DiffToFullRatioRequireFull

Specifies the last differential backup size to last full backup size ratio. When exceeding the specified ratio LiteSpeed performs a full backup.

This argument accepts one of the following formats:

  • '.4'
  • '40%'

@DryRun

Shows backups that are candidates for restore at this time, but does not restore them. This argument accepts one of the following values:

  • 0—False (default)
  • 1—True

@ElapsedDaysRequireFull

Specifies the minimum number of days since last full backup required to perform full backup. The default value is 14.

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

@ExtentsChgRatioRequireFull

Specifies the minimum amount of database changes required for the full backup.

This argument accepts one of the following formats:

  • '.4'
  • '40%'

@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

@FastCompressionExtension

Specifies the fast compression file extension. This argument accepts one of the following formats:

  • bak - the default for new items.
  • bkp - for an existing item that does not have an extension defined

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

@FileNumber

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.

@ForceDifferential

Forces differential backup. It accepts the following values:

  • 0—False (default)
  • 1—True

@ForceFull

Forces full backup. This argument accepts one of the following values:

  • 0—False (default)
  • 1—True

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

@FullBackupEscalation

This option causes LiteSpeed to issue a full backup, if one of the following problems is discovered in the current backup set:

  • The full backup is missing.
  • A differential backup is missing from the backup set (excludes backups automatically removed after the specified retention period).
  • LSN verification fails in the backup set.
  • Verify operation fails on full or differential backup.

NOTE: If a problem is detected and a full backup is created through escalation, an error will be returned.

This argument accepts one of the following values:

  • 0—False (default)
  • 1—True

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

@MirrorDirectory 

Specifies a directory for a mirror backup. You can supply multiple instances of this argument.

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

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

@SpecificDaysForbidFull

Specifies days of the week when a full backup is never performed. It accepts the following formats:

  • 3—on Tuesday
  • 'tu'—on Tuesday
  • '5-7'—from Thursday to Saturday
  • 'm, w, su'—on Monday, Wednesday, and Sunday

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

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

@tsmdevicetimeoutminutes

Specifies how long to wait for a TSM device.

@tsmdsmi_dir

DSMI_DIR path if needed.

@tsmdsmi_log

DSMI_LOG path.

@tsmfilespace

Specifies the TSM file space, the logical space on the TSM server. It can be the drive label name or UNC name. You can supply multiple instances of this argument.

NOTE: IBM recommends that an application client should select a unique file space; it is recommended that LiteSpeed users follow this practice with a specific file space reserved for LiteSpeed backups.

@tsmlogname

Log name.

@tsmmanagementclass

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

@tsmpassword

The TSM username password. Passwords are case-sensitive.

@tsmusername

The TSM username ID.

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

  • Last—Verifies last backup performed (can be either a full or differential)
  • Full, Last—Verifies the last full backup and last differential is available
  • All—Verifies last full backup and all differentials since

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

CONTINUE_AFTER_ERROR Causes the backup be executed despite encountering an invalid backup checksum.

Examples

Full backup change of 40%

Back up the Northwind database. Perform full backup only if the amount of database changes since the last full backup is more than 40%.

EXEC master.dbo.xp_slsFastCompression
@database = 'Northwind'
, @BackupDirectory = 'C:\Program Files\Microsoft SQL Server\MSSQL.1\MSSQL\Backup'
, @ExtentsChgRatioRequireFull = '.4'

Full backup to multiple locations

Back up the Northwind database to multiple locations. Perform full backup only if more than 10 days have passed since last full backup.

EXEC master.dbo.xp_slsFastCompression
@database = 'Northwind'
, @BackupDirectory = 'C:\Program Files\Microsoft SQL Server\MSSQL.1\MSSQL\Backup'
, @MirrorDirectory = 'D:\SQLServerBackups'
, @ElapsedDaysRequireFull = 10

Force full backup

Back up the Northwind database. Force full backup.

EXEC master.dbo.xp_slsFastCompression

@database = 'Northwind'

, @BackupDirectory = 'C:\Program Files\Microsoft SQL Server\MSSQL.1\MSSQL\Backup'

, @ForceFull = 1

Backup to TSM change of 40%

Backup to TSM. Perform full backup only if the amount of database changes since the last full backup is more than 40%.

exec master.dbo.xp_slsFastCompression

@database = N'userdb3',

@backupname = N'userdb3 - Fast Compression Backup',

@desc = N'Fast Compression Backup of userdb3',

@AdaptiveCompression = 'Speed',

@ExtentsChgRatioRequireFull = N'40%',

@tsmfilespace = N'FC',

@tsmconfigfile = N'C:\Program Files\Tivoli\TSM\baclient\dsm.opt',

@tsmclientnode = N'w2k3_TSM',

@tsmclientownerpwd = N'***',

@tsmmanagementclass = N'STANDARD',

@tsmdevicetimeoutminutes = 2,

@FullBackupEscalation = 1

Backup showing FastCompressionExtension argument

Backup showing FastCompressionExtension argument using existing item bkp file extension.

exec master.dbo.xp_slsFastCompression

@database = N'A1',

@backupname = N'A1 - Fast Compression Backup',

@desc = N'Fast Compression Backup of A1',

@compressionlevel = 2,

@comment = N'',

@AppendDifferential = 0,

@CheckForFullBackup = 1,

@ExtentsChgRatioRequireFull = N'35%',

@BackupDirectory = N'D:\Backups',

@FullBackupEscalation = 1,

@ElapsedDaysRequireFull = 14,

@FastCompressionExtension = ‘bkp’

sls_FastCompression (Microsoft Azure)

exec master.dbo.xp_slsFastCompression

@database = N'newtest',

@backupname = N'newtest - Fast Compression Backup',

@desc = N'Fast Compression Backup of test',

@compressionlevel = 7,

@comment = N'',

@ExtentsChgRatioRequireFull = N'35%',

@BackupDirectory = N'test',

@CloudVendor = N'AzureBlob',

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

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

@CloudBucketName = N'test',

@AzureBlobType = N'Page',

@UseSSL = 1,

@FullBackupEscalation = 1,

@ElapsedDaysRequireFull = 14

Returns

0 (success) or non-zero (failure).

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 Topics

Fast Compression Backup

xp_slsReadProgress

xp_slsreadprogress

Reads the progress of the current activity on a specified database and returns an integer (0-100) indicating the percentage completed of the current activity on the specified database.

This topic covers:

Syntax

EXEC master.dbo.xp_slsreadprogress
@database = 'database_name'

Examples

  1. Read the progress of the current activity at a specified database:

    exec xp_slsreadprogress @database='Northwind'

    This command returns the percentage complete, for example:

    (1 row(s) affected)

    96 percent completed

  2. Query the progress of an activity based on the result returned (in this case print 'DONE' when the progress is 100 percent):

    Declare @Result int
    exec xp_slsreadprogress @database='Northwind',
    @Percent = @Result output
    if @Result = 100
    begin
    print 'Done'
    end

 

Related Topic

xp_slsSmartCleanup

xp_slsSmartCleanup

Removes full and differential backup files and transaction log backups based on a user-defined period (either the file age or the date).

The backup retention will never delete:

  • The backup files, if there are mixed backups in the same backup file. For example, if a user performs a backup of AdventureWorks and Pubs into the same mybackups.bak backup file.
  • The full backup, if there are associated differential or t-log backups in the backup set that are not eligible for cleanup.
  • File/FileGroup backups
  • File/FileGroup differential backups
  • Partial backups
  • Partial differential backups
  • Files that have the filesystem archive bit set (if that option is selected)

This topic covers:

Syntax

exec master.dbo.xp_slsSmartCleanup
@database = 'database_name'
, (@BackupRetainDays = 1...365 | @BackupExpiration = 'date_time')
, (@LogRetainDays = 1...365 | @LogExpiration = 'date_time')
[, @KeepArchiveFiles = 0 | 1 ]
[, @CopyOnlyBackups = 'option']
[, @DryRun = 0 | 1 ]
[, @TSMClientNode = 'TSM_client_node']
[, @TSMUserName = 'TSM_username_ID']
[, @TSMPassword = 'TSM_username_password']
[, @TSMConfigFile = 'TSM_configuration_file']
[, @TSMClientOwnerPwd = 'TSM_client_owner_password']
[, @TSMDSMI_DIR = 'path']
[, @TSMDSMI_LOG = 'path']
[, @TSMLogName = 'log_name']

xp_slsSmartCleanup (Amazon S3)

exec master.dbo.xp_slsSmartCleanup
@database = N'test',
@CloudVendor = N'AmazonS3',
@CloudBucketName = N'test',
@CloudAccessKeyEnc = N'********',
@CloudSecretKeyEnc = N'*******',
@CloudRegionName = N'us-east-1',
@UseSSL = 1,
@BackupRetainDays = 28,
@LogRetainDays = 7

xp_slsSmartCleanup (Azure)

exec master.dbo.xp_slsSmartCleanup
@database = N'test',
@CloudVendor = N'AzureBlob',
@CloudAccessKeyEnc = N'******',
@CloudSecretKeyEnc = N'*****',
@CloudBucketName = N'test',
@UseSSL = 1,
@BackupRetainDays = 28,
@LogRetainDays = 7

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>

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

@BackupExpiration

Specifies the date using one of the following formats:

YYYY-MM-DD

YYYY-MM-DD HH:MM:SS

where

  • YYYY—4-digit year
  • MM—2-digit month
  • DD—2-digit day of the month
  • HH—2-digit hour using the local 24-hour clock
  • MM—2-digit minute
  • SS—2-digit second

To be eligible for cleanup, the full or differential backup must be older than this date.

@BackupRetainDays

Specifies the number of days (N). The full or differential backup must be at least N days old before it is eligible for cleanup.

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

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

@CloudVendor

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

@CopyOnlyBackups

Controls how LiteSpeed handles copy-only backups. This argument accepts one of the following values:

  • Default—LiteSpeed will ignore copy-only backups except on secondary replicas in AlwaysOn Availability groups, in which case it will allow deletions. This is the default behavior when the parameter is not specified.
  • Ignore—Copy-only backups are never deleted.
  • AllowDeletes—Copy-only backups are removed according to the specified retention options.

NOTES:

  • Transaction log backups are not considered dependent on copy-only full or copy-only tlog backups.
  • Copy-only transaction log backups will not mark other transaction log or full backups as having a dependent.
  • The values are not case-sensitive.

@DryRun

Displays backups that are to be removed (delete candidates) or kept according to the specified conditions and SmartCleanup logic. SmartCleanup does not remove any backups, if this parameter is specified.

@KeepArchiveFiles

Turns on monitoring and refuses to delete files that have the archive filesystem bit set. When enabled dependent files are not deleted.

@LogExpiration

Specifies the date of one of the following formats:

YYYY-MM-DD

YYYY-MM-DD HH:MM:SS

where

  • YYYY—4-digit year
  • MM—2-digit month
  • DD—2-digit day of the month
  • HH—2-digit hour using the local 24-hour clock
  • MM—2-digit minute
  • SS—2-digit second

To be eligible for cleanup, the t-log backup must be older than this date.

@LogRetainDays

Specifies the number of days (N). The t-log backup must be at least N days old before it is eligible for cleanup.

@MultiDatabaseType

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

This argument accepts one of the following values:

  • All - Clean up backups for all system and user databases.
  • System - Clean up backups for only system databases.
  • User - Clean up backups for only user databases.
  • Selected - Clean up backups for specifically selected databases.

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

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

@tsmdsmi_dir

DSMI_DIR path if needed.

@tsmdsmi_log

DSMI_LOG path.

@tsmlogname

Log name.

@tsmpassword

The TSM username password. Passwords are case-sensitive.

@tsmusername

The TSM username ID.

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

Examples

  1. Delete disk full and differential backups older than 28 days, delete log backups older than 2 days, allow deletions of the copy-only backups:

    exec master.dbo.xp_slsSmartCleanup
    @database = 'test2'
    , @BackupRetainDays = 28
    , @LogRetainDays = 2
    , @CopyOnlyBackups = 'AllowDeletes'

  2. Delete disk full and differential backups created before 11/15/2012:

    exec master.dbo.xp_slsSmartCleanup
    @database = 'test2'
    , @BackupExpiration = '2012-11-15'

  3. Delete tsm log backups older than 2 days:

    exec master.dbo.xp_slsSmartCleanup
    @database = N'test_tsm'
    , @tsmconfigfile = N'C:\Program Files\Tivoli\TSM\baclient\dsm.opt'
    , @tsmclientnode = N'w2k3_TSM2'
    , @tsmclientownerpwd = N'*****'
    , @LogRetainDays = 2

  4. Delete full, differential and transaction log TSM backups created before 06/15/2012, using the PASSWORDAccess generate option to connect to the TSM Server:

    exec master.dbo.xp_slsSmartCleanup
    @database = N'test_tsm'
    , @tsmconfigfile = N'C:\Program Files\Tivoli\TSM\baclient\dsm_gp.opt'
    , @BackupExpiration = '2012-06-15'
    , @LogExpiration = '2012-06-15'

  5. Keep archived files older than 2 days:

    exec master.dbo.xp_slsSmartCleanup
    @database = @dbname
    , @BackupRetainDays = 2
    , @LogRetainDays = 1
    , @KeepArchiveFiles = 1

  6. Microsoft Azure cloud cleanup

    exec master.dbo.xp_slsSmartCleanup

    @database = N'test',

    @CloudVendor = N'AzureBlob',

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

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

    @CloudBucketName = N'test',

    @UseSSL = 1,

    @BackupRetainDays = 28,

    @LogRetainDays = 7

Returns

0 (success) or non-zero (failure).

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 Topics

SmartCleanup

Related Documents

Please note our Privacy Policy recently changed to support GDPR. You may read it here. Continuing to use our website indicates you have accepted the new policy.