Name

ds_read - Queries information on an entry by name

Synopsis

#include <xom.h>
#include <xds.h> DS_status ds_read(
OM_private_object session,
OM_private_object context,
OM_object name,
OM_object selection,
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. 

selection(Object(DS_C_ENTRY_INFO_SELECTION)).  Specifies what information from the entry is requested.  Information about no attributes, all attributes, or just for a named set can be chosen.  Attribute types are always returned, but the attribute values need not be returned.  The possible values of this parameter are given in the OSF DCE Application Development Guide—Directory Services. 

Output

result_return(Object(DS_C_READ_RESULT)).  Upon successful completion, the result contains the DN of the target object, and a flag indicating whether the result came from the original entry or a copy, as well as any requested attribute types and values.  Attribute information is only returned if access rights are sufficient. 

invoke_id_return
(Integer).  Not supported.

Description

The ds_read() function is used to extract information from an explicitly named entry.  It can also be used to verify a DN. 

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_read() operation:

       •Since CDS does not implement the X.500 schema rules, some CDS objects may not contain mandatory attributes like 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 DS_C_NAME_ERROR (DS_­E_­NO_­SUCH_­OBJECT). 

       •In CDS, the naming attribute of an object is not stored in the attribute list for the object.  Thus in CDS, ds_read() does not return this attribute in the attribute list for an object. 

Return Values

DS_statusIndicates whether or not the read operation is completed.  This is DS_SUCCESS if completed. 

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_ATTRIBUTE

       •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 by the function:

       •DS_C_ATTRIBUTE_ERROR

       •DS_C_NAME_ERROR

       •DS_C_REFERRAL

       •DS_C_SECURITY_ERROR

       •DS_C_SERVICE_ERROR

Note that the directory error DS_C_ATTRIBUTE_ERROR (DS_­E_­NO_­SUCH_­ATTRIBUTE_­OR_­VALUE) is reported in GDS if an explicit list of attributes is specified by the selection parameter, but none of them are present in the entry.  This error is not reported if any of the selected attributes are present. 

A DS_C_SECURITY_ERROR (DS_E_INSUFFICIENT_ACCESS_RIGHTS) is only reported where access rights preclude the reading of all requested attribute values. 

This function can return a DS_C_COMMUNICATIONS_ERROR, as well as the error constant DS_NO_WORKSPACE.