OM_private_object bound_session, context, name; { DS_status status; OM_private_object entry; status = ds_add_entry(bound_session, DS_DEFAULT_CONTEXT, name, entry, NULL); if (status == DS_SUCCESS) { printf("ADD ENTRY was successful\n"); } else { printf("ADD ENTRY failed\n"); } }

The above example shows how to perform a synchronous Add Entry operation. Note that the Invoke_id argument is not needed and is therefore set to NULL. The example assumes that all other arguments have been defined as shown in Example 1.

Opens a session with the directory service.

Syntax

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

C Binding

DS_status ds_bind(session, workspace, bound_session_return)

DS_status dsbind (
OM_object session
OM_workspace workspace
OM_private_object bound_session_return)

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 (or on a DEC OSF/1 system linked against the archive libraries libdxd.a and libdxdcds.a), 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 Values

Possible return values are as follows:

Return	Description
DS_SUCCESS	The operation completed successfully.
DS_NO_WORKSPACE	A workspace has not been set up by a call to the Initialize function.

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

Examples

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

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 successful\n"); } else { printf("BIND failed\n"); } }

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.

Compares an attribute value with the attribute value stored in the Directory for a particular entry.

Syntax

Status = ds_compare(Session, Context, Name, AVA, Result, Invoke-ID)

C Binding

DS_status ds_compare (session, context, name, ava, result_return, invoke_id_return)

Arguments

Session

The Session OM private object that was returned by the Bind function, identifying the directory session to be used.

Context

The Context parameters to be used for this operation. The Size-Limit Context parameter does not apply to this operation. This argument must be a Context OM private object or the constant Default-Context.

Name

A Name OM object containing the name of the target entry. Any aliases in the name will be dereferenced unless prohibited by the Context parameter Dont-Dereference-Aliases.

AVA

An AVA OM object containing the attribute-value-assertion that specifies the attribute type and value to be compared with that in the entry.

Result

A Compare-Result OM private object containing flags indicating whether the values matched and whether the comparison was made against the original entry. It also contains the Distinguished Name of the target object if an alias was dereferenced.

Invoke-ID

The Invoke-ID of an asynchronous directory operation. This is valid only if the Asynchronous OM attribute in the Context parameter is set to True.

Description

This function checks that the value supplied in the given AVA is the same as the value or values of the same attribute type in the named entry. The operation fails and an error is returned if the target object is not found or if the target entry does not have the required attribute type.

If this function is called asynchronously, then the result can be abandoned by calling the Abandon function.

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 the following issues for the Compare function:

• All CDS operations are synchronous. If a CDS operation is attempted and the Context parameter Asynchronous has been set true, a Library-Error, not-supported, is returned.
• When a CDS name is passed to XDS and DCE is not installed, a Library-Error, \fInot-supported\fP, is returned. This error is also returned when an X.500 name is passed to XDS and X.500 is not installed.
• In CDS, the naming attribute of an object is not stored in the attribute list of an object. Thus, in CDS a Compare operation of the purported naming attribute value with the naming attribute value of the directory object always fails to match.
• CDS supports only the following X.500 attribute syntaxes:
  • OM_S_TELETEX_STRING
  • OM_S_OBJECT_IDENTIFIER_STRING
  • OM_S_OCTET_STRING
  • OM_S_PRINTABLE_STRING
  • OM_S_NUMERIC_STRING
  • OM_S_BOOLEAN
  • OM_S_INTEGER
  • OM_S_UTC_TIME_STRING
  • OM_S_ENCODING_STRING
  
  If attributes of any other syntax are supplied to a Compare operation that references CDS, then it returns the Attribute-Error constraint-violation.
• In CDS, the name parameter supplied to the Compare function must ultimately resolve to the name of a leaf (that is, a CDS Object) entry; otherwise, the Name-Error no-such-object is returned. The function never interprets the name parameter as the name of a CDS Directory entry.

Return Values

Possible return values are as follows:

Return	Description
DS_SUCCESS	The comparison was completed, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously.
DS_NO_WORKSPACE	A workspace has not been set up by a call to the Initialize function.

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:

• Library-Error, with Problem attribute values of bad-argument, bad-context, bad-name, bad-session, miscellaneous, missing-type, not-supported, or too-many-operations
• Attribute-Error, constraint-violation
• Name-Error, no-such-object
• Referral
• Security-Error
• Service-Error
• Communications-Error

Examples

The following code extracts show an example call to the Compare function. The Compare function is used to compare the common name attribute with the name attribute contained within the directory entry identified by the Name argument.

There are two examples. The first example shows how to perform an asynchronous Compare operation. The second example shows how to perform a synchronous Compare operation.

The Bound_Session argument contains the identity of a session returned from an earlier call to the Bind function. This object identifies the session through which the request should be issued. The Name argument is assumed to have been previously defined. Examples of how to define a Name argument, including an example of a CDS Name argument, are shown in the Read function.

OM_private_object ava; OM_workspace workspace; OM_descriptor cpub_ava[4]; DS_status status; OM_sint invoke_id; OM_uint completion_flag; DS_status operation_status; OM_return_code om_status; OM_private_object name, compare_result; OM_return_code om_status = OM_SUCCESS; OMX_CLASS_DESC( cpub_ava[0], DS_C_AVA); OMX_ATTR_TYPE_DESC( cpub_ava[1], DS_ATTRIBUTE_TYPE, DS_A_COMMON_NAME); OMX_ZSTRING_DESC( cpub_ava[2], OM_S_PRINTABLE_STRING, DS_ATTRIBUTE_VALUES, "Albert Einstein"); OMX_OM_NULL_DESC( cpub_ava[3]); /* create the OM private object: ava */ om_status = om_create(DS_C_AVA, OM_FALSE, workspace, &ava); /* Copy the attribute list from the cpub_ava public object */ /* into the ava private object */ om_status = om_put(ava, OM_REPLACE_ALL, cpub_ava, 0,0,0); /* call the ds_compare function using ava as a parameter */ status = ds_compare(bound_session, context, name, ava, &compare_result, &invoke_id); if (status == DS_SUCCESS) { printf("COMPARE request was successful\n"); } else { printf("COMPARE request failed\n"); } /* now wait for the response... */ completion_flag = DS_OUTSTANDING_OPERATIONS; /* loop around calls to receive_result() until we get one back */ while ( (status == DS_SUCCESS) && ( completion_flag == DS_OUTSTANDING_OPERATIONS) ) { status = ds_receive_result(bound_session, &completion_flag, &operation_status, &compare_result, &invoke_id); if (status == DS_SUCCESS) { switch (completion_flag) { case DS_COMPLETED_OPERATION: /* we have a completed operation */ /* now see what we have got back ... */ if(operation_status == DS_SUCCESS) { printf("COMPARE result received\n"); /* use OM to examine compare_result object */ ... } else { printf("COMPARE request failed\n"); } break; case DS_OUTSTANDING_OPERATIONS: ... break; case DS_NO_OUTSTANDING_OPERATION: ... break; } } }

The above example shows:

• How to define an attribute value assertion and use that in the Compare function.
• How to define an AVA OM public object (cpub_ava) containing the attribute value assertion.
• How to use the OM Create function to create an AVA OM private object (ava) and how to use the OM Put function to copy the attribute value assertion from the public object (cpub_ava) into the newly created private object (ava).
• How to use the Receive Result function to obtain the result of the Compare function.
  The OM Create and the OM Put functions are assumed to succeed.

  OM_private_object bound_session, name, context; { DS_status status; OM_private_object ava; status = ds_compare(bound_session, DS_DEFAULT_CONTEXT, name, ava, &compare_result, NULL); if (status == DS_SUCCESS) { printf("COMPARE request was successful\n"); /* examine compare result object to see if */ /* comparison was TRUE or FALSE */ } else { printf("COMPARE request failed\n"); } }

  
  The above example shows how to perform a synchronous Compare operation. Note that the Invoke-ID argument is not needed and is therefore set to NULL. The example assumes that all other arguments have been defined as shown in Example 1.

Initializes the interface.

Syntax

Workspace = ds_initialize(void )

C Binding

OM_workspace ds_initialize(void)

OM_workspace workspace)

Description

This function performs any necessary initialization of the X.500 API including the creation of a workspace. You must call this function before you call any other X.500 API functions. It may be called multiple times, in which case each call returns a workspace that is distinct from other workspaces created by the Initialize function but not yet deleted by the Shutdown function.

Return Values

Possible return values are as follows:

Upon successful completion this function returns a pointer to a workspace in which OM objects can be created and manipulated. Only objects created in this workspace can be used as arguments to the other directory interface functions. This function returns NULL if it fails.

Errors

None.

Examples

The following code extract shows an example of a call to the Initialize function. The Initialize function is used to initialize the X.500 API and create a workspace which can then be used by other functions.

OM_workspace workspace; { if ((workspace = ds_initialize()) != NULL) { printf("INITIALIZE was successful\n"); } else { printf("INITIALIZE failed\n"); } }

The Initialize function establishes the workspace that you can then use to communicate with the directory, for the remainder of the session.

Lists all the immediate subordinate entries of a directory entry.

Syntax

Status = ds_list(Session, Context, Name, Result, Invoke-ID)

C Binding

DS_status ds_list(session, context, name, result_return, invoke_id_return)

DS_status ds_list (
OM_private_object session
OM_private_object context
OM_object name
OM_private_object result_return
OM_sint invoke_id_return)

Arguments

Session

The Session OM private object that was returned by the Bind function, identifying the directory session to be used.

Context

The directory context to be used for this operation. This argument must be a Context OM private object or the constant Default-Context.

Name

A Name OM object specifying the name of the object entry whose immediate subordinates are to be listed. Any aliases in the name will be dereferenced unless prohibited by the Context parameter Dont-Dereference-Aliases.

Result

A List-Result OM private object, passed by reference, containing some information about the target object's immediate subordinates. It also contains the distinguished name of the target object if an alias was dereferenced to find it. Aliases in the subordinate names are identified, but not dereferenced. Additionally, there may be a partial outcome qualifier which indicates that the result is incomplete. It also explains the reason why, for example, the time limit expired, and contains information that may be helpful when attempting to complete the operation.

Invoke-ID

The Invoke-ID of an asynchronous directory operation.

Description

This function is used to obtain a list of all the immediate subordinates of a named entry. It is possible that the list will be incomplete in some circumstances.

If this function is called asynchronously, then the result can be abandoned by calling the Abandon function.

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 the following issues for the List function:

• All CDS operations are synchronous. If a CDS operation is attempted and the Context parameter Asynchronous has been set true, a Library-Error, not-supported, is returned. This error is also returned when an X.500 name is passed to XDS and X.500 is not installed.

Return Values

Possible return values are as follows:

Return	Description
DS_SUCCESS	The target object was located regardless of whether it has any subordinates, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously.
DS_NO_WORKSPACE	A workspace has not been set up by a call to the Initialize function.

If neither of these constants are 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:

• Library-Error, with Problem attribute values of bad-argument, bad-context, bad-name, bad-session, miscellaneous, missing-type, not-supported, or too-many-operations
• Name-Error
• Referral
• Security-Error
• Service-Error
• Communications-Error

Examples

The following code extracts show an example call to the List function. The List function is used to list the subordinates of the directory entry identified in the Name argument.

There are two examples. The first example shows how to perform an asynchronous List operation. The second example shows how to perform a synchronous List operation.

The Bound_Session argument contains the identity of a session, established using the Bind function, through which the request should be issued. The Name argument is assumed to have been previously defined. Examples of how to define a Name argument, including an example of a CDS Name argument, are shown in the Read function.

OM_private_object bound_session, context, name; OM_workspace workspace; { DS_status status; OM_private_object list_result; OM_sint invoke_id; OM_uint completion_flag; DS_status operation_status; OM_return_code om_status; OM_public_object spub_result; OM_value_position desc_count; /* call ds_list to list the subordinates of the entry */ /* identified in name */ status = ds_list(bound_session, context, name, &list_result, &invoke_id); completion_flag = DS_OUTSTANDING_OPERATIONS; /* loop around calls to receive_result() until we get one back */ while ((status == DS_SUCCESS) && (completion_flag == DS_OUTSTANDING_OPERATIONS)) { status = ds_receive_result(bound_session, &completion_flag, &operation_status, &list_result, &invoke_id); if (status == DS_SUCCESS) { switch (completion_flag) { case DS_COMPLETED_OPERATION: /* we have a completed operation */ /* now see what we have got back ... */ if (operation_status == DS_SUCCESS) { om_status = om_get(list_result, OM_NO_EXCLUSIONS, 0, 0, 0, OM_ALL_VALUES, &spub_result, &desc_count); if (om_status == OM_SUCCESS) { /* if desc_count is not zero, the results are now */ /* available in the public object spub_result */ } else { /* error getting results */ } } else {...} break; case DS_COMPLETED_OPERATION: ... break; case DS_COMPLETED_OPERATION: ... break; } } }

---

Previous

Next

Contents

Index