This topic describes the main program. Three calls usually precede any use of XDS.
First, ds_initialize( ) is called to set up a workspace. A workspace is a memory area in which XDS can generate objects that will be used to pass information to the application. If the call is successful, it returns a handle that must be saved for the ds_shutdown( ) call. If the call is unsuccessful, it returns NULL, but this example does not check for errors.
xdsWorkspace = ds_initialize();
If GDS is being used as the global directory service, the service packages are specified next. Packages consist of groups of objects, together with the associated supporting interface functionality, designed to be used for some specific end. For example, to access the (X.500) Global Directory, specify DSX_GDS_PKG. This example uses the basic XDS service so DS_BASIC_DIR_CONTENTS_PKG is specified. The featureList parameter to ds_version( ) is an array, not an object, since packages are not being handled yet:
dsStatus = ds_version(featureList, xdsWorkspace);
Note that if you are not using GDS as your global directory service (in other words, if you are using XDS by itself), then you should not call ds_version( ).
From this point on, status is returned by XDS functions via a DS_status variable. DS_status is a handle to a private object, whose value is DS_SUCCESS (that is, NULL) if the call was successful. If something went wrong, the information in the (possibly complex) private error object has to be analyzed through calls to om_get( ), which is one of the general-purpose object management functions that belongs to XDS's companion interface XOM. Usage of om_get( ) is demonstrated later on in this program, but return status is not checked in this example.
The third necessary call is to ds_bind( ). This call brings up the directory service, which binds to a Directory System Agent (DSA), the GDS server, through a Directory User Agent (DUA), the GDS client. The DS_DEFAULT_SESSION parameter calls for a default session. The alternative is to build and fill out your own DS_C_SESSION object, specifying such things as DSA addresses, and pass that. The default is used in this example:
dsStatus = ds_bind(DS_DEFAULT_SESSION, xdsWorkspace, &session);