Db2 APIs for using compression with backup and restore operations

Db2 provides APIs that can be used by third-party compression products to compress and decompress backup images. This interface is designed to augment or replace the compression library that is supported as a standard part of Db2. The compression plug-in interface can be used with the backup and restore Db2 APIs or the backup and restore plug-ins for vendor storage devices.

Db2 defines a set of API prototypes that provide a general purpose interface for compression and decompression that can be used by many vendors. These APIs are to be provided by the vendor in a shared library on Linux® and UNIX systems, or DLL on the Windows operating system. When the APIs are invoked by Db2, the shared library or DLL specified by the calling backup or restore routine is loaded and the APIs provided by the vendor are called to perform the required tasks.

Operational overview

Eight APIs are defined to interface Db2 and the vendor product:
  • InitCompression - Initialize the compression library
  • GetSavedBlock - Get vendor block for backup image
  • Compress - Compress a block of data
  • GetMaxCompressedSize - Estimate largest possible buffer size
  • TermCompression - Terminate the compression library
  • InitDecompression - Initialize the decompression library
  • Decompress - Decompress a block of data
  • TermDecompression - Terminate the decompression library

Db2 will provide the definition for the COMPR_DB2INFO structure; the vendor will provide definitions for each of the other structures and APIs for using compression with backup and restore. The structures, prototypes, and constants are defined in the file sqlucompr.h, which is shipped with Db2 database products.

Db2 will call these APIs, and they should be provided by the vendor product in a shared library on Linux and UNIX systems, or in a DLL on the Windows operating system.

Note: The shared library or DLL code will be run as part of the database engine code. Therefore, it must be reentrant and thoroughly debugged. An errant function might compromise data integrity of the database.

Sample calling sequence

For backup, the following sequence of calls is issued by Db2 for each session: 
   InitCompression
followed by 0 to 1 
   GetMaxCompressedSize
   Compress
followed by 1 
   TermCompress
For restore, the sequence of calls for each session is: 
   InitDecompression
followed by 1 to n 
   Decompress
followed by 1 
   TermCompression

Compression plug-in interface return codes

The following are the return codes that the APIs might return. Except where specified, Db2 will terminate the backup or restore when any non-zero return code is returned.

   SQLUV_OK

0

Operation succeeded

   SQLUV_BUFFER_TOO_SMALL

100

Target buffer is too small. When indicated on backup, the tgtAct field shall indicate the estimated size required to compress the object. Db2 will retry the operation with a buffer at least as large as specified. When indicated on restore, the operation will fail.

   SQLUV_PARTIAL_BUFFER

101

A buffer was partially compressed. When indicated on backup, the srcAct field shall indicate the actual amount of data actually compressed and the tgtAct field shall indicate the actual size of the compressed data. When indicated on restore, the operation will fail.

   SQLUV_NO_MEMORY

102

Out of memory

   SQLUV_EXCEPTION

103

A signal or exception was raised in the code.

   SQLUV_INTERNAL_ERROR

104

An internal error was detected.

The difference between SQLUV_BUFFER_TOO_SMALL and SQLUV_PARTIAL_BUFFER is that when SQLUV_PARTIAL_BUFFER is returned, Db2 will consider the data in the output buffer to be valid.