Considerations for designing an application

Edit online

When you design an application, you must have a broad understanding of many aspects of the API.

To gain an understanding of the API, review the following topics:

When you design your application, review the considerations in Table 1. Start structures with memset fields might change in subsequent releases. The stVersion value increments with each product enhancement.

Table 1. API Considerations for designing an application
Design item Considerations
Setting locale

The application must set the locale before the API is called. To set the locale to the default value, add the following code to the application:

setlocale(LC_ALL,"");

To set the locale to another value, use the same call with the proper locale in the second parameter. Check for specifics in the documentation for each operating system that you are using.
Session control

Apply the following guidelines to session control:

  • Assign a unique node name for each IBM Storage Protect backup-archive client and IBM Storage Protect API client product. The following products are examples of these clients:
    • IBM Storage Protect for Mail
    • or IBM Storage Protect HSM for Windows
  • Use a consistent owner name across a backup and restore procedure.
  • Use the passwordaccess option to manage access to the protected password file.
  • Ensure that sessions for data movement end when the task is completed so that devices on the server are freed for use by other sessions.
  • To permit LAN-free data transfer, use the dsmSetup function call with the multithread flag set to on.
  • On AIX®, when you are using multithreaded applications or LAN-free, especially running on machines with multiple processors, set the environment variable AIXTHREAD_SCOPE to S in the environment before you start the application, for better performance and more solid scheduling. For example: 
      EXPORT AIXTHREAD_SCOPE=S
    By setting AIXTHREAD_SCOPE to S, user threads that are created with default attributes are placed into system-wide contention scope. The user thread is bound to a kernel thread and is scheduled by the kernel. The underlying kernel thread is not shared with any other user thread. For more information, see Using multithreading.
  • Ensure that only one thread in a session calls any API function at any time. Applications that use multiple threads with the same session handle must synchronize the API calls. For example, use a mutex to synchronize API calls:
    • getTSMMutex()
    • issue TSM API call
    • releaseTSMMutex()
    Use this approach only when the threads share a handle. You can use parallel calls to API functions if the calls have different session handles.
Session control (continued)
  • Implement a threaded consumer/producer model for data movement. API calls are synchronous and the calls for dsmGetData function and dsmSendData function block until they are finished. By using a consumer/producer model, the application can read the next buffer during waiting periods for the network. Also, decoupling the data read/write and the network increases performance when there is a network bottleneck or delays. In general, the following holds: 
    Data thread <---> shared queue of buffers <---> communication
thread (issue calls to the IBM Storage Protect API)
  • Use the same session for multiple operations to avoid incurring an overhead. For applications that deal with many small objects, implement session-pooling so that the same session can be used across multiple small operations. An overhead is associated with opening and closing a session to the IBM Storage Protect server. The dsmInit/dsmInitEX call is serialized so even in a multithreaded application only one thread can sign on at any time. Also, during sign-on the API sends a number of one-time queries to the server so that the server can do all operations. These queries include policy, option, file spaces, and local configuration.
Operation sequence

The IBM Storage Protect server locks file space database entries during some operations. The following rules apply when you are designing IBM Storage Protect API applications:

  • Queries lock the file space during the entire transaction.
  • The query lock can be shared with other query operations, so multiple query operations on the same file space can execute concurrently.
  • The following operations are used to modify the IBM Storage Protect server database (DB Chg): send, get, rename, update, and delete.
  • Completion of a DB Chg operation requires a file space lock during the database change at the end of the transaction.
  • Multiple DB Chg operations on the same file space can execute concurrently. There might be a delay while the sequence waits for the lock at the end transaction.
  • The query lock cannot be shared with DB Chg operations. A DB Chg operation delays the beginning of a query on the same file space, so design your applications to separate and serialize queries from DB Chg operations on the same file space.
Object naming When you name objects, consider the following factors:
  • The specific object names are the high-level and low-level object names. If a unique identifier, such as a date stamp, is included in the name, then backup objects are always active. The objects expire only when they are marked inactive by the dsmDeleteObj function call.
  • The restore method for objects determines how to format the name for easy queries. If you plan to use a partial object restore (POR), you cannot use compression. To suppress compression, use the dsmSendObj objAttr objCompressed=bTrue function.
Object grouping Group objects logically by using file spaces. A file space is a container on the server that provides a grouping category for the objects. The API queries all file spaces during the initial sign-on and also during queries, so the number of file spaces must be restricted. A reasonable assumption is that an application sets up 20 - 100 file spaces per node. The API can cater for more file spaces, but each file space incurs an overhead for the session. To create a more granular separation, use the directory object in the application.
Object handling Do not store objectID values to use for future restores. These values are not guaranteed to be persistent during the life of the object.

During a restore, pay special attention to the restore order. After the query, sort on this value before the restore. If you are using multiple types of serial media, then access the different types of media in separate sessions. For more information, see the following topic:

Selecting and sorting objects by restore order
Management class Consider how much control the application must have over the management class that is associated with the application objects. You can define include statements, or you can specify a name on the dsmSendObj function call.
Object size IBM Storage Protect needs to know a size estimate for each object. Consider how your application estimates the size of an object. An overestimation of the object size is better than an underestimation.