dsmInitEx

Edit online

The dsmInitEx function call starts an API session by using the additional parameters for 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 IBM® Storage Protect 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. Call dsmQueryApiVersionEx and verify that the API version of the application client and the version of the API library that is installed on the user's workstation is compatible.
char *clientNodeNameP (I)
This parameter is a pointer to the node for the IBM Storage Protect session. All sessions must be associated with a node name. The DSM_MAX_NODE_LENGTH constant in the dsmapitd.h file sets the maximum size 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 DSM_RC_REJECT_ID_UNKNOWN.

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 is a multi-user platform, an owner name of NULL (the root user) has the authority to back up, archive, restore, or retrieve any objects that belong 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 platform, 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 IBM Storage Protect 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 parameter, if a value is supplied.
char *applicationType (I)
Identifies the application that is running the IBM Storage Protect 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. The value is entered in the platform field on the server. Consider using an operating system ID in the value. The maximum string length is defined in the DSM_MAX_PLATFORM_LENGTH constant.

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 that are 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 and Linux systems only)
  • TCPServeraddr (not for UNIX systems)
  • Fromnode
  • Fromowner
  • Passwordaccess

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

Options have the following format:

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

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

dirDelimiter
The directory delimiter that is prefixed on the file space, high-level or low-level names. You must specify the dirDelimiter parameter only if the application overrides the system defaults. In a UNIX or Linux environment, the default is forward slash (/). In a Windows environment, the default is backslash (\).
useUnicode
A Boolean flag that indicates whether Unicode is enabled. The useUnicode flag must be false to achieve cross-platform interoperability between UNIX and Windows systems.
bCrossPlatform
A Boolean flag that must be set (bTrue) to achieve cross-platform interoperability between UNIX and Windows systems. When the bCrossPlatform flag is set, the API ensures that the file spaces are not Unicode and that the application does not use Unicode. A Windows application that uses Unicode is not compatible with applications that use non-Unicode encodings. The bCrossPlatform flag must not be set for a Windows application that uses Unicode.
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.
Restriction: When encryptkey=save, if an encrypt key exists, the value that is 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 the value of infoRC. An infoRC value of DSM_RC_REJECT_LASTSESS_CANCELED (69), the IBM Storage Protect indicates that the administrator canceled the last session.

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 IBM Storage Protect server detected a system error and notified the clients.
DSM_RC_REJECT_VERIFIER_EXPIRED (52) Password expired and must be updated. The next call must be dsmChangePW with the handle returned on this call.
DSM_RC_REJECT_ID_UNKNOWN (53) Cannot 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 (...), but was not found.
DSM_RC_NO_PASS_FILE (168) The password file is not available.
DSM_RC_UNMATCHED_QUOTE (177) An unmatched quotation mark 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 IBM Storage Protect version.
DSM_RC_PASSWD_TOOLONG (2103) The specified password is too long.
DSM_RC_NO_OPT_FILE (2220) No configuration file is found.
DSM_RC_INVALID_KEYWORD (2221) A keyword that is specified in an options string is invalid.
DSM_RC_PATTERN_TOO_COMPLEX (2222) Include-exclude pattern too complex to be interpreted by IBM Storage Protect.
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 node name 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 or the include-exclude file was not found.