Maintaining API version control

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 performs the following tasks:

Confirms that the API library is installed and available on the end user's system
Returns the version level of the API library that the application accesses

The API is designed to be upwardly compatible. Applications that are written to older versions or releases of the API library operate correctly when you run a newer version.

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 1 for information about your platform.

Table 1. Platform compatibility information
Platform	Description
Windows	The message files must be at the same level as the library (DLL). The Trusted Communication Agent module (dsmtca) is not used.
UNIX or Linux	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 API type definitions source files.

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 * 10000)+(DSM_API_RELEASE * 1000) +
               (DSM_API_LEVEL * 100) + (DSM_API_SUBLEVEL);   
  libVersion = (apiLibVer.version * 10000) + (apiLibVer.release * 1000) +
                  (apiLibVer.level * 100) + (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);