Two application-specific APIs or two different implementations of the same service require work areas, called workspaces, to maintain private and public (service-generated) objects. The workspace is required because two implementations of the same service (or different services) can represent private objects differently. Each one has its own workspace. Using the functions provided by XOM API, such as om_get( ) and om_copy( ), objects can be copied and moved from one workspace to another.
Recall that private objects are returned by a service to a workspace in private implementation-specific format. Using the OM function calls described in OM Function Calls, the data can be extracted from the private object for further program processing.
Before a request to the directory can be made by an application program, a workspace must be created by using the appropriate XDS function. An application creates a workspace by performing the XDS API call ds_initialize( ). Once the workspace is obtained, subsequent XDS API calls, such as ds_read( ), return a pointer to a private object in the workspace. When program processing is completed, the workspace is destroyed by using the ds_shutdown( ) XDS API function. Implicit in ds_shutdown( ) is a call to the XOM API function om_delete( ) to delete each private object the workspace contains.
The programs in Sample Application Programs demonstrate how to initialize and shut down a workspace. The XDS functions ds_initialize( ) and ds_shutdown( ) are described in detail in XDS Programming.
The closures of one or more packages are associated with a workspace. A package can be associated with any number of workspaces. An application program must obtain a workspace that supports an OM class before it is able to create any instances of that OM class. For example, some of these operations in an application may require involvement with GDS security, ACLs, or the DUA cache. Therefore, in addition to the basic packages provided by the directory service APIs, the workspace would have to support the GDS package. The following code fragment demonstrates how an application initializes a workspace and negotiates the packages to be associated with that workspace:
/* Build up an array of object identifiers for the optional */
/* packages to be negotiated. */
DS_feature features[] = {
{ OM_STRING(OMP_O_DS_BASIC_DIR_CONTENTS_PKG), OM_TRUE },
{ OM_STRING(OMP_O_DSX_GDS_PKG), OM_TRUE },
{ 0 }
};
CHECK_DS_CALL((OM_object) !(workspace = ds_initialize()));
CHECK_DS_CALL(ds_version(bdcp_package, workspace));