ds_bind(3xds) — Subroutines

Name

ds_bind − Opens a session with the directory service.

Syntax

Status = ds_bind(Session, Workspace, Bound-Session)

Session@OM_object@T{ read T} Workspace@OM_workspace@T{ read T} Bound-Session@OM_private_object@T{ write T} Status@T{ DS_status T}

C Binding

DS_status ds_bind (session, workspace, bound_session_return)

OM_object@T{ session T} OM_workspace@T{ workspace T} OM_private_object@T{ ∗bound_session_return T}

Arguments

Session

A Session OM object specifying the address of the DSA to bind to, and other information. You can submit either an OM public object or an OM private object as this argument. You can also use the constant Default-Session as the value of this argument, causing a new session to be created with default values for all its OM attributes. The Bind operation uses information from the DUA defaults file when the constant Default-Session is used.

Workspace

Specifies the workspace (obtained from a call to the Initialize function) which 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 argument is a private object, it must be a private object in this workspace.

Bound-Session

A Session OM private object identifying a directory session. This session may be used as an argument to other functions, for example the Read function. If the value of Session was Default-Session or a public object, then Bound-Session is a new private object. Otherwise, when the Session is a private object, then Bound-Session is that private object. The function supplies default values for any of the OM attributes that were not present in the session instance supplied as an argument. It also sets the value of the File-Descriptor OM Attribute. The initial value of this attribute is No-Valid-File-Descriptor. On an OpenVMS system, a file descriptor is not returned and the value of this attribute does not change. Note also that if the application binds only to a CDS directory, the value of the File-Descriptor OM attribute does not change.

Description

This function opens a session with the directory service and returns a session object for use in subsequent function calls. This function must be called before any other directory functions.

DCE Notes

Ideally, the user does not know whether X.500 or CDS is actually handling the DCE naming operations. There are, however, some situations where naming results will differ depending on which service is handling the operation. (The intro reference page for XDS functions describes the general differences between operations on X.500 and CDS.)

Note that to use CDS when X.500 is not active, the Bind function must be called with the value of the session parameter to set to DS_DEFAULT_SESSION. In this case, the Bind function will return DS_SUCCESS, but the returned Bound Session object may be used only for directory operations on the CDS namespace. If an operation is attempted against X.500 with this Bound Session, the directory routine will return the Library-Error, not-supported.

If your application was built and runs on a system where CDS is installed but X.500 is not installed, the Bind function will only attempt to bind to the CDS directory. If your application was built and runs on a system where X.500 is installed but CDS is not installed, the Bind function will only attempt to bind to the X.500 directory, and will return an error if it fails. If both CDS and X.500 are installed on the system and your application was built and runs against the XDS shareable library files,

then the Bind function will attempt to bind to both directories.

Note that in normal operation, no error message is returned if the Bind function fails to connect to an X.500 directory, but an error will be returned when your application attempts an X.500 operation. If you require error messages to be returned when the Bind function fails, your application must call the Version function and negotiate the Digital extension feature DSX-RET-X500-BIND-ERR-FTR.

Return Value

DS_SUCCESS@T{ The operation completed successfully. T} DS_NO_WORKSPACE@T{ A workspace has not been set up by a call to the Initialize function. T}

If neither of these constants is returned, then the function returns a pointer to an error object of one of the classes listed below.

Errors

This function can return pointers to the following error objects:

System-Error

Library-Error, with Problem attribute values of bad-session, miscellaneous, not-supported or too-many-sessions

Security-Error

Service-Error

Communications-Error

Example

The following code extract shows an example call to the Bind function. It establishes a session with the directory service.

Exhibit 0-0.

OM_private_object bound_session;

OM_workspace       workspace;

{

    DS_status         status;

    status = ds_bind(DS_DEFAULT_SESSION, workspace, &bound_session);

    if (status == DS_SUCCESS)
    {
     printf("BIND was successful0);
    }
    else
    {
    printf("BIND failed0);
    }
}

The Bind function associates a workspace, obtained from a call to the Initialize function, with the directory service session returned in the Bound_Session argument. The function uses the default session constant DS_DEFAULT_SESSION as the Session argument.

Museum