dsmInit

Edit online

The dsmInit function call starts an API session and connects the client to IBM® Storage Protect storage. The application client can have only one active session open at a time. To open another session with different parameters, use the dsmTerminate call first to end the current session.

To permit cross-node query and restore or retrieve, use the -fromnode and -fromowner string options. See Accessing objects across nodes and owners for more information.

Syntax

dsInt16_t  dsmInit  (dsUint32_t        *dsmHandle,
   dsmApiVersion *dsmApiVersionP,
   char          *clientNodeNameP,
   char          *clientOwnerNameP,
   char          *clientPasswordP,
   char          *applicationType,
   char          *configfile,
   char          *options);

Parameters

dsUint32_t *dsmHandle (O)
The handle that identifies this initialization session and associates it with subsequent IBM Storage Protect calls.
dsmApiVersion *dsmApiVersionP (I)
A pointer to the data structure identifying the version of the API that the application client is using for this session. The structure contains the values of the three constants, DSM_API_VERSION, DSM_API_RELEASE, and DSM_API_LEVEL, that are set in the dsmapitd.h file. A previous call to dsmQueryApiVersion must be performed to ensure that compatibility exists between the application client API version and the version of the API library that is installed on the user's workstation.
char *clientNodeNameP (I)
This parameter is a pointer to the node for the IBM Storage Protect session. All sessions must have a node name associated with them. The constant, DSM_MAX_NODE_LENGTH, in the dsmapitd.h file sets the maximum size that is permitted for a node name.

The node name is not case-sensitive.

If this parameter is set both to NULL and passwordaccess is set to prompt, the API attempts to obtain the node name first from the options string that was passed. If it is not there, the API then attempts to obtain the node name from the configuration file or options files. If these attempts to find the node name fail, the UNIX or Linux® API uses the system host name, while APIs on other operating systems return the DSM_RC_REJECT_ID_UNKNOWN code.

If this parameter is NULL, and the passwordaccess option in the dsm.opt file (for the Windows API) or in the dsm.sys file (for the UNIX or Linux API) is set to generate, the API uses the nodename option value or the system host name.

char *clientOwnerNameP (I)
This parameter is a pointer to the owner of the IBM Storage Protect session. If the operating system on which the session starts is a multi-user operating system, an owner name of NULL (the root user) has the authority to back up, archive, restore, or retrieve any objects belonging to the application, regardless of the owner of the object.

The owner name is case-sensitive.

If this parameter is NULL and the passwordaccess option in the dsm.sys file is set to generate, the API then uses the login user ID.

Note: On a multi-user operating system, it is not necessary for the owner name to match the active user ID of the session running the application.
char *clientPasswordP (I)
This parameter is a pointer to the password of the node on which the IBM Storage Protect session runs. The DSM_MAX_VERIFIER_LENGTH constant in the dsmapitd.h file sets the maximum size that is permitted for a password.

The password is not case-sensitive.

Except when the password file is first started, the value of this parameter is ignored if passwordaccess is set to generate.

char *applicationType (I)
This parameter identifies the application that is running the session. The application client defines the value.

Each time an API application client starts a session with the server, the application type (or platform) of the client is updated on 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.

To see the current value of the application type, call dsmQuerySessInfo.

char *configfile (I)
This parameter points to a character string that contains the fully-qualified name of an API configuration file. Options specified in the API configuration file override their specification in the client options file. Options files are defined when IBM Storage Protect (client or API) is installed.
char *options (I)
Points to a character string that can contain user options such as:
  • Compressalways
  • Servername (UNIX or Linux only)
  • TCPServeraddr
  • Fromnode
  • Fromowner
  • EnableClientEncryptKey
  • Passwordaccess

The application client can use the option list to override the values of these options that the configuration file sets.

The format of the options is:

  1. Each option that is specified in the option list begins with a dash (-) and is followed by the option keyword.
  2. The keyword, in turn, is followed by an equal sign (=) and then followed by the option parameter.
  3. If the option parameter contains a blank space, enclose the parameter with single or double quotes.
  4. If more than one option is specified, separate the options with blanks.

If options are NULL, values for all options are taken from the user options file or the API configuration file.

Return codes

The return code numbers are provided in parentheses ( ).

Table 1. Return codes for dsmInit
Return code Explanation
DSM_RC_ABORT_SYSTEM_ERROR (1) The server has detected a system error and has notified the clients.
DSM_RC_REJECT_VERIFIER_EXPIRED (52) Password has expired and must be updated.
DSM_RC_REJECT_ID_UNKNOWN (53) Could not find the node name.
DSM_RC_AUTH_FAILURE (137) There was an authentication failure.
DSM_RC_NO_STARTING_DELIMITER (148) There is no starting delimiter in pattern.
DSM_RC_NEEDED_DIR_DELIMITER (149) A directory delimiter is needed immediately before and after the match directories meta-string (...) and one was not located.
DSM_RC_NO_PASS_FILE (168) The password file is not available.
DSM_RC_UNMATCHED_QUOTE (177) An unmatched quote is in the option string.
DSM_RC_NLS_CANT_OPEN_TXT (0610) Unable to open the message text file.
DSM_RC_INVALID_OPT (400) An entry in the option string is invalid.
DSM_RC_INVALID_DS_HANDLE (2014) Invalid DSM handle.
DSM_RC_NO_OWNER_REQD (2032) Owner parameter must be NULL when passwordaccess is set to generate.
DSM_RC_NO_NODE_REQD (2033) Node parameter must be NULL when passwordaccess is set to generate.
DSM_RC_WRONG_VERSION (2064) The API version for the application client has a higher value than the IBM Storage Protect version.
DSM_RC_PASSWD_TOOLONG (2103) The password that was specified is too long.
DSM_RC_NO_OPT_FILE (2220) A configuration file could not be located.
DSM_RC_INVALID_KEYWORD (2221) A keyword that was specified in an options string is invalid.
DSM_RC_PATTERN_TOO_COMPLEX (2222) The include-exclude pattern is too complex for IBM Storage Protect to interpret.
DSM_RC_NO_CLOSING_BRACKET (2223) There is no closing bracket in the pattern.
DSM_RC_INVALID_SERVER (2225) For a multi-user environment, the server in the system configuration file was not found.
DSM_RC_NO_HOST_ADDR (2226) Not enough information to connect to host.
DSM_RC_MACHINE_SAME (2227) The nodename that is defined in the options file cannot be the same as the system host name.
DSM_RC_NO_API_CONFIGFILE (2228) Cannot open the configuration file.
DSM_RC_NO_INCLEXCL_FILE (2229) The include-exclude file was not found.
DSM_RC_NO_SYS_OR_INCLEXCL (2230) Either the dsm.sys file or the include-exclude file was not found.