BSAInit
Initialize the environment and set up a session.
SYNOPSIS
#include <xbsa.h>
int BSAInit(BSA_Handle *bsaHandlePtr, BSA_SecurityToken *tokenPtr, BSA_ObjectOwner *objectOwnerPtr,
char **environmentPtr)
DESCRIPTION
The BSAInit() call authenticates the XBSA application, sets up a session with the NetBackup XBSA interface and an environment for subsequent API calls for the caller. Nested sessions are not supported.
PARAMETERS
BSA_Handle *bsaHandlePtr (O) | This parameter is used to return the handle that identifies this session and must be used for subsequent API calls using this session. |
BSA_SecurityToken *tokenPtr (I) | For NetBackup XBSA Version 1.1.0, this parameter is ignored. Client authentication is part of NetBackup functionality and is performed between the NetBackup XBSA interface and the NetBackup server. |
BSA_ObjectOwner *objectOwnerPtr (I) | This parameter is a pointer to a structure used to specify both the bsa_ObjectOwner and the app_ObjectOwner. For NetBackup XBSA Version 1.1.0, the NetBackup XBSA interface and NetBackup determine object ownership. If the bsa_ObjectOwner field is specified, it is ignored. The app_ObjectOwner is optional and can be the empty string. The BSA_ObjectOwner established when the session is created is used in subsequent authorization checking. |
char **environmentPtr (I) | This parameter is a pointer to a structure that contains the new NetBackup XBSA environment variables (keyword, value) pairs, for the session. The new NetBackup XBSA environment consists of a pointer to an array of strings. Each string consists of a keyword followed by an '=' and followed by a null-terminated value. No spaces are allowed around the '='. A NULL pointer terminates the array of pointers. |
EXTENDED DESCRIPTION
See Environment variable definitions.
Variables defined by the XBSA application but not interpreted by the NetBackup XBSA interface are silently ignored and not added to the NetBackup XBSA environment. Variables required by the NetBackup XBSA interface and not specified by the application can result in a BSA_RC_INVALID_ENV error during a BSAInit() call. The BSAGetEnvironment() call only returns the NetBackup XBSA environment variables that are meaningful to the NetBackup XBSA interface. This allows the XBSA application to discover which variables specified in the call to BSAInit() the NetBackup XBSA interface interpreted.
When an XBSA application connects to a NetBackup XBSA interface, it can make an initial call to BSAQueryApiVersion() to determine the highest version of the specification supported. If the application supports that version, it should specify it when calling BSAInit(). If the application does not support that version, or did not call BSAQueryApiVersion(), the XBSA application should specify the version it requires. If a "version not supported" error is encountered, and the XBSA application supports other versions, the XBSA application may retry the call to BSAInit() specifying a different version.
BSAInit() can also determine the verbose level and open the log file if the log directory exists. Thus the XBSA application can start logging after BSAInit().
If BSA_SERVICE_HOST and NBBSA_FEATURE_ID are specified in the list of XBSA environment variables, the feature is checked for a valid license key. If a valid license is not found, the transaction returns a NBBSA_RC_FEATURE_NOT_LICENSED error and does not open the session.
RETURN VALUE
The following return codes are returned by this function:
BSA_RC_ABORT_SYSTEM_ERROR | System detected error, operation aborted. |
BSA_RC_AUTHENTICATION_FAILURE | There was an authentication failure. |
BSA_RC_INVALID_CALL_SEQUENCE | The sequence of API calls is incorrect. Nested sessions are not supported. |
BSA_RC_INVALID_ENV | An entry in the environment structure is invalid or missing. |
BSA_RC_NULL_ARGUMENT | A NULL pointer was encountered in one of the arguments. |
NBBSA_RC_FEATURE_NOT_LICENSED | The license for the requested feature is not available. |
BSA_RC_SUCCESS | The function succeeded. |
BSA_RC_VERSION_NOT_SUPPORTED | The NetBackup XBSA interface does not support the specified version of the interface. |