3 — XDS Directory Services ReferencePages

[Previous] [Next] [Contents]

This chapter provides reference pages for the X/Open Directory Services (XDS) API functions. Digital's XDS implementation includes two additional XDS functions that support asynchronous operations. The functions are as follows:

• The ds_abandon function abandons the outstanding asynchronous function call.

• The ds_receive_result function retrieves completed results of an outstanding asynchronous operation.

ds_intro - This reference page introduces the X/OPEN Directory Services (XDS) functions.

Syntax

#include <xom.h>#include <xds.h>

Description

This reference page lists the XDS interface functions supported in the Digital X.500 product. XDS provides a C language binding

.

Function	Description
ds_abandon	Abandons an outstanding asynchronous operation.
ds_add_entry	Adds a leaf entry to the Directory Information Tree (DIT).
ds_bind	Opens a session with a directory user agent.
ds_compare	Compares a purported attribute value with the attribute value stored in the directory for a particular entry.
ds_initialize	Initializes the interface.
ds_list	Enumerates the immediate subordinates of a particular directory entry.
ds_modify_entry	Performs an atomic modification of a directory entry.
ds_modify_rdn	Changes the Relative Distinguished Name (RDN) of a leaf entry.
ds_read	Queries information on a directory entry by name
ds_receive_result	Retrieves the result of an asynchronously executed operation
ds_remove_entry	Removes a leaf entry from the DIT
ds_search	Finds entries of interest in a portion of the DIT
ds_shutdown	Shuts down the interface
ds_unbind	Unbinds from a directory session
ds_version	Negotiates features of the interface and service
dsX_trace_object	Displays an explanation of the content of an object

DCE Notes

The DEC X.500 Directory Service supports asynchronous operations, which the Distributed Computing Environment (DCE) XDS interface does not. Thus, the Abandon and Receive Result functions are included in the Digital product.

The differences between the X.500 Directory Service and the Cell Directory Service (CDS) are as follows:

• All functions operate on the X.500 name space.

• CDS does not support the Modify RDN or Search functions. The Service-Error unwilling-to-perform is returned if either function is attempted on CDS.

• CDS does not support the X.500 schema. Therefore, CDS does not have:

• The concept of an object class

• Mandatory attributes for a given object

• A set of attributes expressly permitted for a given object

• A predefined definition of single and multivalued attributes

  The absence of the schema means that the usual errors, which are returned by X.500 for breach of the rules, are not returned by CDS.

• The CDS naming Directory Information Tree (DIT) is modeled on a typical file system architecture, in which directories are used to store objects and can contain subdirectories. Leaf objects in the CDS DIT are similar to X.500 naming objects. However, subtree objects are called directories as in a file system directory. All new objects must be added to an existing directory. CDS directory objects cannot be added, removed, modified, or compared using the XDS programming interface.

• In CDS, the naming attribute of an object is not stored in the object. Consequently, in CDS the Read operation never returns this attribute, and the Compare operation applied to this attribute returns with the Attribute-Error constraint-violation.

See the notes in the relevant reference page for function-specific differences.

ds_abandon(3xds)

ds_abandon - This function abandons an outstanding asynchronous operation.

Syntax

Status = ds_abandon(Session, Invoke-ID)

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

C Binding

DS_status ds_abandon(session, invoke_id)

OM_private_object	session
OM_sint	invoke_id

Arguments

Session

The Session OM private object that was returned by the Bind function, identifying the directory session in which the operation was submitted to the directory.

Invoke-ID

Identifies the operation that is to be abandoned. You can only abandon interrogatory operations (Compare, List, Read, and Search).

The value of Invoke-ID must be that which was returned by the function call that initiated the asynchronous directory operation that is now to be abandoned.

Description

This function abandons the outstanding asynchronous function call. The asynchronous function is no longer outstanding after the Abandon function returns, and the results of the asynchronous function will never be returned by the Receive-Result function.

DCE Notes

The DCE XDS interface does not support asynchronous operations.

Return Value

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:

• Abandon-Failed

• Communications-Error

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

• The result of the asynchronous operation will not be returned even if an Abandon-Failed error is returned.

The following code extract shows an example call to the Abandon function.

OM_private_object  bound_session;
OM_sint            invoke_id;
{
    DS_status          status;
    status = ds_abandon(bound_session, invoke_id);
    if (status == DS_SUCCESS)
    {
      printf("ABANDON was successful\n");
    }
    else
    {
      printf("ABANDON failed\n");
    }
}

The abandon function abandons the results of the asynchronous operation identified by the Invoke-ID argument.

ds_add_entry(3xds)

ds_add_entry - Adds an entry to the Directory Information Tree (DIT).

Syntax

Status = ds_add_entry(Session, Context, Name, Entry, Invoke-ID)

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

C Binding

DS_status ds_add_entry(session, context, name, entry, invoke_id_return) session

OM_private_object	session
OM_private_object	context
OM_object	name
OM_object	entry
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 Context parameters 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 distinguished name of the entry to be added. The immediate superior of the new entry is determined by removing the last RDN component that belongs to the new entry. The immediate superior should exist in the same DSA; otherwise, the function may fail with an Update-Error, affecting-multiple-DSAs. It does not fail if an agreement exists between the DSAs that allows the entry to be added. Any aliases in the name will not be dereferenced.

Entry

The attribute information which, together with the RDN, constitutes the entry to be created. The information must be contained in an Attribute List OM object, or an OM object that is a subclass of Attribute-List. The object parameter should not contain the value of the RDN of the entry being created.

Invoke-ID

The Invoke-ID of an asynchronous directory operation. This is passed by reference.

Description

This function adds an entry to the Directory. The entry can be either an object entry or an alias entry. The Directory checks that the resulting entry conforms to the Directory schema.

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 Add Entry 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.

• Only leaf objects (that is, objects that are not CDS directory objects) can be added to CDS through the XDS interface.

• The DS_A_OBJECT_CLASS attribute of an object is single valued in CDS and multivalued in X.500. If the Entry argument contains a DS_A_OBJECT_CLASS attribute with a value of DS_O_ALIAS, a CDS alias (soft link) will be created. If the attribute value is DS_O_GROUP_OF_NAMES, a CDS Group object will be created. Any other value for DS_A_OBJECT_CLASS, or the absence of this attribute, will result in the creation of an ordinary CDS object.

• Only the DS_A_COMMON_NAME and DS_A_MEMBER attributes are valid for the DS_O_GROUP_OF_NAMES object in CDS.

• CDS supports only the following X.500 attribute syntaxes:

  OM_S_TELETEX_STRING
  OM_S_OBJECT_IDENTIFIER_STRING
  OM_S_OCTET_STRING
  OM_S_PRINTABLE_STRING
  OM_S_NUMERIC_STRING
  OM_S_BOOLEAN
  OM_S_INTEGER
  OM_S_UTC_TIME_STRING
  OM_S_ENCODING_STRING
  

If attributes of any other syntax are supplied to an Add Entry operation that references CDS, then it returns the Attribute-Error constraint-violation. Because CDS does not implement the X.500 schema rules, some CDS objects may not contain mandatory attributes like object class and so on.

Return Value

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:

• Attribute-Error, constraint-violation

• Communications-Error

• 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, no-such-object

• Referral

• Security-Error

• Service-Error

• Update-Error

The following code extracts show an example call to the Add Entry function. The Add Entry function is used to create a new directory entry containing two attributes: common name and organization unit.

There are two examples. The first example shows how to perform an asynchronous Add Entry operation. The second example shows how to perform a synchronous Add 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 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.

Example 1

OM_private_object bound_session, context;
OM_workspace      workspace;
OM_return_code    om_status = OM_SUCCESS;
OM_descriptor     ATLST_entry[4],					/* contents of entry */
		  ATTR_sn_Black[4],
		  ATTR_oc_OrgPerson[5],
	          Context[3];				/* For the context */
/* Define the first X.500 Object Class attribute */
OMX_CLASS_DESC(     ATTR_oc_OrgPerson[0], DS_C_ATTRIBUTE);
OMX_ATTR_TYPE_DESC( ATTR_oc_OrgPerson[1], DS_ATTRIBUTE_TYPE,
                                          DS_A_OBJECT_CLASS);
OMX_STRING_DESC(   ATTR_oc_OrgPerson[2],  OM_S_OBJECT_IDENTIFIER_STRING,
                                          DS_ATTRIBUTE_VALUES,
                                          DS_O_PERSON.elements,
                                          DS_O_PERSON.length);
OMX_STRING_DESC(   ATTR_oc_OrgPerson[3],  OM_S_OBJECT_IDENTIFIER_STRING,
                                          DS_ATTRIBUTE_VALUES,
                                          DS_O_ORG_PERSON.elements,
                                          DS_O_ORG_PERSON.length);
OMX_OM_NULL_DESC(   ATTR_oc_OrgPerson[4]);
/* Define the X.500 Surname attribute */
OMX_CLASS_DESC(     ATTR_sn_Black[0], DS_C_ATTRIBUTE);
OMX_ATTR_TYPE_DESC( ATTR_sn_Black[1], DS_ATTRIBUTE_TYPE,
                                      DS_A_SURNAME);
OMX_ZSTRING_DESC(   ATTR_sn_Black[2], OM_S_PRINTABLE_STRING,
                                      DS_ATTRIBUTE_VALUES,
                                      "Black");
OMX_OM_NULL_DESC(   ATTR_sn_Black[3]);
/* Define the Attribute List */
OMX_CLASS_DESC(     ATLST_entry[0],   DS_C_ATTRIBUTE_LIST);
OMX_OBJECT_DESC(    ATLST_entry[1],   DS_ATTRIBUTES, ATTR_sn_Black);
OMX_OBJECT_DESC(    ATLST_entry[2],   DS_ATTRIBUTES, ATTR_oc_OrgPerson);
OMX_OM_NULL_DESC(   ATLST_entry[3]);
/* now create the context object and set the Asynchronous flag to */
/* true to indicate that the operation should be asynchronous.    */
om_status = om_create(DS_C_CONTEXT, OM_TRUE, workspace, &context);
OMX_CLASS_DESC(  Context[0],   DS_C_CONTEXT);
OMX_BOOLEAN_DESC(Context[1],   DS_ASYNCHRONOUS,OM_TRUE);
OMX_OM_NULL_DESC(Context[2]);
/* Now place the contents of the public object cpub_context into */
/* the private object context                                    */
om_status = om_put(context, OM_REPLACE_ALL, Context, 0, 0, 0);
{
     DS_status         status;
     OM_sint           invoke_id;
     OM_uint           completion_flag;
     DS_status         operation_status;
     OM_return_code    om_status;
     OM_private_object entry, add_entry_result;
     /* create the OM private object: entry */
     om_status = om_create(DS_C_ATTRIBUTE_LIST, OM_FALSE, workspace,
                           &entry);
     /* Copy the attribute list from the cpub_attr_list public */
     /* object into the entry private object                   */
     om_status = om_put(entry, OM_REPLACE_ALL, ATLST_entry, 0, 0, 0);
     /* Call the Add Entry function using entry as a parameter */
     status = ds_add_entry(bound_session, context, name, entry,
                           &invoke_id); 

     if (status == DS_SUCCESS)
     {
        printf("ADD ENTRY request was successful\n");
     }
     else
     {
        printf("ADD 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,
                                   &add_entry_result, &invoke_id);
        if (status == DS_SUCCESS)
        {
            switch (completion_flag)
            {
                case DS_COMPLETED_OPERATION:
                /* we have a completed operation */
                if(operation_status == DS_SUCCESS)
                {
                    printf("ADD ENTRY was successful\n");
                }
                break;
                case DS_OUTSTANDING_OPERATIONS:
                printf("There are outstanding operations\n");
                break;
                case DS_NO_OUTSTANDING_OPERATION:
                printf("There are NO outstanding operations\n");
		

break; } } }}

The above example shows:

• How to define a private object containing context parameters.

• How to define a public object (cpub_attr_list) containing the attributes to be added to the new directory entry.

• How to use the OM Create function to create a private object (entry) and how to use the OM Put function to copy the entry's attributes from the public object (cpub_attr_list) into the newly created private object (entry).

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

The OM Create and the OM Put functions are assumed to succeed.

Example 2

OM_private_object bound_session, context, name;
{
    DS_status         status;
    OM_private_object entry;
    status = ds_add_entry(bound_session, DS_DEFAULT_CONTEXT, name,
                          entry, NULL);
    if (status == DS_SUCCESS)
    {
        printf("ADD ENTRY was successful\n");
    }
    else
    {
        printf("ADD ENTRY failed\n");
    }
}

The above example shows how to perform a synchronous Add Entry 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.

ds_bind(3xds)

ds_bind - Opens a session with the directory service.

Syntax

Status = ds_bind(Session, Workspace, Bound-Session)

Argument	Data Type	Access
Session	OM_object	read
Workspace	OM_workspace	read
Bound-Session	OM_private_object	write
Status	DS_status

C Binding

DS_status ds_bind(session, workspace, bound_session_return)

OM_object	session
OM_workspace	workspace
OM_private_object	bound_session_return

Arguments

Session

A Session OM object specifying the address of the DSA to bind to, and other information. You can submit either an OM public object or an OM private object as this argument. You can also use the constant Default-Session as the value of this argument, causing a new session to be created with default values for all its OM attributes. The Bind operation uses information from the DUA defaults file when the constant Default-Session is used.

Workspace

Specifies the workspace (obtained from a call to the Initialize function) which is to be associated with the session. All function results from directory operations using this session will be returned as private objects in this workspace. If the Session argument is a private object, it must be a private object in this workspace.

Bound-Session

A Session OM private object identifying a directory session. This session may be used as an argument to other functions, for example the Read function. If the value of Session was Default-Session or a public object, then Bound-Session is a new private object. Otherwise, when the Session is a private object, then Bound-Session is that private object. The function supplies default values for any of the OM attributes that were not present in the session instance supplied as an argument. It also sets the value of the File-Descriptor OM Attribute. The initial value of this attribute is No-Valid-File-Descriptor. On an OpenVMS system, a file descriptor is not returned and the value of this attribute does not change. Note also that if the application binds only to a CDS directory, the value of the File-Descriptor OM attribute does not change.

Description

This function opens a session with the directory service and returns a session object for use in subsequent function calls. This function must be called before any other directory functions.

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 that to use CDS when X.500 is not active, the Bind function must be called with the value of the session parameter to set to DS_DEFAULT_SESSION. In this case, the Bind function will return DS_SUCCESS, but the returned Bound Session object may be used only for directory operations on the CDS namespace. If an operation is attempted against X.500 with this Bound Session, the directory routine will return the Library-Error, not-supported.

If your application was built and runs on a system where CDS is installed but X.500 is not installed, the Bind function will only attempt to bind to the CDS directory. If your application was built and runs on a system where X.500 is installed but CDS is not installed, the Bind function will only attempt to bind to the X.500 directory, and will return an error if it fails. If both CDS and X.500 are installed on the system and your application was built and runs against the XDS shareable library files (or on a DEC OSF/1 system was linked against the archive libraries libdxd.a and libdxdcds.a), then the Bind function will attempt to bind to both directories.

Note that in normal operation, no error message is returned if the Bind function fails to connect to an X.500 directory, but an error will be returned when your application attempts an X.500 operation. If you require error messages to be returned when the Bind function fails, your application must call the Version function and negotiate the Digital extension feature DSX-RET-X500-BIND-ERR-FTR.

Return Value

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:

• System-Error
  
• Library-Error, with Problem attribute values of bad-session, miscellaneous, not-supported or too-many-sessions
  
• Security-Error
  
• Service-Error
  
• Communications-Error
  

The following code extract shows an example call to the Bind function. It establishes a session with the directory service.

OM_private_object  bound_session;
OM_workspace       workspace;
{
    DS_status         status;
  

    status = ds_bind(DS_DEFAULT_SESSION, workspace, &bound_session); 
    if (status == DS_SUCCESS)
    {
      printf("BIND was successful\n");
    }
    else
    {
      printf("BIND failed\n");
    }

}

The Bind function associates a workspace, obtained from a call to the Initialize function, with the directory service session returned in the Bound_Session argument. The function uses the default session constant DS_DEFAULT_SESSION as the Session argument.

ds_compare(3xds)

ds_compare - Compares an attribute value with the attribute value stored in the Directory for a particular entry.

Syntax

Status = ds_compare(Session, Context, Name, AVA, Result, Invoke-ID)

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

C Binding

DS_status ds_compare(session, context, name, ava, result_return, invoke_id_return)

OM_private_object	session
OM_private_object	context
OM_object	name
OM_object	ava
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 to be used.

Context

The Context parameters to be used for this operation. The Size-Limit Context parameter does 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 be dereferenced unless prohibited by the Context parameter Dont-Dereference-Aliases.

AVA

An AVA OM object containing the attribute-value-assertion that specifies the attribute type and value to be compared with that in the entry.

Result

A Compare-Result OM private object containing flags indicating whether the values matched and whether the comparison was made against the original entry. It also contains the Distinguished Name of the target object if an alias was dereferenced.

Invoke-ID

The Invoke-ID of an asynchronous directory operation. This is only valid if the Asynchronous OM attribute in the Context parameter is set to True.

Description

This function checks that the value supplied in the given AVA is the same as the value or values of the same attribute type in the named entry. The operation fails and an error is returned if the target object is not found or if the target entry does not have the required attribute type.

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 betweenoperations on X.500 and CDS.) Note the following issues for the Compare 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.

• In CDS, the naming attribute of an object is not stored in the attribute list of an object. Thus in CDS a Compare operation of the purported naming attribute value with the naming attribute value of the directory object always fails to match.

• CDS supports only the following X.500 attribute syntaxes:

  OM_S_TELETEX_STRING
  OM_S_OBJECT_IDENTIFIER_STRING
  OM_S_OCTET_STRING
  OM_S_PRINTABLE_STRING
  OM_S_NUMERIC_STRING
  OM_S_BOOLEAN
  OM_S_INTEGER
  OM_S_UTC_TIME_STRING
  OM_S_ENCODING_STRING
  

  If attributes of any other syntax are supplied to a Compare operation that references CDS, then it returns the Attribute-Error constraint-violation.

• In CDS, the name parameter supplied to the Compare function must ultimately resolve to the name of a leaf (that is, a CDS Object) entry; otherwise, the Name-Error no-such-object is returned. The function never interprets the name parameter as the name of a CDS Directory entry.

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:

• Library-Error, with Problem attribute values of bad-argument, bad-context, bad-name, bad-session, miscellaneous, missing-type, not-supported or too-many-operations
  
• Attribute-Error, constraint-violation
  
• Name-Error, no-such-object
  
• Referral
  
• Security-Error
  
• Service-Error
  
• Communications-Error
  

The following code extracts show an example call to the Compare function. The Compare function is used to compare the common name attribute with the name attribute contained within the directory entry identified by the Name argument.

There are two examples. The first example shows how to perform an asynchronous Compare operation. The second example shows how to perform a synchronous Compare 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 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.

Example 1

     OM_private_object  ava;
     OM_workspace       workspace;
     OM_descriptor      cpub_ava[4];
     DS_status          status;
     OM_sint            invoke_id;
     OM_uint            completion_flag;
     DS_status          operation_status;
     OM_return_code     om_status;
     OM_private_object  name, compare_result;
     OM_return_code     om_status = OM_SUCCESS;
     OMX_CLASS_DESC(     cpub_ava[0], DS_C_AVA);
     OMX_ATTR_TYPE_DESC( cpub_ava[1], DS_ATTRIBUTE_TYPE,
                                      DS_A_COMMON_NAME);
     OMX_ZSTRING_DESC(   cpub_ava[2], OM_S_PRINTABLE_STRING,
                                      DS_ATTRIBUTE_VALUES,
                                      "Albert Einstein");
     OMX_OM_NULL_DESC(   cpub_ava[3]);
     /* create the OM private object: ava */
     om_status = om_create(DS_C_AVA, OM_FALSE, workspace, &ava);
     /* Copy the attribute list from the cpub_ava public object */
     /* into the ava private object                             */
 

     om_status = om_put(ava, OM_REPLACE_ALL, cpub_ava, 0,0,0);
     /* call the ds_compare function using ava as a parameter */
     status = ds_compare(bound_session, context, name,
                         ava, &compare_result, &invoke_id);
 

     if (status == DS_SUCCESS)
     {
        printf("COMPARE request was successful\n");
     }
     else
     {
        printf("COMPARE 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, &compare_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)
                {
                    printf("COMPARE result received\n");
                    /* use OM to examine compare_result object */
                    ...
                }
                else
                {
                    printf("COMPARE request failed\n");
                }
                break;
		

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

The above example shows:

• How to define an attribute value assertion and use that in the Compare function.

• How to define an AVA OM public object (cpub_ava) containing the attribute value assertion.

• How to use the OM Create function to create an AVA OM private object (ava) and how to use the OM Put function to copy the attribute value assertion from the public object (cpub_ava) into the newly created private object (ava).

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

  The OM Create and the OM Put functions are assumed to succeed.

OM_private_object bound_session, name, context;
{
     DS_status           status;
     OM_private_object   ava;
     status = ds_compare(bound_session, DS_DEFAULT_CONTEXT,
                         name, ava, &compare_result, NULL);
 

     if (status == DS_SUCCESS)
     {
        printf("COMPARE request was successful\n");
        /* examine compare result object to see if */
        /* comparison was TRUE or FALSE */
     }
     else
     {
        printf("COMPARE request failed\n");
     }
}

The above example shows how to perform a synchronous Compare 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.

ds_initialize(3xds)

ds_initialize - Initializes the interface.

Syntax

Workspace = ds_initialize(void)

Argument	Data Type
Workspace	OM_workspace

C Binding

OM_workspace ds_initialize(void)

Description

This function performs any necessary initialization of the X.500 API including the creation of a workspace. You must call this function before you call any other X.500 API functions. It may be called multiple times, in which case each call returns a workspace that is distinct from other workspaces created by the Initialize function but not yet deleted by the Shutdown function.

Return Value

Workspace

Upon successful completion this function returns a pointer to a workspace in which OM objects can be created and manipulated. Only objects created in this workspace can be used as arguments to the other directory interface functions. This function returns NULL if it fails.

Errors

This function does not return any errors.

Example

The following code extract shows an example of a call to the Initialize function. The Initialize function is used to initialize the X.500 API and create a workspace which can then be used by other functions.

OM_workspace workspace;
{
    if ((workspace = ds_initialize()) != NULL)
    {
      printf("INITIALIZE was successful\n");
    }
    else
    {
      printf("INITIALIZE failed\n");
    }
}

The Initialize function establishes the workspace that you can then use to communicate with the directory, for the remainder of the session.

ds_list(3xds)

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	read
Context	OM_private_object	read
Name	OM_object	read
Result	OM_private_object	write
Invoke-ID	Integer	write
Status	DS_status

C Binding

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

OM_private_object	session
OM_private_object	context
OM_object	name
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 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.

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
  

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.

Example 1

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;
        }
    }
    

}

This example 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.

Example 2

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
    {...}
}

This example 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.

ds_modify_entry(3xds)

ds_modify_entry - Performs an modification on an entry.

Syntax

Status = ds_modify_entry(Session, Context, Name, Changes, Invoke-ID)

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

C Binding

DS_status ds_modify_entry(session, context, name, changes, invoke_id_return)

OM_private_object	session
OM_private_object	context
OM_object	name
OM_object	changes
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 Context parameters 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 containing the name of the target entry. Any aliases in the name will be dereferenced if the DSA attribute Dereference Alias on Modify is set and the Dont Deference Aliases service control is not set.

Changes

An Entry-Modification-List OM object specifying a sequence of modifications to the named entry.

Invoke-ID

The Invoke-ID of an asynchronous directory operation.

Description

This function is used to make a series of one or more of the following changes to a single entry:

• Add a new attribute (add-attribute)
  
• Remove an attribute (remove-attribute)
  
• Add attribute values (add-values)
  
• Remove attribute values (remove-values)
  

You can replace values by a combination of adding values and removing values in a single operation. You can only change the RDN of an entry by using the Modify-RDN function.

The result of the operation is as if each modification is made in the order specified in the Changes argument. If any of the individual modifications fail, then an Attribute-Error is reported and the entry is left as it was before the whole operation. The operation is atomic, either all the changes are made or none are. The Directory Service checks that the resulting entry conforms to the schema.

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 Modify Entry 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.

• Naming schema rules do not apply in CDS. At the XDS API, all CDS attributes are treated as multivalued. Adding an attribute that already exists on the CDS entry causes an additional value to be added to that attribute's set of values. Thus the following Attribute-Errors are never returned by CDS:
  • no-such-attribute-or-value
    
  • attribute-or-value-already-exists
    

    Naming operations that would normally return these errors succeed in CDS. In particular, the addition of an attribute that already exists does not return with an error. Instead, the values of the attribute to be added are combined with the values of the existing attribute.

• CDS supports only the following X.500 attribute syntaxes:
  • OM_S_TELETEX_STRING
    
  • OM_S_OBJECT_IDENTIFIER_STRING
    
  • OM_S_OCTET_STRING
    
  • OM_S_PRINTABLE_STRING
    
  • OM_S_NUMERIC_STRING
    
  • OM_S_BOOLEAN
    
  • OM_S_INTEGER
    
  • OM_S_UTC_TIME_STRING
    
  • OM_S_ENCODING_STRING
    

    If attributes of any other syntax are supplied to a Modify Entry operation that references CDS, then it returns the Attribute-Error constraint-violation.

• In CDS, the name parameter supplied to the Modify Entry function must ultimately resolve to the name of a leaf (that is, a CDS Object) entry; otherwise the Name-Error no-such-object is returned. The function never interprets the name parameter as the name of a CDS Directory entry.

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:

• Library-Error, with Problem attribute values of bad-argument, bad-context, bad-name, bad-session, miscellaneous, missing-type, not-supported,or too-many- operations
  
• Attribute-Error, constraint-violation
  
• Name-Error, no-such-object
  
• Referral
  
• Security-Error
  
• Service-Error
  
• Update-Error
  
• Communications-Error
  

An Attribute-Error is returned if you attempt any of the following:

• To use Add-Attribute to add an existing attribute
  
• To add a value to a nonexistent attribute type
  
• To use Remove-Attribute to remove a nonexistent attribute or nonexistent attribute value
  

An attempt to remove an attribute or attribute value which is part of the object's RDN or to modify the object class attribute results in an Update-Error.

Examples

The following code extracts show an example call to the Modify Entry function. Note that the standard schema does not contain an object class with the attributes used in the example. The Modify Entry function is used to modify the directory entry, identified in the Name argument, as follows:

• Add a new X.500 attribute Title with the value "Sales & Marketing Director"

• Add the value "Abacus Trading Corporation" to the X.500 attribute Organization Name

• Remove the X.500 attribute Organizational Unit Name

• Remove the value "US" from the Country Name X.500 attribute

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

The Bound_Session argument contains the identity of a session, established using the Bind function, through which the request should be issued. Two arguments are assumed to have been previously defined. These are the Name argument and the Context argument. 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.

Example 1

OM_private_object bound_session, context, name;
/* define some public objects to contain the changes to be made to */
/* the directory entry                                             */
/* declare the descriptor lists (public objects) */
OM_descriptor cpub_mod_list[6];
OM_descriptor cpub_mod1[5];
OM_descriptor cpub_mod2[6];
OM_descriptor cpub_mod3[4];
OM_descriptor cpub_mod4[5];
/* define the first descriptor list */
OMX_CLASS_DESC(     cpub_mod1[0], DS_C_ENTRY_MOD);
OMX_ENUM_DESC(      cpub_mod1[1], DS_MOD_TYPE,
                                  DS_ADD_ATTRIBUTE);
OMX_ATTR_TYPE_DESC( cpub_mod1[2], DS_ATTRIBUTE_TYPE,
                                  DS_A_TITLE);
OMX_ZSTRING_DESC(   cpub_mod1[3], OM_S_PRINTABLE_STRING, 
                                  DS_ATTRIBUTE_VALUES,
                                  "Sales & Marketing Director");
OMX_OM_NULL_DESC(   cpub_mod1[4]);
/* define the second descriptor list */
OMX_CLASS_DESC(     cpub_mod2[0], DS_C_ENTRY_MOD);
OMX_ENUM_DESC(      cpub_mod2[1], DS_MOD_TYPE,
                                  DS_ADD_VALUES);
OMX_ATTR_TYPE_DESC( cpub_mod2[2], DS_ATTRIBUTE_TYPE,
                                  DS_A_ORG_NAME);
OMX_ZSTRING_DESC(   cpub_mod2[3], OM_S_PRINTABLE_STRING, 
                                  DS_ATTRIBUTE_VALUES, 
                                  "Abacus Trading Corporation");
OMX_ZSTRING_DESC(   cpub_mod2[4], OM_S_PRINTABLE_STRING, 
                                  DS_ATTRIBUTE_VALUES, 
                                  "Abacus");
OMX_OM_NULL_DESC(   cpub_mod2[5]);
/* define the third descriptor list */
OMX_CLASS_DESC(     cpub_mod3[0], DS_C_ENTRY_MOD);
OMX_ENUM_DESC(      cpub_mod3[1], DS_MOD_TYPE,
                                  DS_REMOVE_ATTRIBUTE);
OMX_ATTR_TYPE_DESC( cpub_mod3[2], DS_ATTRIBUTE_TYPE,
                                  DS_A_ORG_UNIT_NAME);
OMX_OM_NULL_DESC(   cpub_mod3[3]);
/* define the fourth descriptor list */
OMX_CLASS_DESC(     cpub_mod4[0], DS_C_ENTRY_MOD);
OMX_ENUM_DESC(      cpub_mod4[1], DS_MOD_TYPE,
                                  DS_REMOVE_VALUES);
OMX_ATTR_TYPE_DESC( cpub_mod4[2], DS_ATTRIBUTE_TYPE,
                                  DS_A_COUNTRY_NAME);
OMX_ZSTRING_DESC(   cpub_mod4[3], OM_S_PRINTABLE_STRING,
                                  DS_ATTRIBUTE_VALUES,
                                  "US");
OMX_OM_NULL_DESC(   cpub_mod4[4]);
 

/* define the fifth descriptor list */
OMX_CLASS_DESC(     cpub_mod_list[0],       DS_C_ENTRY_MOD_LIST);
OMX_OBJECT_DESC(    cpub_mod_list[1],       DS_CHANGES, cpub_mod1);
OMX_OBJECT_DESC(    cpub_mod_list[2],       DS_CHANGES, cpub_mod2);
OMX_OBJECT_DESC(    cpub_mod_list[3],       DS_CHANGES, cpub_mod3);
OMX_OBJECT_DESC(    cpub_mod_list[4],       DS_CHANGES, cpub_mod4);
OMX_OM_NULL_DESC(   cpub_mod_list[5]);
{
    DS_status         status;
    OM_sint           invoke_id;
    OM_uint           completion_flag;
    DS_status         operation_status;
    OM_return_code    om_status;
    OM_private_object changes, modify_entry_result;
    /* create an OM Private object called changes*/  
    om_status = om_create(DS_C_ENTRY_MOD_LIST, OM_FALSE, workspace,
                          &changes);
    /* now put the contents of the public object, cpub_mod_list, */
    /* in to the changes private object                          */  
    om_status = om_put(changes, OM_REPLACE_ALL, cpub_mod_list,
                       0, 0, 0);
    /* Call the Modify Entry function using the changes object as */
    /* a parameter                                                */
    status = ds_modify_entry(bound_session, context, name, changes,
                             &invoke_id); 
  

    if (status == DS_SUCCESS)
    {
        printf("MODIFY ENTRY was successful\n");
    }
    else
    {
        printf("MODIFY ENTRY 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,
                                   &modify_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 shows the following:

• How to define an Entry-Modification-List OM public object (cpub_mod_list) containing the modifications to be made.

• How to use the OM Create function to create an Entry-Modification-List OM private object (changes) and how to use the OM Put function to copy the modifications from the public object (cpub_mod_list) into the newly created private object (changes).

  Both the OM Create and the OM Put functions are assumed to succeed.

• How to obtain the result of the Modify Entry function using the Receive Result function.

OM_private_object bound_session, context, name;
{
    DS_status         status;
    OM_private_object changes;
    status = ds_modify_entry(bound_session, DS_DEFAULT_CONTEXT,
                             name, changes, NULL);
    if (status == DS_SUCCESS)
    {
        printf("MODIFY_ENTRY was successful\n");
    }
    else
    {
        printf("MODIFY_ENTRY failed\n");
    }
}

The above example shows how to perform a synchronous Modify Entry operation. Note that the Invoke-ID argument is not needed so NULL is used.

This example assumes that the Changes argument has been defined as shown in Example 1.

ds_modify_rdn(3xds)

ds_modify_rdn - Changes the Relative Distinguished Name (RDN) of an entry.

Syntax

Status = ds_modify_rdn(Session, Context, Name, New-RDN, Delete-Old-RDN, Invoke-ID)

Argument	Data Type	Access
Session	OM_private_object	read
Context	OM_private_object	read
Name	OM_object	read
New-RDN	OM_object	read
Delete-Old-RDN	OM_boolean	read
Invoke-ID	Integer	write
Status	DS_status

C Binding

DS_status ds_modify_rdn(session, context, name, new_rdn, delete_old_rdn, invoke_id_return)

OM_private_object	session
OM_private_object	context
OM_object	name
OM_object	new_rdn
OM_boolean	delete_old_rdn
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. This argument must be a Context OM private object or the constant Default-Context.

Name

A Name OM object containing the current name of the target entry. Any aliases in the name will be dereferenced if the DSA attribute Dereference Alias on Modify is set and the Dont Deference Aliases service control is not set.

New-RDN

A Relative-Name OM object specifying the new RDN. If an attribute value in the new RDN does not already exist in the entry, either as part of the old RDN or as a non-distinguished value, then the new value is added.

Delete-Old-RDN

When this takes the value false the old values will remain, but not as part of the RDN. When this takes the value true, all attribute values in the old RDN that are not also in the new RDN are deleted. If the operation removes the last value of an attribute, the attribute is deleted. This argument must be true when the value of a single-valued attribute is changed.

Invoke-ID

The Invoke-ID of an asynchronous directory operation.

Description

This function is used to change the RDN of a leaf entry. This can be either an object entry or an alias entry.

DCE Notes

CDS does not support the Modify RDN function; it returns with the Service-Error unwilling-to-perform.

Return Value

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:

• Library-Error, with Problem attribute values of bad-argument, bad-context, bad-name, bad-session, miscellaneous, missing-type,or too-many-operations
  
• Attribute-Error
  
• Name-Error
  
• Referral
  
• Security-Error
  
• Service-Error
  
• Update-Error
  
• Communications-Error
  

The Update-Error affects-multiple-DSAs that is referred to in the argument descriptions need not be returned if there is local agreement between the DSAs to allow the entry to be modified.

Example

The following code extract shows an example call to the Modify RDN function:

OM_private_object  bound_session, context, name, new_rdn;
OM_sint            invoke_id;
OM_boolean         delete_old_rdn;
{
    DS_status          status;
    status = ds_modify_rdn(bound_session, DS_DEFAULT_CONTEXT, name,
                           new_rdn, delete_old_rdn, NULL);
    if (status == DS_SUCCESS)
    {
      printf("MODIFY RDN was successful\n");
    }
    else
    {
      printf("MODIFY RDN failed\n");
    }
    return status;}

ds_read - Queries information in a particular entry.

Syntax

Status = ds_read(Session, Context, Name, Selection, Result, Invoke-ID)

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

C Binding

DS_status ds_read (session, context, name, selection, result_return, invoke_id_return)

OM_private_object	session
OM_private_object	context
OM_object	name
OM_object	selection
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 to be used.

Context

The directory context to be used for this operation. The Size-Limit Context parameter does 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 be dereferenced unless prohibited by the Context parameter Dont-Dereference-Aliases.

Selection

An Entry-Information-Selection OM object or a constant specifying what information from the named entry is requested. Information about no attributes, all attributes, or just a named set can be chosen. Attribute types are always returned, but the attribute values need not be. The following constants can be used:

• Select-No-Attributes, to verify the existence of an entry
  
• Select_All-Types, to return just the types of all attributes
  
• Select-All-Types-And-Values, to return the types and values of all attributes
  

Result

A Read-Result OM object, passed by reference, containing the distinguished name of the target object and a flag indicating whether the result came from the original entry or a copy. It also contains any requested attribute types and values. Attribute information is only returned if access rights are sufficient. No object is returned if the call does not complete successfully.

Invoke-ID

The Invoke-ID of an asynchronous directory operation.

Description

This function is used to extract information from an explicitly named entry. It can also be used to verify a distinguished name.

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

• Because CDS does not implement the X.500 schema rules, some CDS objects may not contain mandatory attributes such as 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 the Name-Error no-such-object.

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

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:

• Library-Error, with Problem attribute values of bad-argument, bad-attribute, bad-context, bad-name, bad-session, miscellaneous, missing-type, not-supported or too-many-operations

• Attribute-Error

• Name-Error, no-such-object

• Referral

• Security-Error

• Service-Error

• Communications-Error

• An Attribute-Error, no-such-attribute, is reported if an explicit list of attributes is specified by the selection argument but none of them are present in the entry. This error is not reported if any of the selected attributes are present.

• A Security-Error, insufficient-access-rights, is reported where access rights prohibit the reading of all requested attribute values.

The following code extracts show an example call to the Read function. The Read function is used to read all the types and values from all attributes of the directory entry identified in the Name argument.

There are three examples. The first example shows how to perform an asynchronous Read operation. The second example shows how to perform a synchronous Read operation. The third example shows how to perform a synchronous Read operation with a CDS name.

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.

Example 1

{
     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:

• How to define a private object containing a distinguished name.

• How to define a DS-DN OM public object (cpub_dn) containing the entry's distinguished name: /C=US/O=Digital Equipment Corporation/OU=Research/CN=Albert Einstein

• How to use the OM Create function to create a DS-DN OM private object (name) and how to use the OM Put function to copy the distinguished name from the public object (cpub_dn) into the newly created private object (name).

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

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

  The OM Create, OM Put and the OM Get functions are assumed to succeed.

OM_private_object bound_session, name, context;
{
     DS_status           status;
     OM_private_object   name;
     status = ds_read(bound_session, DS_DEFAULT_CONTEXT,
                      name, selection, &info, NULL);
 

     if (status == DS_SUCCESS)
     {
        printf("READ was successful\n");
     }
     else
     {
        printf("READ failed\n");
     }
}

The above example shows how to perform a synchronous Read 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.

Example 3

{
     OM_workspace      workspace;
     OM_descriptor     cpub_dn[7];
     OM_descriptor     cpub_rdn0[3];
     OM_descriptor     cpub_rdn1[3];
     OM_descriptor     cpub_rdn2[3];
     OM_descriptor     cpub_rdn3[3];
     OM_descriptor     cpub_rdn4[3];
     OM_descriptor     cpub_ava0[4];
     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_ava0[0], DS_C_AVA);
     OMX_ATTR_TYPE_DESC( cpub_ava0[1], DS_ATTRIBUTE_TYPE,
                                       DSX_TYPELESS_RDN);
     OMX_ZSTRING_DESC(   cpub_ava0[2], OM_S_PRINTABLE_STRING,
                                       DS_ATTRIBUTE_VALUES,
                                       "CDS");
     OMX_OM_NULL_DESC(   cpub_ava0[3]);
     OMX_CLASS_DESC(     cpub_ava1[0], DS_C_AVA);
     OMX_ATTR_TYPE_DESC( cpub_ava1[1], DS_ATTRIBUTE_TYPE,
                                       DSX_TYPELESS_RDN);
     OMX_ZSTRING_DESC(   cpub_ava1[2], OM_S_PRINTABLE_STRING,
                                       DS_ATTRIBUTE_VALUES,
                                       "Projects");
     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_rdn0[0],       DS_C_DS_RDN);
     OMX_OBJECT_DESC(    cpub_rdn0[1],       DS_AVAS, cpub_ava0);
     OMX_OM_NULL_DESC(   cpub_rdn0[2]);
     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_OBJECT_DESC(    cpub_dn[5],         DS_RDNS, cpub_rdn0);
     OMX_OM_NULL_DESC(   cpub_dn[6]);
     /* 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 */
     /* specify that all attribute types and values be read.    */
     /* Note that invoke_id parameter is may be set NULL in the */
     /* case of synchronous operation.                          */
     status = ds_read(bound_session, DS_DEFAULT_CONTEXT, name,
                      DS_SELECT_ALL_TYPES_AND_VALUES, &read_result,
                      NULL);
 

     if (status == DS_SUCCESS)
     {
        printf("READ request was successful\n");
        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
     {
        printf("READ request failed\n");
     }
}

The above example shows the synchronous reading of all attribute types and values from the CDS entry /.../C=US/O=Digital Equipment Corporation/OU=Research/Projects/CDS

Note the use of the special attribute type DSX_TYPELESS_RDN in the rightmost RDNs of the name. The presence of one or more occurrences of this attribute type indicates to the XDS API that a name is a CDS distinguished name.

Note that the CDS global naming root /... need not be explicitly supplied as the first RDN in a CDS distinguished name. When the XDS API encounters a CDS distinguished name, it will internally prepend the CDS global naming root, unless one of the CDS local naming roots such as /.: or /: has been explicitly supplied.

A CDS local naming root, if desired, must be explicitly supplied as the first RDN of a distinguished name. It is specified with an attribute type of DSX_TYPELESS_RDN and an attribute value of .: or : as appropriate.

Note that the Invoke-ID argument is not needed for synchronous operation and is therefore set to NULL. The Bound-Session argument is assumed to have been set up as in Example 1.

ds_receive_result(3xds)

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	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)

OM_private_object	session
OM_uint	completion_flag_return
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:

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

• Outstanding-Operations. There are outstanding asynchronous operations but none is 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

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.

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

ds_remove_entry - 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)

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.

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 Remove Entry 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.

• In CDS, the name parameter supplied to the Remove Entry function must ultimately resolve to the name of a leaf (that is, a CDS Object) entry; otherwise, the Name-Error no-such-object is returned. The function never interprets the name parameter as the name of a CDS Directory entry.

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:

• 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, no-such-object
  
• Referral
  
• Security-Error
  
• Service-Error
  
• Update-Error
  
• Communications-Error
  

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.

Example 1

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.

Example 2

OM_private_object bound_session, context, name;
{
    DS_status         status;
    OM_private_object changes;
    status = ds_remove_entry(bound_session, DS_DEFAULT_CONTEXT,
                             name, changes, NULL);
    if (status == DS_SUCCESS)
    {
        printf("REMOVE_ENTRY was successful\n");
    }
    else
    {
        printf("REMOVE_ENTRY failed\n");
    }
    return status;
}

ds_search - Finds entries of interest in a portion of the Directory.

Syntax

Status = ds_search(Session, Context, Name, Subset, Filter, Search_Aliases, Selection, Result, Invoke-ID)

Argument	Data Type	Access
Session	OM_private_object	read
Context	OM_private_object	read
Name	OM_object	read
Subset	Integer	read
Filter	OM_object	read
Search_Aliases	OM_boolean	read
Selection	OM_object	read
Result	OM_private_object	write
Status	DS_status	write
Invoke-ID	Integer

C Binding

DS_status ds_search(session, context, name, subset, filter, search_aliases, selection, result_return, invoke_id_return)

OM_private_object	session
OM_private_object	context
OM_object	name
OM_sint	subset
OM_object	filter
OM_boolean	search_aliases
OM_object	selection
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 to be used.

Context

The Context parameters 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 containing the name of the target entry, which forms the base of the search. Any aliases in the name will be dereferenced unless prohibited by the Dont-Dereference-Aliases Context parameter.

Subset

The search limit that specifies a portion of the Directory tom be searched. Its value must be one of:

• base-object, meaning search just the target entry
  
• one-level, meaning search just the immediate subordinates of the target entry
  
• whole-subtree, meaning search the target entry and all its subordinates
  

Filter

The filter is used to prevent unwanted entries being returned in the results of the search. Information is only returned on entries that satisfy the filter. The constant No-Filter can be used as the value of this argument if you want to search all entries. This corresponds to a filter with a value of and for the attribute Filter-Type, and no values of the attributes Filters or Filter-Items.

Search-Aliases

Any aliases in the subordinate entries being searched are dereferenced if the value of this argument is true. They are not dereferenced if its value is false. Note that Digital's X.500 DSA does not honor this control; it assumes the value is false and does not dereference aliases.

Selection

An Entry-Information-Selection OM object or a constant specifying what information from the named entry is requested. Information about no attributes, all attributes, or just a named set can be chosen. Attribute types are always returned, but the attribute values need not be. The following constants can be used:

• Select-No-Attributes, to verify the existence of an entry
  
• Select_All-Types, to return just the types of all attributes
  
• Select-All-Types-And-Values, to return the types and values of all attributes
  

Result

A Search-Result OM private object, passed by reference, containing the requested information from each object in the search space that satisfied the filter. The distinguished name of the target object is present if an alias was dereferenced. Additionally there may be a partial outcome qualifier that indicates the result is incomplete. It also explains why it is not complete and how it could be completed.

Invoke-ID

The Invoke-ID of an asynchronous operation.

Description

This function is used to search a portion of the directory and return selected information from the entries of interest. It is possible that the information will be incomplete in some circumstances.

DCE Notes

CDS does not support the Search function. It returns with the Service-Error unwilling-to-perform.

Return Value

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:

• Library-Error, with Problem attribute values of bad-argument, bad-context, bad-name, bad-session, miscellaneous, missing-type,or too-many-operations
  
• Attribute-Error
  
• Name-Error
  
• Referral
  
• Security-Error
  
• Service-Error
  
• Communications-Error
  

An unfiltered search of just the base object succeeds even if none of the requested attributes is found while Read fails with the same selected attributes.

A Security-Error, insufficient-access-rights, is only reported where access rights prohibit the reading of all requested attribute values.

Examples

The following code extract shows an example call to the Search function. The Search function is used to search the directory for a specific entry and then extract the values of the Surname and the Title attributes from that entry.

There are two examples. The first example shows how to perform an asynchronous Search operation. The second example shows how to perform a synchronous Search 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 are shown in the Read function. An example of how to define a Context argument is shown in the Add Entry function.

Example 1

{
    OM_private_object bound_session, context, name;
    OM_workspace      workspace;
    OM_descriptor     cpub_eis[5];
    OM_value_position desc_count;
    DS_status         status;
    OM_private_object search_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;
    OM_private_object selection;
    /* create a descriptor list for surname and title of class */
    /* entry information selection                             */
    OMX_CLASS_DESC(       cpub_eis[0], DS_C_ENTRY_INFO_SELECTION);
    OMX_ATTR_TYPE_DESC(   cpub_eis[1], DS_ATTRIBUTES_SELECTED,
                                       DS_A_SURNAME);
    OMX_ATTR_TYPE_DESC(   cpub_eis[2], DS_ATTRIBUTES_SELECTED,
                                       DS_A_TITLE);
    OMX_ENUM_DESC(        cpub_eis[3], DS_INFO_TYPE,
                                       DS_TYPES_ONLY);
    OMX_OM_NULL_DESC(     cpub_eis[4]);
    /* Create an OM private object called selection */
    om_status = om_create(DS_C_ENTRY_INFO_SELECTION,OM_FALSE,
                          workspace, &selection);
    /* Object created, now put in the attributes from cpub_eis */
    om_status = om_put(selection, OM_REPLACE_ALL, cpub_eis ,0,0,0);
    /* now start the search using selection as a parameter*/
    status = ds_search(bound_session, context, name, DS_ONE_LEVEL,
                       DS_NO_FILTER, OM_FALSE, selection,
                       &search_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, &search_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(search_result, OM_NO_EXCLUSIONS,
                                   0, 0, 0, OM_ALL_VALUES,
                                   &spub_result, &desc_count);
                if (om_status == OM_SUCCESS)
                {
                   /* results now available as a public object */
                   /* check desc_count != 0 */
                   /* delete the search result... */
                   om_status = om_delete(search_result);
                }
                else
                {
                   /* error getting results */
                   /* search_result not deleted */
                }
            }
            else
            {...}
            break;
            case DS_COMPLETED_OPERATION:
            ...
            break;
            case DS_COMPLETED_OPERATION:
            ...
            break;
        }
    }
}

The above example shows the following:

• How to define an Entry-Information-Selection OM public object (cpub_eis) containing details of the information that is to be returned from the search.

• How to use the OM Create function to create a private object (selection) and how to use the OM Put function to copy the details of the required information from the Entry-Information-Selection OM public object (cpub_eis) into the newly-created Entry-Information-Selection OM private object (selection).

• How to obtain the result of the Search function using the Receive Result function.

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

The OM Create, OM Put, OM Get and OM Delete functions are assumed to succeed.

Example 2

{
    OM_private_object bound_session, context, name;
    OM_value_position desc_count;
    DS_status         status;
    OM_private_object search_result;
    OM_private_object selection;
    OM_public_object  spub_result;
    /* start the search using selection as a parameter */
    status = ds_search(bound_session, DS_DEFAULT_CONTEXT, name,
                       DS_ONE_LEVEL, DS_NO_FILTER, OM_FALSE,
                       selection, &search_result, NULL);
    if (status == DS_SUCCESS)
    {
        /* now see what we have got back ... */
        om_status = om_get(search_result, OM_NO_EXCLUSIONS,
                           0, 0, 0, OM_ALL_VALUES,
                           &spub_result, &desc_count);
        if (om_status == OM_SUCCESS)
        {
            /* results now available as a public object */
            /* check desc_count != 0 */
            /* delete the search result... */
            om_status = om_delete(search_result);
        }
        else
        {
            /* error getting results */
            /* search_result not deleted */
        }
    }
    else
    {...}
}

The above example shows how to perform a synchronous Search operation. Note that the Invoke-ID argument is not needed and NULL is used. This example assumes that the Selection argument has been defined as shown in Example 1.

ds_shutdown(3xds)

ds_shutdown - Shuts down the interface and closes the workspace.

Syntax

Status = ds_shutdown(Workspace)

Argument	Data Type	Access
Workspace	OM_workspace	read
Status	DS_status

C Binding

DS_status ds_shutdown(workspace)

OM_workspace

workspace

Arguments

Workspace

Specifies the workspace (obtained from a call to the Initialize function) that is to be deleted.

Description

This function shuts down the interface previously established by Initialize and enables the service to release resources.

After this function has been called, no OM objects or other data values associated with the workspace are valid, with the exception of client-generated public objects. You should call the Unbind function for all sessions in this workspace. You must not subsequently call any X.500 API functions that operate on OM objects in this workspace.

In order to ensure that resources are freed, applications should release all private objects by calling the OM Delete function for all top-level OM private objects before calling this function. This is not necessary for subobjects. Applications should also release all service-generated public objects by calling the OM Delete function. You can do this either before or after the calling of this function.

Return Value

Errors

This function does not return any error objects.

Example

The following code extract shows an example call to the Shutdown function:

OM_workspace workspace;
{
  DS_status    status;
  /* Finally, close down the workspace */
  ds_status = ds_shutdown(workspace); 
}

The Shutdown function closes down the workspace identified in the Workspace argument. The workspace identity is obtained from the Initialize function.

ds_unbind(3xds)

ds_unbind - This function closes a directory session.

Syntax

Status = ds_unbind(Session)

Argument	Data Type	Access
Session	OM_private_object	read
Status	DS_status

C Binding

DS_status ds_unbind(session)

OM_private_object

session

Arguments

Session

The directory session that is to be unbound. This argument must be the Session OM private object that was returned by the Bind function, identifying the directory session. If the function succeeds, the value of the File-Descriptor OM attribute is No-Valid-File-Descriptor. The other OM attributes are unchanged.

Description

This function terminates the given directory session and makes the argument unavailable for use with all other interface functions except Bind.

The results of any outstanding asynchronous operations that were initiated using the given Session can no longer be received, and it is not possible to find out if they succeeded. It is therefore recommended that you obtain the results of all outstanding asynchronous operations by calling the Receive-Result function before calling Unbind.

It is possible to use the unbound session again as an argument to Bind, perhaps after modification by the Object Management functions.

Return Value

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:

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

The following code extract shows an example call to the Unbind function.

{
  OM_private_object bound_session;
  DS_status         status;
  

  status = ds_unbind(bound_session); 
  if (status == DS_SUCCESS)
  {
      printf("UNBIND was successful\n");
  }
  else
  {
      printf("UNBIND failed\n");
  }  
}

The Unbind function closes down a session established by the Bind function. The Bound_Session argument identifies the session to be closed.

ds_version(3xds)

ds_version - Negotiates the features of the interface and service.

Syntax

Status = ds_version(Feature-List, Workspace)

Argument	Data Type	Access
Feature-List	DS_Feature	write/read
Workspace	OM_workspace	read
Status	DS_status

C Binding

DS_status ds_version(feature_list, workspace)

DS_feature	feature_list[]
OM_workspace	workspace

Arguments

Feature-List

An ordered sequence of features, each represented by an object identifier. The sequence is terminated by an object identifier having no components (that is, a length of zero, and any value of the data pointer in the C representation).

Workspace

Specifies the workspace (obtained from a call to the Initialize function) for which the features are to be negotiated. The features will be in effect for operations that use the workspace or directory sessions associated with the workspace.

Description

This function negotiates features of the interface that are represented by object identifiers. Features are negotiated after a workspace has been initialized.

Negotiable features include the Basic-Directory-Contents Package, the Strong-Authentication Package, and the MHS Directory User Package.

The Gradient DCE for Tru64 UNIX implementation of this function does not support the features listed above, but supports one extension, DSX-RET-X500-BIND-ERR-FTR. This feature guarantees that the Bind function will always return an error if it fails to connect to an X.500 directory. This feature is useful if the system where your application runs is capable of simultaneous connections to both CDS and X.500 directories in the same XDS session. In other circumstances, this feature is not needed.

Return Value

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:

• Library-Error, with the Problem attribute values of miscellaneous, bad_workspace.
  
• System-Error
  

The following code extract shows an example call to the Version function.

{
    OM_workspace       workspace;
    DS_feature         feature_list[];
    DS_status          status;
    status = ds_version(feature_list, workspace);
    if (status == DS_SUCCESS)
    {
      printf("VERSION was successful\n");
    }
    else
    {
      printf("VERSION failed\n");
    }
}

dsX_trace_object - Displays an explanation of the content of an object on the current output device.

Syntax

(void) dsX_trace_object(Object)

Argument	Data Type	Access
Object	OM_object	read

C Binding

dsX_trace_object(object)

OM_object

object

Arguments

OM_object

The object whose content you want to inspect.

Description

This function displays on the current output device information about the content of an OM object, as follows:

• A full expansion of a public object
  
• The type of a private object
  
• Details of the content of an error object
  
• For a name object or AVA encoded in ASN.1, both the ASCII and hexadecimal representations of the ASN.1 encoding
  

The routine also checks for null pointers.

Errors

This function does not return any errors.

Example

The following code extract shows an example call to the Trace Object function:

{
  OM_workspace workspace;
  OM_return_code status;
  OM_object session = NULL;
 

  status = om_create(DS_C_SESSION,OM_TRUE,workspace,&session);
  if (status == OM_SUCCESS)
    {
      dsX_trace_object(session);
    }  
}

[Previous] [Next] [Contents]

To make comments or ask for help, contact support@entegrity.com.

Copyright © 2001 Entegrity Solutions Corporation & its subsidiaries.

Copyright © 1998-2001 Compaq Computer Corporation.

All rights reserved.