![]() |
![]() |
The TSM program is a session-based program, and all activities must be performed within a TSM session. To start a session, the application starts the dsmInitEx call. This call must be performed before any other API call other than dsmQueryApiVersionEx, dsmQueryCliOptions, or dsmSetUp.
The dsmQueryCliOptions function can only be called before the dsmInitEx call. It returns the values of important options, such as option files, compression settings, and communication parameters. The dsmInitEx call sets up a session with the server as indicated in the parameters that are passed in the call or defined in the options files.
The client node name, the owner name, and the password parameters are passed to the dsmInitEx call. The owner name is case-sensitive, but the node name and password are not. The application client nodes must be registered with the server before starting a session.
Each time an API application client starts a session with the server, the client application type is registered with the server. We recommend that the application type value contain an operating system abbreviation because this value is entered in the "platform" field on the server. The maximum string length is DSM_MAX_PLATFORM_LENGTH.
The dsmInitEx function call establishes the TSM session with the API configuration file and option list of the application client. The application client can use the API configuration file and option list to set a number of TSM options. These values override the values that are set in the user's configuration files at installation time. They can not change the options that the TSM administrator defines. If the application client does not have its own configuration file and option list, you can set both of these parameters to NULL. For more information about configuration files, see Understanding Configuration Files and Options Files.
The dsmInitEx function call establishes the TSM session, using additional parameters that permit extended verification.
Check the dsmInitEx function call and the dsmInitExOut information return code. The TSM administrator cancelled the last session if the return code is okay (RC=ok) and the information return code (infoRC) is DSM_RC_REJECT_LASTSESS_CANCELED. To end the current session immediately, call dsmTerminate.
The dsmQuerySessOptions call returns the same fields as the dsmQueryCliOptions call. It can be sent only within a session. The values reflect the client options that are valid during that session, from option files, and from any overrides from the dsmInitEx call.
Once a session starts, the application can send a call to dsmQuerySessInfo to determine the server parameters that are set for this session. Items such as the policy domain and transaction limits are returned to the application with this call.
End sessions with a dsmTerminate call. This closes any connection with the server and frees all resources that are associated with this session.
The example in Figure 2 defines a number of global and local variables and then uses them in calls to dsmInitEx and dsmTerminate. The dsmInitEx call takes a pointer to dsmHandle for one of its parameters, while the dsmTerminate call takes the dsmHandle itself. The example in Figure 3 displays the details of rcApiOut. The function, rcApiOut, calls the API function dsmRCMsg, that translates a return code into a message. The rcApiOut call then prints the message for the user. A version of rcApiOut is included in the API sample application. The dsmApiVersion function is a type definition that is found in the header file, dsmapitd.h.