ds_receive_result(3xds) — Subroutines

Name

ds_receive_result − This function retrieves the result of an asynchronously executed operation.

Syntax

Status = ds_receive_result(Session, Completion-Flag, Operation-Status, Result, Invoke-ID)

Argument@Data Type@Access

Session@OM_private_object@T{ read T} Completion-Flag@Unsigned Integer@T{ write T} Operation-Status@DS_status@T{ write T} Result@OM_private_object@T{ write T} Invoke-ID@Integer@T{ write T} Status@T{ DS_status T}

C Binding

DS_status ds_receive_result(session, completion-flag, operation-status, result, invoke-id)

OM_private_object@T{ session T} OM_uint@T{ ∗completion_flag_return T} DS_status@T{ ∗operation_status_return 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 in which the operation was performed.

Completion-Flag

One of the following values to indicate the status of outstanding asynchronous operations:

•Completed-Operation. At least one outstanding asynchronous operation has completed and its result is available.

•Outstanding-Operations. There are outstanding asynchronous operations but none has completed.

•No-Outstanding-Operation. There are no outstanding asynchronous operations.

The result of the Completion-Flag parameter is valid if Status has the value Success.

Upon successful return with Completion-Flag having the value completed-operation, Status and Invoke-ID parameter values for the completed operation are returned.

Operation-Status

Takes an error value if an error occurred during the execution of the asynchronous directory operation. If no error occurred then it takes the value success. The possible error values are listed for each individual operation in the corresponding function description.

This result is only valid if the status has the value success and Completion-Flag has the value completed-operation.

Result

The result of the completed asynchronous operation. Its value is the constant Null-Result if the operation was one that does not return a result (Add-Entry, Modify-Entry, Modify-RDN, or Remove-Entry). Otherwise it is an OM object of the appropriate OM class for the result of the asynchronous operation. You can check the class of the Result by using the OM functions.

This result is only valid if the following conditions are true:

•Status has the value success

•Completion-Flag has the value completed-operation

•Operation-Status has the value success

Invoke-ID

The Invoke-ID of the operation whose result is being returned.

This result is valid if the Status has the value success and Completion-Flag has the value completed-operation.

Description

This function is used to retrieve the completed results of an outstanding asynchronous operation.

The function results include two status indications. One, called Status, indicates that the function call itself was successful and is always returned. The other, called Operation-Status, is used to return the status of the completed asynchronous operation and is only returned if there is one. See DEC X.500 Directory Service Programming for information about calling functions asynchronously.

DCE Notes

The DCE XDS interface does not support asynchronous operations.

Return Value

The operation completed successfully. 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 object:

Library-Error, with Problem attribute values of bad-session, or miscellaneous

Any errors related to the completed asynchronous operation are reported in Operation-Status as described above.

Example

The following code extract shows an example call to the Receive Result function. The Receive Result function is used to obtain the result of an outstanding asynchronous operation.

Exhibit 0-0.

{
    /∗ Call the Modify Entry function asynchronously using the   ∗/
    /∗ changes object as a parameter. The Asynchronous attribute ∗/
    /∗ on the OM Context object has value True                   ∗/

    status = ds_modify_entry(session,context,name,changes,&invoke_id);

    if (status == DS_SUCCESS)
    {...}
    else
    {...}

    /∗ 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,
                                   &modify_entry_result,
                                   &invoke_id);

        if (status == DS_SUCCESS)
        {
            switch (completion_flag)
            {
                case DS_COMPLETED_OPERATION:
                /∗ operation is complete ∗/
                break;

                case DS_OUTSTANDING_OPERATIONS:
                ...
                break;

                case DS_NO_OUTSTANDING_OPERATION:
                ...
                break;
            }
        }
    } }

The Receive Result function uses as input, the Invoke-ID argument output from the asynchronous function.

Museum