LiteSpeed for SQL Server 8.9.8 - Security and Compliance Guide

xp_extractor

Converts LiteSpeed backups to native SQL Server backups.

This topic covers:

• Syntax

• Arguments

• Examples

• Returns

Syntax

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

exec master..xp_extractor
@FileName = N'C:\Backups\backup.bkp',
@FileNumber = 1,
@Init = 1,
@MTFFile = N'C:\Backups\backup.bkp.bak'

Arguments

Tips:

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

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

@affinity @backupfile @backupindex @basesize @encryptionkey @filename @filenumber @init @ioflag @logging @maxtransfersize @mtffile @priority @showhelp

@throttle @trace @tsmarchive @tsmclientnode @tsmclientownerpwd @tsmconfigfile @tsmdevicetimeoutminutes @tsmfile @tsmobject @tsmpassword @tsmpointintime @tsmusername @vlf @vlfmaxsize

@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, an incoming 64-bit mask will be truncated to 32-bit.

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.

@backupfile

The name of the LiteSpeed backup device file to be extracted. This argument accepts network destinations.

For TSM backups and TSM archives, this argument accepts the following formats:

• tsmbkp:<filespace>\<high>\<low>

• tsmarc:<filespace>\<high>\<low>

You can supply multiple instances of this argument.

@backupindex

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.

@basesize

The smallest chunk of memory LiteSpeed attempts to write to disk at any given time.

@encryptionkey

Type: Varchar

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

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

Example of key: 'Mypassword'

@filename

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

@filenumber

Type: Integer

Disk restores:

Specifies the particular backup to use when recasting, restoring, extracting or reading from files with multiple appended backups. A backup file can contain multiple backups. Each time you append a new backup, a sequential number is assigned to this backup within the backup file. You can run xp_restore_headeronly to query the files contained within the backup set given by backup_file_name.

Tape restores:

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

@init

Type: Integer

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. Equivalent to WITH INIT in native SQL Server backups. For TSM backups, this will create the TSM object and version the backup based on the retention policy. The argument accept the values:0 (appends the backup to an existing backup file)1 (overwrite the existing target backup file)

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.

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

@mtffile

Specify the location and name of the Microsoft Tape Format (MSTF) base file.

The extractor utility will create one backup device file for each thread used in a LiteSpeed backup.

The extracted files containing the native SQL Server backup will have the following format: base_file_namex.

Where:

• base_file_name is the specified Microsoft Tape Format base file.

• x is a number or letter that represents the sequence of the files. In case there are no additional files, the base file will not have an x appended to its name.

NoteS:

• You can specify a network destination for this parameter.

• You only need to specify this parameter once. The extraction utility will create all the necessary files automatically.

• You cannot tell the extraction utility to extract a different number of native SQL Server files. However, you can specify different destinations for the extracted files by supplying a file name with the -E parameter for each of the native SQL Server files. To see how many files extractor.exe will create, run it without this parameter. See example 4 for more information.

• If a full path is not specified, the extracted files will be created in the current directory.

@priority

Type: Integer

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

• 0—Normal (Default)

• 1—AboveNormal

• 2—High

@showhelp

Displays the syntax summary of the LiteSpeed command-line utility.

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

@trace

Used by LiteSpeed to activate trace logging.

@tsmarchive

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

• 0—False (default)
• 1—True

@tsmfile

Specifies the TSM file.

@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 in the advent that a MAX TAPE MOUNTS EXCEEDED error is received from TSM at the start of the backup. This parameter ensures that the TSM device is acquired and dedicated to this backup before the backup actually begins. If this parameter is not set or passed in then no timeout is used and instead the backup will then fail immediately if the MAX TAPE MOUNTS EXCEEDED is received from TSM.

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

@tsmpassword

The TSM username password. Passwords are case-sensitive.

@tsmpointintime

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

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

@tsmusername

The TSM username ID.

@vlf

Virtual log files are the unit of truncation for the transaction log.

@vlfmaxsize

The maximum size of virtual log files. The number of virtual log files can grow based on the auto growth settings for the log file and how often the active transactions are written to disk. Too many virtual log files can cause transaction log backups to slow down and can also slow down database recovery.

Examples

Encrypted backup conversion

exec master..xp_extractor
@FileName = N'C:\Backups\backup.bkp',
@FileNumber = 1,
@EncryptionKey = N'password',
@Init = 1,
@MTFFile = N'C:\Backups\backup.bkp.bak'

Striped backups

exec master..xp_extractor
@FileName = N'C:\Backups\backupStripe1.bkp',
@FileName = N'C:\Backups\backupStripe2.bkp',
@FileName = N'C:\Backups\backupStripe3.bkp',
@Init = 1,
@MTFFile = N'C:\Backups\backup.1.bak',
@MTFFile = N'C:\Backups\backup.2.bak'

Returns

0 (success) or non-zero (failure). Message indicating success or failure of the operation. Return codes represent the native error number returned from SQL Server for any errors encountered during the operation. Result codes returned from the LiteSpeed utilities are added 50000 to keep them separate from the SQL Server code range.

To capture the output message, run the following:

declare @rmsg varchar(999)
exec master..<xp_extractor> <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..<xp_extractor> <arguments>, @resultmsg=@rmsg output, @resultcode=@rc output
select @rc, @rmsg

 

Related Topic

Convert LiteSpeed Backups to SQL Server Backups