IBM Tivoli Storage Manager, Version 7.1

dsmInitEx

The dsmInitEx function call starts an API session using the additional parameters that permit extended verification.

Syntax

dsInt16_t  dsmInitEx   (dsUint32_t        *dsmHandleP,
                        dsmInitExIn_t     *dsmInitExInP,
                        dsmInitExOut_t    *dsmInitExOutP) ;

Parameters

dsUint32_t *dsmHandleP (O)

The handle that identifies this initialization session and associates it with subsequent Tivoli® Storage Manager calls.

dsmInitExIn_t *dsmInitExInP

This structure contains the following input parameters:

dsmApiVersion *dsmApiVersionP (I)

This parameter is a pointer to the data structure that identifies the version of the API that the application client is using for this session. The structure contains the values of the four constants, DSM_API_VERSION, DSM_API_RELEASE, DSM_API_LEVEL, and DSM_API_SUBLEVEL that are set in the dsmapitd.h file. A previous call to dsmQueryApiVersionEx must be performed to ensure that compatibility exists between the API version of the application client and the version of the API library installed on the user's workstation.

char *clientNodeNameP (I)

This parameter is a pointer to the node for the Tivoli Storage Manager 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 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 the APIs from other operating systems return the code, DSM_RC_REJECT_ID_UNKNOWN.

This parameter must be NULL if the passwordaccess option in the dsm.sys file is set to generate. The API then uses the system host name.

char *clientOwnerNameP (I)

This parameter is a pointer to the owner of the Tivoli Storage Manager session. If the operating system is a multi-user platform on which the session is started, 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.

This parameter must be NULL if 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 platform, if passwordaccess is set to prompt, it is not necessary for the owner name to match the active user ID of the session running the application.

char *clientPasswordP (I)

A pointer to the password of the node on which the Tivoli Storage Manager session runs. The DSM_MAX_VERIFIER_LENGTH constant in the dsmapitd.h file sets the maximum size that is allowed 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 *userNameP;

A pointer to the administrative user name that has client authority for this node.

char *userPasswordP;

A pointer to the password for the userName, if a value is supplied.

char *applicationType (I)

Identifies the application that is running the Tivoli Storage Manager session. The application client identifies the value.

Each time an API application client starts a session with the server, the application type (or operating system) 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 view the current value of the application type, call dsmQuerySessInfo.

char *configfile (I)

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 Tivoli Storage Manager (client or API) is installed.

For a description and use of configuration files, see Understanding configuration and options files and the Tivoli Storage Manager Backup-Archive Client Installation and User’s Guide for your operating system.

char *options (I)

Points to a character string that can contain user options such as:

Compressalways
Servername (UNIX and Linux only)
TCPServeraddr (non-UNIX)
Fromnode
Fromowner

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

The format of the options is:

Each option that is specified in the option list begins with a dash (-) and is followed by the option keyword.
The keyword is followed by an equal sign (=) and then the option parameter.
If the option parameter contains a blank space, enclose the parameter with single or double quotes.
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. You can find descriptions and use of each option in the Tivoli Storage Manager Backup-Archive Client Installation and User’s Guide for your operating system.

dirDelimiter

The directory delimiter that is prefixed on the file space, high-level or low-level names. You need to specify this only if the application overrides the system defaults. In a UNIX or Linux environment, this is /. In a Windows environment, this is\.

useUnicode

A Boolean flag that indicates if Unicode is enabled.

bCrossPlatform

A Boolean flag that indicates if cross-platform is enabled.

UseTsmBuffers

Indicates whether to use buffer copy elimination.

numTsmBuffers

Number of buffers when useTsmBuffers = bTrue.

bEncryptKeyEnabled

Indicates whether encryption with application-managed key is used.

encryptionPasswordP

The encryption password.

Note: When using encryptkey=save, if an encrypt key already exists, the value specified in the encryptionPasswordP is ignored.

dsmAppVersion *appVersionP (I)

This parameter is a pointer to the data structure that identifies the version information of the application that is starting an API session. The structure contains the values of the four constants, applicationVersion, applicationRelease, applicationLevel, and applicationSubLevel, which are set in the tsmapitd.h file.

dsmInitExOut_t *dsmInitExOut P

This structure contains the output parameters.

dsUint32_t *dsmHandle (0): The handle that identifies this initialization session and associates it with subsequent API calls.
infoRC: Additional information about the return code. Check both the function return code and infoRC. If infoRC is DSM_RC_REJECT_LASTSESS_CANCELED (69), the Tivoli Storage Manager administrator cancelled the last session. The application should decide if it will cancel this session attempt by calling dsmTerminate immediately.

Return codes

The return code numbers are provided in parentheses ( ).

Table 1. Return codes for dsmInitEx
Return code	Explanation
DSM_RC_ABORT_SYSTEM_ERROR (1)	The Tivoli Storage Manager server has detected a system error and has notified the clients.
DSM_RC_REJECT_VERIFIER_EXPIRED (52)	Password has expired and must be updated. The next call must be dsmChangePW with the handle returned on this call.
DSM_RC_REJECT_ID_UNKNOWN (53)	Could not find the node name.
DSM_RC_TA_COMM_DOWN (103)	The communications link is down.
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 found.
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 (2013)	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)	Application client's API version has a higher value than the Tivoli Storage Manager version.
DSM_RC_PASSWD_TOOLONG (2103)	The specified password is too long.
DSM_RC_NO_OPT_FILE (2220)	No configuration file could be found.
DSM_RC_INVALID_KEYWORD (2221)	A keyword specified in an options string is invalid.
DSM_RC_PATTERN_TOO_COMPLEX (2222)	Include-exclude pattern too complex to be interpreted by Tivoli Storage Manager.
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 the host.
DSM_RC_MACHINE_SAME (2227)	The nodename 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 or the include-exclude file was not found.

Feedback