dsmBeginTxn

Edit online

The dsmBeginTxn function call begins one or more IBM® Storage Protect transactions that begin a complete action; either all the actions succeed or none succeed. An action can be either a single call or a series of calls. For example, a dsmSendObj call that is followed by a number of dsmSendData calls can be considered a single action. Similarly, a dsmSendObj call with a dataBlkPtr that indicates a data area containing the object to back up is also considered a single action.

Try to group more than one object together in a single transaction for data transfer operations. Grouping objects results in significant performance improvements in the IBM Storage Protect system. From both a client and a server perspective, a certain amount of overhead is incurred by starting and ending each transaction.

There are limits to what you can perform within a single transaction. These restrictions include:

  • A maximum number of objects that you can send or delete in a single transaction. This limit is located in the data that dsmQuerySessInfo returns in the ApiSessInfo.maxObjPerTxn field. This corresponds to the TxnGroupMax server option.
  • All objects that are sent to the server (either backup or archive) within a single transaction must have the same copy destination that is defined in the management class binding for the object. This value is located in the data that dsmBindMC returns in the mcBindKey.backup_copy_dest or mcBindKey.archive_copy_dest fields.

With the API, either the application client can monitor and control these restrictions, or the API can monitor these restrictions. If the API is monitoring restrictions, appropriate return codes from the API calls inform the application client when one or more restrictions are reached.

Always match a dsmBeginTxn call with a dsmEndTxn call to optimize the set of actions within a pair of dsmBeginTxn and dsmEndTxn calls.

Syntax

dsInt16_t dsmBeginTxn  (dsUint32_t dsmHandle);

Parameters

dsUint32_t dsmHandle (I)
The handle that associates this call with a previous dsmInitEx call.

Return codes

The return code numbers are provided in parentheses ( ).

Table 1. Return codes for dsmBeginTxn
Return code Explanation
DSM_RC_ABORT_NODE_NOT_AUTHORIZED (36) FROMNODE or FROMOWNER is not allowed for TXN operations.