Sending data to a server

Edit online

The API permits application clients to send data or named objects and their associated data to IBM® Storage Protect server storage.

Tip: You can either back up or archive data. Perform all send operations within a transaction.

The transaction model

All data sent to IBM Storage Protect storage during a backup or archive operation is done within a transaction. A transaction model provides a high level of data integrity, but it does impose some restrictions that an application client must take into consideration.

Start a transaction by a call to dsmBeginTxn or end a transaction by a call to dsmEndTxn. A single transaction is an atomic action. Data sent within the boundaries of a transaction is either committed to the system at the end of the transaction or rolled back if the transaction ends prematurely.

Transactions can consist of either single object sends or multiple object sends. To improve system performance by decreasing system overhead, send smaller objects in a multiple object transaction. The application client determines whether single or multiple transactions are appropriate.

Send all objects within a multiple object transaction to the same copy destination. If you need to send an object to a different destination than the previous object, end the current transaction and start a new one. Within the new transaction, you can send the object to the new copy destination.

Note: Objects that do not contain any bit data ( sizeEstimate=0 ) are not checked for copy destination consistency.

IBM Storage Protect limits the number of objects that can be sent in a multiple object transaction. To find this limit, call dsmQuerySessInfo and examine the maxObjPerTxn field. This field displays the value of the TXNGroupmax option that is set on your server.

The application client must keep track of the objects sent within a transaction to perform retry processing or error processing if the transaction ends prematurely. Either the server or the client can stop a transaction at any time. The application client must be prepared to handle sudden transaction ends that it did not start.

File aggregation

IBM Storage Protect servers use a function that is called file aggregation. With file aggregation, all objects sent in a single transaction are stored together, which saves space and improves performance. You can still query and restore the objects separately.

To use this function, all of the objects in a transaction should have the same file space name. If the file space name changes within a transaction, the server closes the existing aggregated object and begins a new one.

LAN-free data transfer

The API can take advantage of LAN-free data transfer if the dsmSetUp option for multithreading is ON. The API returns the existence of a LAN-free destination in the Query Mgmt Class response structure archDetailCG or backupDetailCG field bLanFreeDest.

You can use LAN-free operations on platforms that are supported by the storage agent. Macintosh platform is excluded.

LAN-free information is provided in the following output structures. The out structure (dsmEndGetDataExOut_t) for dsmEndGetData includes the field, totalLFBytesRecv. This is the total number of LAN-free bytes that are received. The out structure (dsmEndSendObjExOut_t) for dsmEndSendObjEx includes the field, totalLFBytesSent. This is the total number of LAN-free bytes that were sent.

Simultaneous-write operations

You can configure IBM Storage Protect server storage pools to write simultaneously to a primary storage pool and copy storage pool or pools during a backup or archive. Use this configuration to create multiple copies of the object.

If a simultaneous-write operation fails, the return code on the dsmEndTxn function might be DSM_RC_ABORT_STGPOOL_COPY_CONT_NO, which indicates that the write to one of the copy storage pools failed, and the IBM Storage Protect storage pool option COPYCONTINUE was set to NO. The application terminates and the problem must be resolved by the IBM Storage Protect server administrator.

For more information about setting up simultaneous-write operations, see the IBM Storage Protect server documentation.

Enhancing API performance

You can use the tcpbuffsize and tcpnodelay client options and the DataBlk API parameter to enhance API performance.

Table 1 describes the actions that you can take to enhance the API performance.

Table 1. Backup-archive options and the API parameter that enhance performance
Backup-archive client options	Description
tcpbuffsize	Specifies the size of the TCP buffer. The default value is 31 KB. To enhance performance, set the value to 32 KB.
tcpnodelay	Specifies whether to send small buffers to the server rather than holding them. To enhance performance, set this option to yes for all platforms. This option is valid for Windows and AIX® only.
API parameter	Description
DataBlk	This parameter is used with the dsmSendData function call to determine the application buffer size. For best results, set the parameter as a multiple of the tcpbuffsize value that is specified with the tcpbuffsize minus 4 bytes. For example, set a value of 28 for this parameter when the value of tcpbuffsize is set to 32 KB.

Each dsmSendData call is synchronous and does not return until the data transferred to the API in the dataBlkPtr is flushed to the network. The API adds a 4-byte overhead to each transaction buffer that is placed on the network.

For example, when the transaction buffer size is 32 KB and the application DataBlk buffer size is 31 KB, then each application DataBlk buffer fits in a communications buffer and can be flushed immediately. However, if the application DataBlk buffer is exactly 32 KB, and because the API is adding 4 bytes per transaction buffer, two flushes are required; one of 32 KB and one of 4 bytes. Also, if you set the tcpnodelay option to no, flushing the 4 bytes might take up to 200 milliseconds.