ds_read(3xds) — Subroutines
(c) Digital Equipment Corporation. 1994. All rights reserved.
Name
ds_read − Queries information in a particular entry.
Syntax
Status = ds_read(Session, Context, Name, Selection, 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} Selection@OM_object@T{ read T} Result@OM_object@T{ write T} Invoke-ID@Integer@T{ write T} Status@T{ DS_status T}
C Binding
DS_status ds_read (session, context, name, selection, 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{ selection 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 directory context 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.
Selection
An Entry-Information-Selection OM object or a constant specifying what information from the named entry is requested. Information about no attributes, all attributes, or just a named set can be chosen. Attribute types are always returned, but the attribute values need not be. The following constants can be used:
•Select-No-Attributes, to verify the existence of an entry
•Select_All-Types, to return just the types of all attributes
•Select-All-Types-And-Values, to return the types and values of all attributes
Result
A Read-Result OM object, passed by reference, containing the distinguished name of the target object and a flag indicating whether the result came from the original entry or a copy. It also contains any requested attribute types and values. Attribute information is only returned if access rights are sufficient. No object is returned if the call does not complete successfully.
Invoke-ID
The Invoke-ID of an asynchronous directory operation.
Description
This function is used to extract information from an explicitly named entry. It can also be used to verify a distinguished name.
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 Read 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.
•
Because CDS does not implement the X.500 schema rules, some CDS objects may not contain mandatory attributes such as object class and so on. In CDS, a read of an alias object fails if the DS_A_ALIASED_OBJECT_NAME does not exist. Instead, CDS returns with the Name-Error no-such-object.
•
In CDS, the naming attribute of an object is not stored in the attribute list for the object. Thus in CDS, the Read function does not return this attribute in the attribute list for an object.
Return Value
The read 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-attribute, bad-context, bad-name, bad-session, miscellaneous, missing-type, not-supported or too-many-operations
Attribute-Error
Name-Error, no-such-object
Referral
Security-Error
Service-Error
Communications-Error
An Attribute-Error, no-such-attribute, is reported if an explicit list of attributes is specified by the selection argument but none of them are present in the entry. This error is not reported if any of the selected attributes are present.
A Security-Error, insufficient-access-rights, is reported where access rights prohibit the reading of all requested attribute values.
Examples
The following code extracts show an example call to the Read function. The Read function is used to read all the types and values from all attributes of the directory entry identified in the Name argument.
There are three examples. The first example shows how to perform an asynchronous Read operation. The second example shows how to perform a synchronous Read operation. The third example shows how to perform a synchronous Read operation with a CDS name.
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 Context argument is assumed to have been previously defined. An example of how to define a Context argument is shown in the Add Entry function.
Exhibit 0-0.
{
OM_workspace workspace;
OM_descriptor cpub_dn[6];
OM_descriptor cpub_rdn1[3];
OM_descriptor cpub_rdn2[3];
OM_descriptor cpub_rdn3[3];
OM_descriptor cpub_rdn4[3];
OM_descriptor cpub_ava1[4];
OM_descriptor cpub_ava2[4];
OM_descriptor cpub_ava3[4];
OM_descriptor cpub_ava4[4];
OM_value_position desc_count;
DS_status status;
OM_sint invoke_id;
OM_uint completion_flag;
DS_status operation_status;
OM_return_code om_status;
OM_private_object name, read_result;
OM_public_object spub_result;
OMX_CLASS_DESC( cpub_ava1[0], DS_C_AVA);
OMX_ATTR_TYPE_DESC( cpub_ava1[1], DS_ATTRIBUTE_TYPE,
DS_A_COMMON_NAME);
OMX_ZSTRING_DESC( cpub_ava1[2], OM_S_PRINTABLE_STRING,
DS_ATTRIBUTE_VALUES,
"Albert Einstein");
OMX_OM_NULL_DESC( cpub_ava1[3]);
OMX_CLASS_DESC( cpub_ava2[0], DS_C_AVA);
OMX_ATTR_TYPE_DESC( cpub_ava2[1], DS_ATTRIBUTE_TYPE,
DS_A_ORG_UNIT_NAME);
OMX_ZSTRING_DESC( cpub_ava2[2], OM_S_PRINTABLE_STRING,
DS_ATTRIBUTE_VALUES,
"Research");
OMX_OM_NULL_DESC( cpub_ava2[3]);
OMX_CLASS_DESC( cpub_ava3[0], DS_C_AVA);
OMX_ATTR_TYPE_DESC( cpub_ava3[1], DS_ATTRIBUTE_TYPE,
DS_A_ORG_NAME);
OMX_ZSTRING_DESC( cpub_ava3[2], OM_S_PRINTABLE_STRING,
DS_ATTRIBUTE_VALUES,
"Digital Equipment Corporation");
OMX_OM_NULL_DESC( cpub_ava3[3]);
OMX_CLASS_DESC( cpub_ava4[0], DS_C_AVA);
OMX_ATTR_TYPE_DESC( cpub_ava4[1], DS_ATTRIBUTE_TYPE,
DS_A_COUNTRY_NAME);
OMX_ZSTRING_DESC( cpub_ava4[2], OM_S_PRINTABLE_STRING,
DS_ATTRIBUTE_VALUES,
"US");
OMX_OM_NULL_DESC( cpub_ava4[3]);
OMX_CLASS_DESC( cpub_rdn1[0], DS_C_DS_RDN);
OMX_OBJECT_DESC( cpub_rdn1[1], DS_AVAS, cpub_ava1);
OMX_OM_NULL_DESC( cpub_rdn1[2]);
OMX_CLASS_DESC( cpub_rdn2[0], DS_C_DS_RDN);
OMX_OBJECT_DESC( cpub_rdn2[1], DS_AVAS, cpub_ava2);
OMX_OM_NULL_DESC( cpub_rdn2[2]);
OMX_CLASS_DESC( cpub_rdn3[0], DS_C_DS_RDN);
OMX_OBJECT_DESC( cpub_rdn3[1], DS_AVAS, cpub_ava3);
OMX_OM_NULL_DESC( cpub_rdn3[2]);
OMX_CLASS_DESC( cpub_rdn4[0], DS_C_DS_RDN);
OMX_OBJECT_DESC( cpub_rdn4[1], DS_AVAS, cpub_ava4);
OMX_OM_NULL_DESC( cpub_rdn4[2]);
OMX_CLASS_DESC( cpub_dn[0], DS_C_DS_DN);
OMX_OBJECT_DESC( cpub_dn[1], DS_RDNS, cpub_rdn4);
OMX_OBJECT_DESC( cpub_dn[2], DS_RDNS, cpub_rdn3);
OMX_OBJECT_DESC( cpub_dn[3], DS_RDNS, cpub_rdn2);
OMX_OBJECT_DESC( cpub_dn[4], DS_RDNS, cpub_rdn1);
OMX_OM_NULL_DESC( cpub_dn[5]);
/∗ create the OM private object: name ∗/
om_status = om_create(DS_C_DS_DN, OM_FALSE, workspace, &name);
/∗ Copy the attribute list from the cpub_dn public object into ∗/
/∗ the name private object ∗/
om_status = om_put(name, OM_REPLACE_ALL, cpub_dn, 0,0,0);
/∗ call the ds_read function using Name as a parameter and ∗/
/∗ select only the information specified by rdn_type_list ∗/
status = ds_read(bound_session, context, name,
DS_SELECT_ALL_TYPES_AND_VALUES, &read_result,
&invoke_id);
if (status == DS_SUCCESS)
{
printf("READ request was successful0);
}
else
{
printf("READ 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, &read_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(read_result, OM_NO_EXCLUSIONS,
0, 0, 0, OM_ALL_VALUES,
&spub_result, &desc_count);
if (om_status == OM_SUCCESS)
{
/∗ check desc_count != 0 ∗/
/∗ results now available in public object ∗/
/∗ spub_result ∗/
}
else
{
/∗ error getting results ∗/
/∗ search_result not deleted ∗/
}
}
else
{...}
break;
case DS_OUTSTANDING_OPERATIONS:
...
break;
case DS_NO_OUTSTANDING_OPERATION:
...
break;
}
}
} }
Example 1 shows:
•How to define a private object containing a distinguished name.
•How to define a DS-DN OM public object (cpub_dn) containing the entry’s distinguished name: /C=US/O=Digital Equipment Corporation/OU=Research/CN=Albert Einstein
•How to use the OM Create function to create a DS-DN OM private object (name) and how to use the OM Put function to copy the distinguished name from the public object (cpub_dn) into the newly created private object (name).
•How to use the Receive Result function to obtain the result of the Read function.
•How to use the OM Get function to copy the attributes of the Read-Result OM private object into the Read-Result OM public object (Spub_Result) for examination.
The OM Create, OM Put and the OM Get functions are assumed to succeed.
Exhibit 0-0.
OM_private_object bound_session, name, context;
{
DS_status status;
OM_private_object name;
status = ds_read(bound_session, DS_DEFAULT_CONTEXT,
name, selection, &info, NULL);
if (status == DS_SUCCESS)
{
printf("READ was successful0);
}
else
{
printf("READ failed0);
}
}
Example 2 shows how to perform a synchronous Read 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.
Exhibit 0-0.
{
OM_workspace workspace;
OM_descriptor cpub_dn[7];
OM_descriptor cpub_rdn0[3];
OM_descriptor cpub_rdn1[3];
OM_descriptor cpub_rdn2[3];
OM_descriptor cpub_rdn3[3];
OM_descriptor cpub_rdn4[3];
OM_descriptor cpub_ava0[4];
OM_descriptor cpub_ava1[4];
OM_descriptor cpub_ava2[4];
OM_descriptor cpub_ava3[4];
OM_descriptor cpub_ava4[4];
OM_value_position desc_count;
DS_status status;
OM_sint invoke_id;
OM_uint completion_flag;
DS_status operation_status;
OM_return_code om_status;
OM_private_object name, read_result;
OM_public_object spub_result;
OMX_CLASS_DESC( cpub_ava0[0], DS_C_AVA);
OMX_ATTR_TYPE_DESC( cpub_ava0[1], DS_ATTRIBUTE_TYPE,
DSX_TYPELESS_RDN);
OMX_ZSTRING_DESC( cpub_ava0[2], OM_S_PRINTABLE_STRING,
DS_ATTRIBUTE_VALUES,
"CDS");
OMX_OM_NULL_DESC( cpub_ava0[3]);
OMX_CLASS_DESC( cpub_ava1[0], DS_C_AVA);
OMX_ATTR_TYPE_DESC( cpub_ava1[1], DS_ATTRIBUTE_TYPE,
DSX_TYPELESS_RDN);
OMX_ZSTRING_DESC( cpub_ava1[2], OM_S_PRINTABLE_STRING,
DS_ATTRIBUTE_VALUES,
"Projects");
OMX_OM_NULL_DESC( cpub_ava1[3]);
OMX_CLASS_DESC( cpub_ava2[0], DS_C_AVA);
OMX_ATTR_TYPE_DESC( cpub_ava2[1], DS_ATTRIBUTE_TYPE,
DS_A_ORG_UNIT_NAME);
OMX_ZSTRING_DESC( cpub_ava2[2], OM_S_PRINTABLE_STRING,
DS_ATTRIBUTE_VALUES,
"Research");
OMX_OM_NULL_DESC( cpub_ava2[3]);
OMX_CLASS_DESC( cpub_ava3[0], DS_C_AVA);
OMX_ATTR_TYPE_DESC( cpub_ava3[1], DS_ATTRIBUTE_TYPE,
DS_A_ORG_NAME);
OMX_ZSTRING_DESC( cpub_ava3[2], OM_S_PRINTABLE_STRING,
DS_ATTRIBUTE_VALUES,
"Digital Equipment Corporation");
OMX_OM_NULL_DESC( cpub_ava3[3]);
OMX_CLASS_DESC( cpub_ava4[0], DS_C_AVA);
OMX_ATTR_TYPE_DESC( cpub_ava4[1], DS_ATTRIBUTE_TYPE,
DS_A_COUNTRY_NAME);
OMX_ZSTRING_DESC( cpub_ava4[2], OM_S_PRINTABLE_STRING,
DS_ATTRIBUTE_VALUES,
"US");
OMX_OM_NULL_DESC( cpub_ava4[3]);
OMX_CLASS_DESC( cpub_rdn0[0], DS_C_DS_RDN);
OMX_OBJECT_DESC( cpub_rdn0[1], DS_AVAS, cpub_ava0);
OMX_OM_NULL_DESC( cpub_rdn0[2]);
OMX_CLASS_DESC( cpub_rdn1[0], DS_C_DS_RDN);
OMX_OBJECT_DESC( cpub_rdn1[1], DS_AVAS, cpub_ava1);
OMX_OM_NULL_DESC( cpub_rdn1[2]);
OMX_CLASS_DESC( cpub_rdn2[0], DS_C_DS_RDN);
OMX_OBJECT_DESC( cpub_rdn2[1], DS_AVAS, cpub_ava2);
OMX_OM_NULL_DESC( cpub_rdn2[2]);
OMX_CLASS_DESC( cpub_rdn3[0], DS_C_DS_RDN);
OMX_OBJECT_DESC( cpub_rdn3[1], DS_AVAS, cpub_ava3);
OMX_OM_NULL_DESC( cpub_rdn3[2]);
OMX_CLASS_DESC( cpub_rdn4[0], DS_C_DS_RDN);
OMX_OBJECT_DESC( cpub_rdn4[1], DS_AVAS, cpub_ava4);
OMX_OM_NULL_DESC( cpub_rdn4[2]);
OMX_CLASS_DESC( cpub_dn[0], DS_C_DS_DN);
OMX_OBJECT_DESC( cpub_dn[1], DS_RDNS, cpub_rdn4);
OMX_OBJECT_DESC( cpub_dn[2], DS_RDNS, cpub_rdn3);
OMX_OBJECT_DESC( cpub_dn[3], DS_RDNS, cpub_rdn2);
OMX_OBJECT_DESC( cpub_dn[4], DS_RDNS, cpub_rdn1);
OMX_OBJECT_DESC( cpub_dn[5], DS_RDNS, cpub_rdn0);
OMX_OM_NULL_DESC( cpub_dn[6]);
/∗ create the OM private object: name ∗/
om_status = om_create(DS_C_DS_DN, OM_FALSE, workspace, &name);
/∗ Copy the attribute list from the cpub_dn public object into ∗/
/∗ the name private object ∗/
om_status = om_put(name, OM_REPLACE_ALL, cpub_dn, 0,0,0);
/∗ call the ds_read function using Name as a parameter and ∗/
/∗ specify that all attribute types and values be read. ∗/
/∗ Note that invoke_id parameter is may be set NULL in the ∗/
/∗ case of synchronous operation. ∗/
status = ds_read(bound_session, DS_DEFAULT_CONTEXT, name,
DS_SELECT_ALL_TYPES_AND_VALUES, &read_result,
NULL);
if (status == DS_SUCCESS)
{
printf("READ request was successful0);
om_status = om_get(read_result, OM_NO_EXCLUSIONS,
0, 0, 0, OM_ALL_VALUES,
&spub_result, &desc_count);
if (om_status == OM_SUCCESS)
{
/∗ check desc_count != 0 ∗/
/∗ results now available in public object ∗/
/∗ spub_result ∗/
}
else
{
/∗ error getting results ∗/
/∗ search_result not deleted ∗/
}
}
else
{
printf("READ request failed0);
} }
Example 3 shows the synchronous reading of all attribute types and values from the CDS entry
/.../C=US/O=Digital Equipment Corporation/OU=Research/Projects/CDS
Note the use of the special attribute type DSX_TYPELESS_RDN in the rightmost RDNs of the name. The presence of one or more occurrences of this attribute type indicates to the XDS API that a name is a CDS distinguished name.
Note that the CDS global naming root /... need not be explicitly supplied as the first RDN in a CDS distinguished name. When the XDS API encounters a CDS distinguished name, it will internally prepend the CDS global naming root, unless one of the CDS local naming roots such as /.: or /: has been explicitly supplied.
A CDS local naming root, if desired, must be explicitly supplied as the first RDN of a distinguished name. It is specified with an attribute type of DSX_TYPELESS_RDN and an attribute value of .: or : as appropriate.
Note that the Invoke-ID argument is not needed for synchronous operation and is therefore set to NULL. The Bound-Session argument is assumed to have been set up as in Example 1.