Starting or ending a session

IBM® Storage Protect is a session-based product, and all activities must be performed within an IBM Storage Protect 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 be called only before the dsmInitExcall. The function 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 a session starts.

Each time an API application client starts a session with the server, the client application type is registered with the server. Always specify an operating system abbreviation for the application type value 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 IBM Storage Protect 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 IBM Storage Protect options. These values override the values that are set in the user configuration files during installation. Users cannot change the options that the administrator defines. If the application client does not have a specific configuration file and option list, you can set both of these parameters to NULL. For more information about configuration files, see the following topic:

Understanding configuration and options files

The dsmInitEx function call establishes the IBM Storage Protect session, by using parameters that permit extended verification.

Check the dsmInitEx function call and the dsmInitExOut information return code. The administrator canceled 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. The call 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.

After 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. Any connection with the server is closed and all resources that are associated with this session are freed.

For an example of starting and ending a session, see the following topic:

An example of starting and ending a session

The example defines a number of global and local variables that are used in calls to dsmInitEx and dsmTerminate.

The dsmInitEx call takes a pointer to dsmHandle as a parameter. The the dsmTerminate call takes the dsmHandle as a parameter.

The example Details of rcApiOut displays the details of rcApiOut. The function rcApiOut calls the API function dsmRCMsg, which 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.