Name

ds_list - Enumerates the immediate subordinates of a particular directory entry

Synopsis

#include <xom.h>
#include <xds.h> 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);

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.  This parameter must be a private object or the DS_DEFAULT_CONTEXT constant. 

name(Object(DS_C_NAME)).  The name of the object entry whose immediate subordinates are to be listed.  Any aliases in the name are dereferenced unless this is prohibited by the service control attribute DS_DONT_DEREFERENCE_ALIASES of the DS_­C_­CONTEXT object. 

Output

result_return(Object(DS_C_LIST_RESULT)).  Upon successful completion, the result contains some information about the target object’s immediate subordinates.  It also contains the DN of the target object, if an alias was dereferenced to find it.  Aliases in the subordinate names are not dereferenced.  In addition, there can be a partial outcome qualifier, which indicates that the result is incomplete.  It also explains the reason for this (for example, because the time limit expired), and it contains information that can be helpful when attempting to complete the operation. 

invoke_ID_return
(Integer).  Not supported.

Description

The ds_list() function is used to obtain a list of the immediate subordinates of the named entry.  The list can be incomplete in some circumstances; for example, if the results exceed DS_SIZE_LIMIT. 

Return Values

DS_statusTakes the value DS_SUCCESS if the named object is located (even if there are no subordinates) and takes an error value if not. 

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 function can return the following directory errors:

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