(c) Digital Equipment Corporation. 1994. All rights reserved.

Name

ds_list − Lists all the immediate subordinate entries of a directory entry. 
 
 
 

Syntax

 
Status = ds_list(Session, Context, Name, 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} Result@OM_private_object@T{ write T} Invoke-ID@Integer@T{ write T} Status@T{ DS_status T}

C Binding

 
 
DS_status ds_list(session, context, name, result_return, invoke_id_return)
 
 

 
OM_private_object@T{ session T} OM_private_object@T{ context T} OM_object@T{ name 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. This argument must be a Context OM private object or the constant Default-Context.
 

Name
 
 
A Name OM object specifying the name of the object entry whose immediate subordinates are to be listed. Any aliases in the name will be dereferenced unless prohibited by the Context parameter Dont-Dereference-Aliases.
 

Result
 
 
A List-Result OM private object, passed by reference, containing some information about the target object’s immediate subordinates. It also contains the distinguished name of the target object if an alias was dereferenced to find it.
 
 
Aliases in the subordinate names are identified, but not dereferenced.
 
Additionally, there may be a partial outcome qualifier which indicates that the result is incomplete.  It also explains the reason why, for example, the time limit expired, and contains information that may be helpful when attempting to complete the operation.
 

Invoke-ID
 
 
The Invoke-ID of an asynchronous directory operation.
 
 

Description

 
 
This function is used to obtain a list of all the immediate subordinates of a named entry. It is possible that the list will be incomplete in some circumstances.

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

Return Value

The target object was located regardless of whether it has any subordinates, 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
 

Name-Error
 

Referral
 

Security-Error
 

Service-Error
 

Communications-Error
 
 
 
 
 

Examples

 
 
The following code extracts show an example call to the List function. The List function is used to list the subordinates of the directory entry identified in the Name argument.

 
There are two examples. The first example shows how to perform an asynchronous List operation. The second example shows how to perform a synchronous List operation.

 
The Bound_Session argument contains the identity of a session, established using the Bind function, 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 bound_session, context, name;
 
OM_workspace      workspace;
 
{
 
    DS_status         status;
    OM_private_object list_result;
    OM_sint           invoke_id;
    OM_uint           completion_flag;
    DS_status         operation_status;
    OM_return_code    om_status;
    OM_public_object  spub_result;
    OM_value_position desc_count;
 
 
    /∗ call ds_list to list the subordinates of the entry ∗/
    /∗ identified in name                                 ∗/
 
    status = ds_list(bound_session, context, name, &list_result,
                     &invoke_id);
 
    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, &list_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(list_result, OM_NO_EXCLUSIONS,
                                   0, 0, 0, OM_ALL_VALUES,
                                   &spub_result, &desc_count);
 
                if (om_status == OM_SUCCESS)
                {
                   /∗ if desc_count is not zero, the results are now ∗/
                   /∗ available in the public object spub_result     ∗/
                }
                else
                {
                   /∗ error getting results ∗/
                }
            }
            else
            {...}
            break;
 
            case DS_COMPLETED_OPERATION:
            ...
            break;
 
            case DS_COMPLETED_OPERATION:
            ...
            break;
        }
    }
  }
 

 
Example 1 shows:
 
 

•A call to the List function. 
 

•How to use the Receive Result function to obtain the result of the List function. 
 

•How to use the OM Get function to copy the attributes of the List-Result OM private object into the equivalent List-Result OM public object (Spub_Result) for examination. 
 

 
The OM Get function is assumed to succeed.

Exhibit 0-0.

 
OM_private_object bound_session, context, name;
 
{
    DS_status         status;
    OM_private_object list_result;
    OM_public_object  spub_result;
    OM_value_position desc_count;
 
    status = ds_list(bound_session, DS_DEFAULT_CONTEXT, name,
                     &list_result, NULL);
 
    if (status == DS_SUCCESS)
    {
        /∗ LIST was successful ∗/
 
        /∗ now see what we have got back ... ∗/
 
        om_status = om_get(list_result, OM_NO_EXCLUSIONS,
                           0, 0, 0, OM_ALL_VALUES,
                           &spub_result, &desc_count);
 
        if (om_status == OM_SUCCESS)
        {
            /∗ if desc_count!=0, results now available as a public ∗/
            /∗ object                                              ∗/
        }
        else
        {
            /∗ error getting results ∗/
        }
 
    }
    else
    {...}
 
}
 

 
Example 2 shows how to perform a synchronous List 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.