Tivoli Header

Tivoli Storage Manager Using the Application Program Interface


Maintaining Version Control in the API

All APIs have some form of version control, and Tivoli Storage Manager is no exception. The API version that you use in your application must be compatible with the version of the API library that is installed on the end user workstation.

The dsmQueryApiVersionEx should be the first API call that you enter when you use the API. This call:

The API is designed to be upwardly compatible. Applications that are written to older versions or releases of the API library will operate correctly if the end user is running a newer version. See "Summary of Code Changes" for differences between levels.

Determining the release of the API library is very important because some releases might have different memory requirements and data structure definitions. Downward compatibility is unlikely. See Table 11 for information about your platform.

Table 11. Platform Information

Platform Description
Intel The message files must be at the same level as the library (DLL). The dsmtca is not used.
OS/400 The API service program (QANSAPI/QANSAPI), the Trusted Communication Agent program (QANSAPI/DSMTCA), and the message files must be at the same level.
UNIX The API library, the Trusted Communication Agent module (dsmtca), and the message files must be at the same level.

The dsmQueryApiVersionEx call returns the version of the API library that is installed on the end user workstation. You can then compare the returned value with the version of the API that the application client is using.

The API version number of the application client is entered in the compiled object code as a set of four constants defined in dsmapitd.h:

   DSM_API_VERSION
   DSM_API_RELEASE
   DSM_API_LEVEL
   DSM_API_SUB_LEVEL

See Appendix A, API Type Definitions Source File.

The API version of the application client should be less than, or equal to, the API library that is installed on the user's system. Be careful about any other condition. You can enter the dsmQueryApiVersionEx call at any time, whether the API session has been started or not.

Data structures that the API uses also have version control information in them. Structures have version information as the first field. As enhancements are made to structures, the version number is increased. When initializing the version field, use the defined structure Version value in dsmapitd.h.

Figure 1 demonstrates the type definition of the structure, dsmApiVersionEx from the header file, dsmapitd.h. The example then defines a global variable that is named apiLibVer. It also demonstrates how you can use it in a call to dsmQueryApiVersionEx to return the version of the end user's API library. Finally, the returned value is compared to the API version number of the application client.

Figure 1. An Example of Obtaining the Version Level of the API

+--------------------------------------------------------------------------------+
|typedef struct                                                                  |
|{                                                                               |
|        dsUint16_t stVersion;     /* Structure version                */        |
|        dsUint16_t version;       /* API version                      */        |
|        dsUint16_t release;       /* API release                      */        |
|        dsUint16_t level;         /* API level                        */        |
|        dsUint16_t subLevel;      /* API sub level                    */        |
|} dsmApiVersionEx;                                                              |
|                                                                                |
|dsmApiVersionEx apiLibVer;                                                      |
|                                                                                |
|memset(&apiLibVer,0x00,sizeof(dsmApiVersionEx));                                |
|dsmQueryApiVersionEx(&apiLibVer);                                               |
|                                                                                |
|/* check for compatibility problems */                                          |
|dsInt16_t appVersion= 0, libVersion = 0;                                        |
|                                                                                |
|  appVersion = (DSM_API_VERSION * 1000) + (DSM_API_RELEASE * 100) +             |
|               (DSM_API_LEVEL * 10) + (DSM_API_SUBLEVEL)                        |
|  libVersion = (apiLibVer.version * 1000) + (apiLibVer.release * 100) +         |
|                  (apiLibVer.level * 10) + (apiLibVer.subLevel);                |
|                                                                                |
|                                                                                |
|   if (libVersion < appVersion)                                                 |
|   {                                                                            |
|      printf("\n***********************************************************\n");|
|      printf("The TSM API library is lower than the application version\n");    |
|      printf("Install the current library version.\n");                         |
|      printf("*************************************************************\n");|
|      return 0;                                                                 |
|   }                                                                            |
|                                                                                |
|                                                                                |
|printf("* API Library Version = %d.%d.%d.%d  *\n",                              |
|     apiLibVer.version,                                                         |
|     apiLibVer.release,                                                         |
|     apiLibVer.level,                                                           |
|     apiLibVer.subLevel);                                                       |
+--------------------------------------------------------------------------------+


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]