Digital DCE for OpenVMS VAX and OpenVMS Alpha
Reference Guide


Previous Contents Index

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.


 
{ 
     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 successful\n"); 
     } 
     else 
     { 
        printf("READ request failed\n"); 
     } 
     /* 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; 
            } 
        } 
    } 
} 
 

The above example shows:


ds_receive_result(3xds)

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 read
Completion-Flag Unsigned Integer write
Operation-Status DS_status write
Result OM_private_object write
Invoke-ID Integer write
Status DS_status  

C Binding

DS_status ds_receive_result(session, completion_flag, operation_status, result, invoke_id)


DS_status ds_receive_result (
OM_private_object session
OM_uint context<completion_flag_returned>(indent\3) DS_status operation_status_return
OM_private_object result_return
OM_sint invoke_id_return)


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:

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.


Return Values

Possible return values are as follows:
Return Description
DS_SUCCESS The operation completed successfully.
DS_NO_WORKSPACE A workspace has not been set up by a call to the Initialize function.

If neither of these constants is 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:

Examples

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.


 
{ 
    /* 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.


ds_remove_entry(3xds)

Removes an entry from the Directory Information Tree (DIT).

Syntax

Status = ds_remove_entry(Session, Context, Name, Invoke-ID)

Argument Data Type Access
Session OM_private_object read
Context OM_private_object read
Name OM_object read
Invoke-ID Integer write
Status DS_status  

C Binding

DS_status ds_remove_entry(session, context, name, invoke_id_return)


DS_status ds_remove_entry (
OM_private_object session
OM_private_object context
OM_object name
OM_sint invoke_id_return)


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 and Dont-Dereference-Aliases Context parameters do 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 not be dereferenced.

Invoke_ID

The Invoke-ID of an asynchronous directory operation.

Description

This function is used to remove an entry from the Directory. This may be an object entry or an alias entry. The entry must not have any subordinate entries.

Note

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 Remove Entry function:


Return Values

Possible return values are as follows:
Return Description
DS_SUCCESS The entry was removed, if the operation was invoked synchronously. The operation was initiated, if it was invoked asynchronously.
DS_NO_WORKSPACE A workspace has not been set up by a call to the Initialize function.

If neither of these constants is 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:

Examples

The following code extracts show an example call to the Remove Entry function. The Remove Entry function is used to remove an existing directory entry.

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

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 Name argument and the Context argument are 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. An example of how to define a Context argument is shown in the Add Entry function.


 
OM_private_object bound_session, context, name; 
{ 
    DS_status         status; 
    OM_sint           invoke_id; 
    OM_uint           completion_flag; 
    DS_status         operation_status; 
    OM_private_object remove_entry_result; 
    /* Call the Remove Entry function */ 
    status = ds_remove_entry(bound_session, context, name, 
                             &invoke_id); 
  
    if (status == DS_SUCCESS) 
    { 
        printf("REMOVE ENTRY request was successful\n"); 
    } 
    else 
    { 
        printf("REMOVE ENTRY request failed\n"); 
    } 
    /* 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, 
                                   &remove_entry_result, 
                                   &invoke_id); 
        if (status == DS_SUCCESS) 
        { 
            switch (completion_flag) 
            { 
                case DS_COMPLETED_OPERATION: 
                /* we have a completed operation */ 
                /* check operation_status */ 
                break; 
                case DS_OUTSTANDING_OPERATIONS: 
                ... 
                break; 
                case DS_NO_OUTSTANDING_OPERATION: 
                ... 
                break; 
            } 
        } 
    } 
} 

The above example removes the directory entry, identified in the Name argument, from the directory. Since the operation is executed asynchronously, an invoke identifier is returned in the Invoke-ID argument. This uniquely identifies this specific operation and is therefore used in the subsequent Receive Result function to obtain the result of the operation.


Previous Next Contents Index