Buffer copy elimination

The buffer copy elimination function removes the copy of data buffers between an application and the IBM® Storage Protect server, which results in better processor utilization. For maximum effect, use this approach in a LAN-free environment.

The buffers for data movement are allocated by IBM Storage Protect and a pointer is passed back to the application. The application places the data in the provided buffer, and that buffer is passed through the communication layers to the storage agent by using shared memory. The data is then moved to the tape device, which eliminates copies of data. This function can be used with either backup or archive operations.

The overall sequence of calls for backup/archive is as follows:

dsmInitEx (UseTsmBuffers = True, numTsmBuffers = [how many IBM Storage Protect
            -allocated buffers the application needs to allocate])
dsmBeginTxn
for each object in the txn
  dsmBindMC
    dsmSendObject
      dsmRequestBuffer
      dsmSendBufferData (sends and release the buffer used)
    dsmEndSendObjEx
dsmEndTxn
for each buffer still held
      dsmReleaseBuffer
dsmTerminate       

The dsmRequestBuffer function can be called multiple times, up to the value that is specified by the numTsmBuffers option. An application can have two threads: a producer thread that fills buffers with data; and a consumer thread that sends those buffers to IBM Storage Protect with the dsmSendBufferData call. When a dsmRequestBuffer call is issued and the numTsmBuffers is reached, the dsmRequestBuffer call blocks until a buffer is released. The buffer release can happen by either calling dsmSendBufferData, which sends and releases a buffer or by calling dsmReleaseBuffer. For more information, see callbuff.c in the API sample directory.

If at any point there is a failure in the send, the application must release all the buffers that are held and terminate the session. For example:

  If failure
    for each data buffer held by application
      call dsmReleaseBuffer 
  dsmTerminate

If an application calls dsmTerminate and a buffer is still held, the API does not exit. The following code is returned: DSM_RC_CANNOT_EXIT_MUST_RELEASE_BUFFER. If the application cannot release the buffer, the application must exit the process to force a cleanup.