Name

ds_compare - Compares an attribute value with the attribute value stored in the directory for a particular entry

Synopsis

#include <xom.h>
#include <xds.h> DS_status ds_compare(
OM_private_object session,
OM_private_object context,
OM_object name,
OM_object ava,
OM_private_object ∗result_return,
OM_sint ∗invoke_id_return);

Parameters

Input

session(Object(DS_C_SESSION)).  The directory session against which this operation is performed.  This must be a private object. 

context(Object(DS_C_CONTEXT)).  The directory context to be used for this operation.  Note that DS_SIZE_LIMIT does not apply to this operation.  This parameter must be a private object or the DS_DEFAULT_CONTEXT constant. 

name(Object(DS_C_NAME)).  The name of the target object entry.  Any aliases in the name are dereferenced unless prohibited by the DS_DONT_DEREFERENCE_ALIASES service control attribute of the DS_C_CONTEXT object. 

ava(Object(DS_C_AVA)).  The attribute value assertion that specifies the attribute type and value to be compared with those in the entry. 

Output

result_return(Object(DS_C_COMPARE_RESULT)).  Upon successful completion, the result contains flags indicating whether the values matched and whether the comparison was made against the original entry.  It also contains the DN of the target object if an alias is dereferenced. 

invoke-ID_return
(Integer).  Not supported.

Description

The ds_compare() function compares the value supplied in the given ava parameter with the value or values of the same attribute type in the named entry. 

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 for the general differences between operations on GDS and CDS.) 

Note the following issues for the ds_compare() operation:

       •In CDS, the naming attribute of an object is not stored in the attribute list of an object.  Thus in CDS, a ds_compare() of the purported naming attribute value with the naming attribute value of the directory object always fails to match. 

       •GDS-structured types are not supported by CDS. If a GDS-structured attribute type is used as a parameter to ds_compare() on a CDS object, then it returns with the error DS_C_ATTRIBUTE_ERROR (DS_­E_­CONSTRAINT_­VIOLATION). 

       •In CDS, ds_compare() can only be used on leaf objects; otherwise, a DS_C_NAME_ERROR (DS_E_NO_SUCH_OBJECT) is returned. 

       •In CDS, if the name parameter is a CDS soft link and the Dont_Dereference_Aliases context parameter is set to TRUE, the only allowed attribute for comparison is the DS_A_ALIASED_OBJECT_NAME attribute.  This attribute is compared with the Distinguished Name of the soft link target. 

Return Values

DS_statusIndicates whether the comparison is completed or not.  If successful, DS_SUCCESS is returned.  Note that the operation fails and an error is returned either if the target object is not found or if it does not have an attribute of the required type. 

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_ARGUMENT

       •DS_E_BAD_CONTEXT

       •DS_E_BAD_NAME

       •DS_E_BAD_SESSION

       •DS_E_MISCELLANEOUS

       •DS_E_MISSING_TYPE

       •DS_E_TOO_MANY_OPERATIONS

The following directory errors can be returned:

       •DS_C_ATTRIBUTE_ERROR

       •DS_C_NAME_ERROR

       •DS_C_REFERRAL

       •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.