Every application program must first call ds_initialize( ) to establish a workspace where objects returned by the directory service are deposited. The ds_initialize( ) function must be called before any other directory interface functions are called.
The ds_initialize( ) call returns a handle (or pointer) to a workspace. The application program performs operations on OM objects in this workspace. OM objects created in this workspace can be used as input parameters to the other directory interface functions. In addition, objects returned by the directory service are deposited in the workspace.
Within the following code fragment from example.c, a workspace is initialized. (The declaration of the variable workspace and the call to ds_initialize( ) are found in different topics of the program.)
int main(void)
{
DS_status error; /* return value from DS functions */
OM_return_code return_code;/* return value from OM functions */
OM_workspace workspace; /* workspace for objects */
OM_private_object session; /* session for directory operations */
OM_private_object result; /* result of read operation */
OM_sint invoke_id; /* Invoke-ID of the read operation */
OM_value_position total_num; /* Number of Attribute Descriptors */
/*
* Perform the Directory operations:
* (1) Initialize the directory service and get an OM workspace.
* (2) bind a default directory session.
* (3) read the telephone number of "name".
* (4) terminate the directory session.
*/
CHECK_DS_CALL((OM_object) !(workspace=ds_initialize()));
OM_workspace is a type definition in the xom.h header file defined as a pointer to void. A void pointer is a generic pointer that may point to any data type. The variable workspace is declared as data type OM_workspace. The return value is assigned to the variable workspace and the CHECK_DS_CALL macro determines if the call is successful. CHECK_DS_CALL is an error handling macro that is defined in example.h.
The ds_initialize( ) call returns a handle to a workspace in which OM objects can be created and manipulated. Only objects created in this workspace can be used as parameters to other directory interface functions. The ds_initialize( ) call returns NULL if it fails.