ds_compare(3xds) — Subroutines
(c) Digital Equipment Corporation. 1994. All rights reserved.
Name
ds_compare − 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)
Argument@Data Type@Access
Session@OM_private_object@T{ read T} Context@OM_private_object@T{ read T} Name@OM_object@T{ read T} AVA@OM_object@T{ read T} Result@OM_private_object@T{ write T} Invoke-ID@Integer@T{ write T} Status@T{ DS_status T}
C Binding
DS_status ds_compare(session, context, name, ava, result_return, invoke_id_return)
OM_private_object@T{ session T} OM_private_object@T{ context T} OM_object@T{ name T} OM_object@T{ ava T} OM_private_object@T{ ∗result_return T} OM_sint@T{ ∗invoke_id_return T}
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 only valid 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, not-supported, 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 Value
The comparison was completed, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously. 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 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
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.
Exhibit 0-0.
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 successful0);
}
else
{
printf("COMPARE request failed0);
}
/∗ 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 received0);
/∗ use OM to examine compare_result object ∗/
...
}
else
{
printf("COMPARE request failed0);
}
break;
case DS_OUTSTANDING_OPERATIONS:
...
break;
case DS_NO_OUTSTANDING_OPERATION:
...
break;
}
}
}
Example 1 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.
Exhibit 0-0.
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 successful0);
/∗ examine compare result object to see if ∗/
/∗ comparison was TRUE or FALSE ∗/
}
else
{
printf("COMPARE request failed0);
}
}
Example 1 shows how to perform a synchronous Compare operation. Note that the Invoke-ID argument is not needed and therefore set to NULL. The example assumes that all other arguments have been defined as shown in Example 1.