Name

ds_bind - Opens a session with the directory

Synopsis

#include <xom.h>
#include <xds.h> DS_status ds_bind(
OM_object session,
OM_workspace workspace,
OM_private_object ∗bound_session_return);

Parameters

Input

session(Object(DS_C_SESSION)).  Specifies a particular directory service provider, together with other details of the service required.  This parameter can be either a public object or a private object.  The DS_DEFAULT_SESSION constant can also be used as the value of this parameter, causing a new session to be created with default values for all its OM attributes. 

workspaceSpecifies the workspace obtained from a call to ds_initialize() that is to be associated with the session.  All function results from directory operations using this session will be returned as private objects in this workspace.  If the session parameter is a private object, it must be a private object in this workspace. 

Output

bound_session_return
(Object(DS_C_SESSION)).  Upon successful completion, this parameter contains an instance of a directory session that can be used as a parameter to other functions (for example, ds_read()).  This is a new private object if the value of the session parameter was DS_DEFAULT_SESSION or a public object; otherwise, it is that value supplied as a parameter.  The function supplies default values for any of the OM attributes that are not present in the session parameter instance supplied as a parameter.  It also sets the value of the DS_FILE_DESCRIPTOR OM attribute to DS_NO_VALID_FILE_DESCRIPTOR, since the functionality is not supported. 

Description

The ds_bind() function sets up a communications link to the DSA. 

Notes

Although the user ideally is not aware whether naming operations are being handled by GDS or CDS, there are some situations where naming results can differ between the two  services.  (See the xds_intro(3xds) reference page for XDS functions at the start of this chapter for general differences between operations on GDS and CDS.) 

Note that in order to use CDS when GDS is not active, ds_bind() must be called with the value of the session parameter set to DS_DEFAULT_SESSION. 

Return Values

DS_statusDS_SUCCESS is returned if the function is completed successfully; otherwise, it indicates the error that has occurred. 

Errors

The following describes a partial list of errors that might be returned.  Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages. 

This function can return a DS_C_SYSTEM_ERROR or one of the following DS_C_LIBRARY_ERROR errors:

       •DS_E_BAD_SESSION

       •DS_E_BAD_WORKSPACE

       •DS_E_MISCELLANEOUS

       •DS_E_NOT_SUPPORTED

       •DS_E_TOO_MANY_SESSIONS

The function can return the following directory errors:

       •DS_C_SECURITY_ERROR

       •DS_C_SERVICE_ERROR

This function can return a DS_C_COMMUNICATIONS_ERROR, as well as the error constant DS_NO_WORKSPACE. 

Related Information

Functions: ds_unbind(3xds).