bstr_initialize(3) — Subroutines

Name

bstr_initialize − Enables access to BASEstar Open services and sets up the BASEstar Open environment.

Syntax

bstr_t_status bstr_initialize (
bstr_t_string realm,
bstr_t_sequence ∗environment_info);

Description

The calling application process invokes the bstr_initialize procedure to indicate its intention to use the BASEstar Open services through the API. During its execution, an application process can invoke the bstr_initialize procedure only once.

The bstr_initialize procedure sets the following environment conditions:

•Operations are performed on the VODB

•The context search path is set to the realm root slash (/).

The bstr_initialize procedure returns a sequence containing the names and values of some Application Management Services BASEstar Open global variables. For further information about BASEstar Open global variables, refer to your management guide.

The optional argument realm indicates the Realm in which the application will execute.

Arguments

realm
access: read
This optional argument specifies the name of the Realm in which the application will execute. If this argument is set to NULL, then the name of the Realm that was specified in the BSTR_REALM global variable is assumed. If instead, you specify a value for the realm argument, that value overrides the value of the BSTR_REALM global variable.

environment_info
access: write
The address of a sequence. Each element in the sequence contains the name and the value of a BASEstar Open global variable. The most significant fields of each element in the sequence are as follows:

•type. Set to BSTR_C_VALUE.

•name. The address of a string which contains the name of a global variable.

•size. Contains the size of the value buffer (maximum length is BSTR_C_BUFFER_LEN).

•value. The address of a bstr_t_string buffer where the global variable value is kept.

The following table lists all the global variables whose values are returned in the environment_info sequence.

Variable Name	C Language Constant
BSTR_DATABASE	BSTR_C_ENV_DATABASE
BSTR_DBACCESS_KEY	BSTR_C_ENV_DBACCESS_KEY
BSTR_DBVERSION	BSTR_C_ENV_DBVERSION
BSTR_PROGRAM	BSTR_C_ENV_PROGRAM
BSTR_REALM	BSTR_C_ENV_REALM
BSTR_WORK_ROOT	BSTR_C_ENV_WORK_ROOT

For further information, refer to the management guide for your platform.

Return Values

BSTR_S_ALREADY_INITIALIZED	BASEstar Open already initialized
BSTR_S_BAD_PARAMETER	Bad parameter value

BSTR_S_COM_PC_NO_WATCHDOG	Watchdog not yet connected
BSTR_S_COM_PC_VERSION_MISMATCH	Protocol version mismatch
BSTR_S_COM_PC_WD_PTABLE_FULL	Watchdog’s process table is full
BSTR_S_COM_PC_REALM_PTABLE_FULL	Watchdog’s Realm table is full
BSTR_S_COM_PC_DUPLICATED_TASK	Duplicated process in watchdog
BSTR_S_COM_PC_CANNOT_CONNECT	Process cannot connect to Communication Server
BSTR_S_COM_PC_SIZE_MISMATCH	Number of bytes requested does not match the number of bytes returned
BSTR_S_NORMAL	Normal successful completion
BSTR_S_NO_MEMORY	Insufficient virtual memory
BSTR_S_NO_REALM	Realm must be set
BSTR_S_REALM_NOT_STARTED	Realm must be started
BSTR_S_SEQUENCE_IN_USE	Sequence already in use