When you are preparing to write an application, you need to consider which of the functions must be used by all applications, and which suit the needs of your application. The functions are divided into three categories:

The administration functions are concerned with the opening and closing of communications between the application, the X.500 API, and the X.500 Directory Service. The administration functions are:

All administration functions, except for the Version function, are needed to open and close a session between the application and the X.500 API.

The interrogation functions are:

The modification functions are:

Two further functions are provided for asynchronous operations; these are:

See Chapter 2, Application Task Descriptions for details of these functions and how to use them.

You need a complete understanding of the purpose of your application in order to understand whether, for example, it needs to use the Compare function. Some applications use the interrogation functions, others use the modification functions, and many use a combination of both.

You need to consider how to use the functions provided by the X.500 API to satisfy the requirements of your application.

When you are planning to use interrogation functions, you need to consider the following points:

When you are planning to use modification functions, you need to consider the following:

Each call to an X.500 API function invokes a corresponding directory operation. The parameters and parameter values that you pass to the function determine how the function processes that operation. Consider how to use these parameters to make these operations as effective and efficient as possible, obtaining the required results with the minimum use of resources. Section 1.4, “Controlling Directory Operations” explains how to achieve this using the Context object.

An application may need one or both of the following categories of data:

You need to consider the different storage requirements for both categories of data. Either category can be stored by the application to be passed into the X.500 API.

The structure of static data is determined when you compile the application. This structure cannot be altered when you run the application. The way the data is to be stored, and the amount of storage it requires, is determined when you compile the application. The only changes that can be made are to the data values.

The structure of dynamic data must be defined when you compile the application but is not fixed. The way the data is stored, and the amount of storage it requires can alter while the application is running. Therefore, the dynamic nature of the data structure must be planned for. Typically, this type of data is used most often in an interactive application, hence these considerations would be involved in the design of a user interface.

Data is exchanged between the application and the X.500 API using objects defined by Object Management (OM). The OM objects and attributes represent the service elements and parameters used in the DAP protocol.

The information that an OM object contains is defined by the value of the Object Class attribute. The type of an OM object defines how it can be manipulated.

The following types of object are defined by OM:

These objects are described in Section 1.3.2, “Private and Public Objects ”.

A private object has a format that is known only to the X.500 API and not to an application. To create a private object, you use the OM functions. You therefore build a private object dynamically, when the application is run; you cannot declare it statically.

Private objects are created and maintained by the X.500 API in a workspace. A workspace is an area of memory that is a repository for private objects. The workspace has object class packages associated with it to enable classes within the packages to be created. A package is a group of OM classes that are functionally related.

You manipulate private objects using OM functions, which are described briefly in Section 2.2, “Creating and Manipulating Objects”. See OSI-Abstract-Data Manipulation for further information on private objects, public objects, and the OM functions.

A public object consists of a data structure called a descriptor list, as described in Section 1.3.3, “Descriptor Structures”. The structure of a public object is known to an application. It contains a collection of attributes determined by the OM object class. Public objects are data structures that can be declared statically or built dynamically. See Section 2.2, “Creating and Manipulating Objects” for details of how to do this.

There are two types of public object:

When you call an X.500 API function, you can specify private or public objects for many of the parameters. Passing a private object to a function may be more efficient because if you pass a public object, the X.500 API must convert it to a private object before it can access the Directory. If you are passing the information to the X.500 API once and do not need to manipulate the object, then use a public object. If you need to manipulate the object, using the OM functions, then use a private object.

If the data must be built dynamically, then do either of the following:

The X.500 API defines data structures that are used by applications to store all the required data. You need to understand these data structures to plan data storage. These data structures are descriptors and descriptor lists.

A descriptor is a defined data structure that represents a single OM attribute. The structure has three components:

Section 1.3.3, “Descriptor Structures” shows how a descriptor is constructed. The example programs described in Section 1.9, “XDS Example Programs” illustrate how such structures can be used.

A descriptor list is an ordered sequence of descriptors that can represent several OM attribute types and values in a single OM object. Descriptor lists can store single-valued and multi-valued OM attributes.

A single-valued OM attribute is represented by a single descriptor in a descriptor list. A multi-valued OM attribute is represented by several descriptors with the same attribute type and syntax in a descriptor list. The descriptors representing the values of a multi-valued OM attribute are always adjacent in the descriptor list. The order of the values in the OM attribute is the same as the order in the descriptor list.

A single descriptor list can represent several single-valued and multi-valued OM attributes.

If a descriptor list contains a descriptor representing an OM class, then that must be the first descriptor in the descriptor list. A descriptor list is terminated with a null descriptor.

Figure 1.2, “Components of a Descriptor List” represents a descriptor list containing the following descriptors:

The following code is an example of coding a descriptor list to represent a distinguished name. The structure macros are defined in the file xom.h.

/**** Public Object ("Descriptor List") for NAME argument to READ*****/ 
 OM_descriptor name[] = 
 { 
 OM_OID_DESC(OM_CLASS, DS_C_DS_DN), 
 { DS_RDNS, OM_S_OBJECT, { 0, DIB_RDN_country_US } }, 
 { DS_RDNS, OM_S_OBJECT, { 0, DIB_RDN_org_name_ABACUS_CO } }, 
 { DS_RDNS, OM_S_OBJECT, { 0, DIB_RDN_locality_USA } }, 
 { DS_RDNS, OM_S_OBJECT, { 0, DIB_RDN_org_unit_SALES } },
 OM_NULL_DESCRIPTOR 
 }; 
 /**** Country ********************************************************/
 OM_descriptor DIB_country_US[] = 
 { 
 OM_OID_DESC(OM_CLASS, DS_C_AVA),
 OM_OID_DESC(DS_ATTRIBUTE_TYPE, DS_A_COUNTRY_NAME), 
 { DS_ATTRIBUTE_VALUES, OM_S_PRINTABLE_STRING, OM_STRING("US") },
 OM_NULL_DESCRIPTOR 
 }; 
 OM_descriptor DIB_RDN_country_US[] = 
 { 
 OM_OID_DESC(OM_CLASS, DS_C_DS_RDN), 
 { DS_AVAS, OM_S_OBJECT, { 0, DIB_country_US } },
 OM_NULL_DESCRIPTOR 
 }; 
 /**** Organizations ***************************************************/
 OM_descriptor DIB_org_name_ABACUS_CO[] = 
 { 
 OM_OID_DESC(OM_CLASS, DS_C_AVA),
 OM_OID_DESC(DS_ATTRIBUTE_TYPE, DS_A_ORG_NAME), 
 { DS_ATTRIBUTE_VALUES, OM_S_PRINTABLE_STRING, OM_STRING("ABACUS LTD.") },
 OM_NULL_DESCRIPTOR 
 }; 
 OM_descriptor DIB_RDN_org_name_ABACUS_CO[] = 
 { 
 OM_OID_DESC(OM_CLASS, DS_C_DS_RDN), 
 { DS_AVAS, OM_S_OBJECT, { 0, DIB_org_name_ABACUS_CO } },
 OM_NULL_DESCRIPTOR 
 }; 
 /**** Locality Names *************************************************/
 OM_descriptor DIB_locality_USA[] = 
 { 
 OM_OID_DESC(OM_CLASS, DS_C_AVA),
 OM_OID_DESC(DS_ATTRIBUTE_TYPE, DS_A_LOCALITY_NAME), 
 { DS_ATTRIBUTE_VALUES, OM_S_PRINTABLE_STRING, OM_STRING("USA") },
 OM_NULL_DESCRIPTOR 
 }; 
 OM_descriptor DIB_RDN_locality_USA[] = 
 { 
 OM_OID_DESC(OM_CLASS, DS_C_DS_RDN), 
 { DS_AVAS, OM_S_OBJECT, { 0, DIB_locality_USA } },
 OM_NULL_DESCRIPTOR 
 }; 
 /**** Organizational Units *******************************************/
 OM_descriptor DIB_org_unit_SALES[] = 
 { 
 OM_OID_DESC(OM_CLASS, DS_C_AVA),
 OM_OID_DESC(DS_ATTRIBUTE_TYPE, DS_A_ORG_UNIT_NAME), 
 { DS_ATTRIBUTE_VALUES, OM_S_PRINTABLE_STRING, OM_STRING("Sales") },
 OM_NULL_DESCRIPTOR 
 }; 
 OM_descriptor DIB_RDN_org_unit_SALES[] = 
 { 
 OM_OID_DESC(OM_CLASS, DS_C_DS_RDN), 
 { DS_AVAS, OM_S_OBJECT, { 0, DIB_org_unit_SALES } },
 OM_NULL_DESCRIPTOR 
 }; 

Figure 1.3, “Relationship Between Descriptors and Descriptor Lists” shows the relationship between the descriptor list and its descriptors.

When an object of a particular OM class is required, an instance of any subclass of that class can be supplied instead. This means that the application can supply a subclass to the X.500 API, and the X.500 API can return a subclass to the application. For example, the application can supply entry names in any format that is defined as a subclass of the OM class Name, and the X.500 API returns all errors as a subclass of the OM class Error. See DEC X.500 Directory Service Programming Reference for details of the classes and subclasses defined.

Applications should not check the OM class of an object by requesting the value of its OM attribute Class. Applications must always use the OM-Instance function, which inform s you whether an object is an instance of a particular OM class or any of its subclasses.

This section describes synchronous and asynchronous modes and explains what you need to consider when choosing between them. It also describes what extra planning is required for asynchronous operations.

The cost of some directory operations in both time and resources could become high if they are not limited in some way. Therefore, you can limit the amount of information returned by an operation or the amount of processing time devoted to it. For example, you may need to limit a search operation that could take a long time, return large amounts of data, or both.

When a DSA is sent a request by the X.500 API but does not hold the necessary information, it can do one of the following:

Chaining is the sending of a request by a DSA to another DSA. It is possible for a request to be chained to any DSA that is known to the DSA that chains the request. A request can be chained to one DSA or to several DSAs simultaneously. Also, a DSA that receives a chained request can chain it to other DSAs.

Figure 1.4, “Chaining to a Single DSA” shows a request chained to a single DSA. Figure 1.5, “Simultaneous Chaining to Multiple DSAs” shows a request chained to several DSAs simultaneously.

Use the Chaining-Prohibited parameter to control whether requests are permitted to be chained to other DSAs, or the operation can only return information from the portion of the DIB held by the DSA to which the request was originally sent. Set the Chaining-Prohibited parameter as follows:

Use the Prefer-Chaining parameter to specify whether or not you prefer a request to be chained, instead of a referral returned, when the DSA cannot satisfy it. Select your preference as follows:

You should not set both Prefer-Chaining and Chaining-Prohibited to true, but you can set both to false .

Use the Local-Scope parameter to specify whether or not requests can be chained outside of an implementation-defined local scope. The local scope will typically be the Directory Management Domain (DMD) or DSA in which the request originates. If possible, you should check the definition of the local scope parameter for the DSA that you are using. Set this parameter as follows:

A DSA defines local scope to be the DSA in which the request originates, effectively preventing chaining when the value of Local-Scope is true.

When a DSA holds none of the information required to satisfy a request, it can return a referr a l to the X.500 API. A referral contains the presentation addresses of one or more other DSAs that might be able to satisfy the request.

When a DSA holds some, but not all, of the information required to satisfy a request it returns a continuation reference. A continuation reference describes how the operation can be continued at one or more other DSAs. A single continuation reference returned as the entire response to an operation, with no partial results, is a referral. One or more continuation references can be included in a Partial-Outcome-Qualifier returned by a List or Search operation; see Section 1.4.8, “Specifying the Operation Start State” for more information about how a Partial-Outcome-Qualifier is used. See VSI X.500 Directory Service Programming Reference for details of the information contained in a continuation reference.

The X.500 API passes referrals on to your application.

1.4.4.1. Handling Continuation References or Referrals

Note

This version of the X.500 API does not provide the Automatic Continuation service. Regardless of the setting of the Automatic-Continuation parameter, your application must handle all referrals.

The Automatic-Continuation parameter controls whether referrals, including continuation references, are handled by the X.500 API, or by your application.

Figure 1.6, “A Referral Handled by the X.500 API” shows a referral handled by the X.500 API. Figure 1.7, “A Referral Handled by the Application” shows a referral handled by an application.

If the Automatic-Continuation parameter is set to true, the X.500 API processes all referrals and returns the final results to the application whenever practical. Use this default setting if the application does not need to deal with referrals, and you want to make the handling of referrals as simple as possible. However, the X.500 API might still return a referral to the application, for example, if it cannot contact the appropriate DSA. You need to plan what to do if this happens.

If the Automatic-Continuation parameter is set to false , your application must handle all referrals. Use this value if the application has special requirements that mean it is preferable for the application to deal with referrals; for example, if the user does not always want to call the function again when a Partial-Outcome-Qualifier is returned or does not want to follow a referral.

1.4.4.2. Referral Scope

Note

This version of the X.500 Directory Service does not honor the setting of the Scope-of-Referral service control but assumes that it is set to World .

The Scope-Of-Referral parameter limits the DSAs to which the X.500 Directory Service can refer you. Figure 1–9 shows the three possible scopes.

The Scope-Of-Referral parameter has one of the following values:

• DMD

  This indicates that you want referrals only to DSAs within the same directory management domain (DMD) as the DSA in which the request originates. Typically, a DMD would be an organization, so this value would ensure that you only receive referrals to other DSAs within your organization. Therefore, you specify this option to gain access to information held within your organization; for example, a search for all meeting rooms within a department that are available at a specified time.

• Country

  This indicates that you want referrals to DSAs within the same country as the DSA to which you originally sent the request, including your DMD. Specify this option to gain access to information held nationally but outside your DMD. This could be information held by another organization in your country. For example, a request for the telephone number of an organization.

  The country of a DSA is determined by the value of the CountryName attribute of the entry in the DIT that represents the DSA. The CountryName of a DSA identifies the country in which the DSA is located or with which it is associated. Therefore, a DSA located in one country could have a different country as the value of its CountryName attribute, for example, a DSA belonging to an international organization that has one country as its base.

• World

  This indicates that you want referrals to any DSA in any DMD in any country in the world, including your country. Specify this option to gain access to information held outside of your country. This could be information held by an organization that is based in another country, for example, the facsimile number of an organization in a different country.

An alias entry provides an alternative name for another entry and contains the Distinguished Name of that entry. This allows a single real-world object to be known by different names within the Directory, enabling different users to use the names familiar to them. See DEC X.500 Directory Service Management for more information about alias entries.

To discover the Distinguished Name of the entry to which an alias refers, the alias is interrogated by the Directory Service. The X.500 Directory Service uses the Distinguished Name to locate the entry to which the alias points and continues the operation with that entry. This is known as dereferencing an alias.

Use the Dont-Dereference-Alia ses service control to specify whether or not aliases that identify the target entry of operations are to be dereferenced. This is set as follows:

This service control does not apply to Add, Modify and Delete operations. The Search_Aliases parameter of the Search function further controls whether aliases are dereferenced in searches; see Section 2.5.4.5, “Specifying Whether to Search Aliases” for information about the how aliases are handled in Search operations.

The X.500 Directory Service does not guarantee to keep copy entries consistent with each other, or with the original entry. Therefore, if you use copy entries, then you must be prepared to receive out-of-d ate data, and it must be dealt with in an appropriate way by your application.

Allow copies to be accessed if one of the following applies:

Do not allow copies to be used if the information you require must be accurate and up to date, and you know that the original entry is the most accurate and up to date version.

Use the Dont-Use-Copy parameter to specify whether or not requests must be satisfied by accessing original entries, as follows:

You need know the frequency with which the DSA updates its copy entries before you decide whether to use copy entries. Note that modification requests always use the original entry; copy entries are only useful for interrogations.

VSI X.500 Directory Service does not currently recognize the priority settings. All requests sent to a Digital DSA are treated with equal priority.

The Priority parameter specifies the level of priority assigned to a request when it is sent to the Directory. This priority is relative to other requests and the possible values are:

The default value for the Priority parameter is Medium .

This service is not guaranteed because there is no Directory-wide system to do this. Therefore, the priority that your request receives depends upon the DSA that the request is sent to. To use the Priority parameter, you need to understand how different implementations deal with the priority settings.

When you call an X.500 API function, it invokes a directory operation. It is possible that a previous request to perform the operation returned partial results in a Partial-Outcome-Qualifier; therefore, you need to invoke the operation again to obtain further results. The X.500 API provides the means of specifying whether the request is already partly processed. Use the Operation- Progress parameter to specify the state the operation has reached. The possible values are:

The default value is the constant DS_OPERATION_NOT_STARTED.

This parameter normally takes the default value but there are circumstances in which you would choose to use another value, for example, to deal with operations that return a Partial-Outcome-Qualifier.

If you want to use the system default values for all the parameters in an OM Context object, you can supply the constant DS_DEFAULT_CONTEXT instead of an object.

You can also use the information in the DUA defaults file to override the system default values. When you create an OM Context object, the object is initialized with the values from the DUA defaults file, or with the system default values if a value is not specified in the DUA defaults file.

Similarly, you can specify the constant DS_DEFAULT_S ESSION in place of an OM Session object, or you can use the information in the DUA defaults file to control directory session characteristics. See Section 2.1.2, “ Opening a Directory Session ” for more information.

VSI X.500 API provides security based upon access controls defined for portions of the DIT. Access controls are used to prevent users accessing data or applications that they are not authorized to access.

Groups of users with particular access rights are identified by their X.500 Distinguished Names.

In response to Read operations, your application must be able to handle responses that contain information that is incomplete due to the access controls on the data. On other operations, it must be able to handle errors caused by access controls.

You need to consider two types of authentication:

See DEC X.500 Directory Service Management for information about authentication.

The first task of an application is to initialize the X.500 API by calling the Initialize function. This function must be called before any other X.500 API functions are called.

The Initialize function establishes the workspace that your application uses during its communication with the Directory. This workspace supports the standard Directory Service Package (the xds.h header file). Therefore, it supports the objects described in VSI X.500 Directory Service Programming Reference. It does not support other packages or extensions that affect the behavior of those applications that use only the standard features. For details of negotiating other features of the workspace, see Section 2.1.4, “Negotiating the Version of Interface and Service”.

The Initialize function has no arguments.

Call the Bind function to open a session with the Directory and to specify the Directory System Agent (DSA) that you want your application to communicate with. The Bind function has two arguments: Session and Workspace:

An application must use the Bind function before it can use any of the interrogation or modification functions. Therefore, the Bind function must be called at least once, after the Initialize function but before any other function calls.

It is possible for an application to call the Bind function many times between calling the Initialize function and calling the Shutdown function. The interface supports multiple concurrent sessions within the same Directory communication. This allows you to:

You are bound to a DSA and therefore able to communicate with it, until you pass the Session object that identifies that DSA as the argument to the Unbind function. See Section 2.1.5, “Closing a Directory Session” for details of closing a Directory session.

Note that the VSI implementation will attempt to rebind to the DSA if the DSA becomes unavailable once bind has been called. If the DSA cannot be contacted, an error is returned.

Most of the X.500 API routines have a Context argument. The Context object contains settings of the service controls that apply to the Directory operation. You can use the DUA defaults file to set default values for service controls. See DEC X.500 Directory Service Management for more information about the DUA defaults file.

Call the Version function to negotiate certain features of the workspace returned by the Initialize function. Negotiate these features after the interface has been initialized. The only negotiable feature of the workspace is support of objects defined in the Basic Directory Contents Package, the Strong Authentication Package and the MHS Directory User Package respectively.

See Section 3.2.1, “Header Files”, and the DEC X.500 Directory Service Programming Reference for details of these packages.

The Version function has two arguments: Feature-list and Workspace. Feature-list is a list of object identifiers. Each object identifier represents a feature of the workspace, and is shown in the following list:

For details of what the header files contain, see the DEC X.500 Directory Service Programming Reference. Note that the VSI implementation does not support these.

The Workspace argument specifies the workspace for which the features are to be negotiated. See the description of the Bind function in DEC X.500 Directory Service Programming Reference for information about other negotiable features.

Call the Unbind function to end a session with the Directory Service. This function has one argument, the Session object identifying the session that you want closed.

If any asynchronous operations were initiated during the session, you must first ensure that they all have their results returned by the Receive-Result function, or are terminated by the Abandon function before you close the session.

A Session object that identifies a closed session cannot be used as the argument to any function except Bind. You can use the Session object of a closed session as the argument to the Bind function to reopen the session.

Call the Shutdown function to shut down a workspace previously set up by the Initialize function. This allows the Directory Service to release resources such as memory. After calling this function, an application cannot call any other interface functions until it has called the Initialize function to establish a workspace. The Shutdown function also deletes any service-generated OM objects, so you must ensure that they are no longer required by your application before calling the function.

The Shutdown function has one argument, workspace, which specifies the workspace that is to be deleted.

You should ensure that all open sessions are closed by calling the Unbind function before you call the Shutdown function to ensure that all resources are released.

The X.500 API supports multiple concurrent sessions; therefore, you can be bound to, and communicate with, many DSAs concurrently. See Section 2.1.2, “ Opening a Directory Session ” for details of binding to a DSA.

The first parameter of most API functions, except Initialize, Version and Shutdown, is a Session object that identifies the DSA that is to be used to service the request. Therefore, you can use different DSAs for any individual operations by passing different Session objects to the function that invokes the operation.

You can only pass a Session object that identifies a DSA to which you are bound. Therefore, you need to bind to the DSA that you want to use (the target DSA) if you have not already done so, or if you have bound to it and have subsequently closed the session by calling the Unbind function.

Call the Receive-Result function to access the results of an outstanding asynchronous operation.

When you call the Receive-Result function, you must specify the session in whose outstanding operations you are interested. This indicates the DSA to which the requests were originally sent. You specify this as the Session parameter of the Receive-Result function.

The Receive-Result function can return results from any outstanding asynchronous operation. Therefore, to identify the asynchronous operation to which these results relate, it also returns the Invoke-ID of that operation.

A call to the Receive-Result function returns four values, as follows:

If at least one outstanding asynchronous operation has completed, the following are also returned:

If there are outstanding asynchronous operations, but none have completed, the Completion-Flag parameter value of DS_OUTSTANDING_OPERATIONS is returned.

If there are no outstanding operations, the Completion-Flag parameter value of DS_NO_OUTSTANDING_OPERATION is returned.

Any results returned in the Result parameter are in the form of an OM object, and of a class appropriate to the results. This is a private object; therefore, you need to use the OM functions to determine its class and contents.

Call the Abandon function to tell the Directory Service that the application is no longer interested in the results of an operation. The results can never be accessed once they have been abandoned, even if the Receive-Result function is called.

The Abandon function applies only to interrogations. The interface does not allow applications to abandon modifications.

However, calling the Abandon function does not guarantee that an abandon operation is requested of the X.500 Directory Service. If an abandon operation is invoked, the X.500 Directory Service does not necessarily abandon the outstanding asynchronous operation itself. How a DSA behaves when it receives an abandon request is implementation-defined.

Specify the session as the Session parameter of the Abandon function that was the target of the operation to be abandoned. Specify the Invoke-ID of the operation that you want to abandon as the Invoke-ID parameter of the Abandon function.

Note that even if the Abandon function returns an error, the result of the asynchronous operation is not returned.

Asynchronous operations are ideal for applications which need to continue to work while waiting on the results of a previously issued operation. An example of this is the Motif version of the DXIM utility, which is a single-threaded windowing application in which other parts of the application can still be used while waiting for results of an operation.

Call the Read function to look at a specified entry. You can specify the combination of the entry’s attributes and attribute values that you want to see.

See Section 1.9, “XDS Example Programs” for information about an example program that reads information from the directory.

Call the List function to list the RDNs of all the immediate subordinate entries of a specified entry. For example, if you are developing a directory browsing utility, then you could use the List function to allow the user to look for entries one level down in the DIT. This allows the user to find an entry when they do not know the Distinguished Name but can locate the area of the Directory where the entry exists. The List function returns only the RDN of an entry and not the full Distinguished Name as is the case with the Search function (see Section 2.5.4, “Searching for an Entry”).

The Compare function allows you to specify an entry and see whether one of its attributes has a specified attribute type and value. The Directory Service responds to this function by returning true or false .

Use this function to verify the value of an attribute, and to confirm that an entry has an attribute of a given type with the specified value. This is particularly useful to verify the value of attributes that contain information that is protected by access controls. For example, you could use the Compare function to verify user passwords. This function does not return the attribute value, so you can only use it to verify the password provided.

Call the Search function to search for entries of interest. You must specify an area of the DIT in which to search for any entries that have attributes and attribute values that match a filter. The filter is evaluated against every entry within the specified area. You can also specify the information that you want returned about entries that match the filter.

See Section 1.9, “XDS Example Programs” for information about the example programs supplied with the Digital X.500 API. The file XDS_SEARCH_EXAMPLE_1.C (OpenVMS) or xds_search_example_1.c (ULTRIX and DEC OSF/1) contains an example of a program that searches for information in the directory.

2.5.4.2. Specifying the Depth of the Search

You must specify how much of the Directory you want to search. You can choose one of three depths of search, as shown in Figure 2.1, “Depths of Search”.

Specify the depth of the search by passing one of the following three constants as the value of the Subset parameter:

• DS_BASE_OBJ ECT. Use this value to search only the target entry that you specified in the Name parameter.

• DS_ONE_LEVEL. Use this value to search the immediate subordinate entries of the specified target entry.

• DS_WHOLE_SUBTREE. Use this value to search the specified target entry and all its subordinate entries.

2.5.4.3. Omitting Entries from the Search

You can use the Filter parameter specify the entry you are looking for and reduce the size of the search results. For example, when you are searching for certain employees within an organizational unit, you only want information returned about Organizational Person entries. All other classes of entry should be omitted from the search result.

To specify the requirements that an entry must satisfy to be included in the search, pass an object of the OM class Filter as the Filter parameter of the Search function. This object has the attributes shown in Figure 2.2, “Attributes of the OM Class Filter”.

If no filter is specified for a search, all entries are returned, subject to access control and DSA service controls.

Specify a Boolean operator as the attribute Filter-Type. Filter-Type joins together the elements of the Filter to determine whether or not an entry satisfies it. The elements of the filter are the Filter-Items and nested Filters, each of which makes an assertion about the attributes of an entry. Decide which Boolean operator to use as follows:

• If you want the Filter to succeed only if all the assertions succeed, then use the value and .

• If you want the Filter to succeed if any of the assertions succeed, then use the value or.

• If you have a Filter with one nested Filter, or Filter-item, and you want the Filter to succeed if the nested Filter or Filter-item fails, then use the value not.

• If you have a Filter with one nested Filter-item, and you want the Filter to succeed if the nested Filter-item succeeds, then use the value item .

Specify a list of assertions about the existence or values of an entry attribute type as the Filter-Items attribute. Filter-Items contains any number of objects of the OM class Filter-Item. The attributes of the OM class Filter-Item are shown in Figure 2.3, “Attributes of the OM Class Filter-Item”.

Specify each assertion you want to make as a Filter-Item by declaring values for its attributes, as follows:

• Attribute-Type

• Attribute-Values

• Filter-Item-Type

• Initial-Substring

• Final-Substring

Specify the attribute type that an entry must contain as the Attribute-Type attribute. Specify the attribute value of the attribute type that an entry must contain as the Attribute-Values attribute. The Attribute-Values attribute must have exactly one value except when you specify a Filter-Item-Type of present or substrings ; see the description of these values in the following list for details.

Set the value for Filter-Item-Type as follows:

• If you want to test whether the entry contains an attribute of the specified type that has at least one value that is approximately equal to the value specified, then use the value approximate-match .

• If you want to test whether the entry contains an attribute of the specified type that has at least one value that is equal to the value specified, then use the value equality .

• If you want to test whether the entry contains an attribute of the specified type that has at least one value that is greater than, or equal to, the value specified, then use the value greater-or-equ al .

• If you want to test whether the entry contains an attribute of the specified type that has at least one value that is less than, or equal to, the value specified, then use the value less-or-equ al .

• If you want to test whether the entry contains an attribute of the specified type regardless of its value, then use the value present.

  The Attribute-Values attribute is ignored when you specify this value.

• If you want to test whether the entry contains an attribute of the specified type that has a value containing all the specified substrings in the given order, then use the value substring .

  The Attribute-Values attribute can contain zero or more values; each value contains one substring.

If you want to test whether the last part of an attribute value is a particular substring, then declare that substring as the value of Final-Substring.

If you want to test whether the first part of an attribute value is a particular substring, then declare that substring as the value of Initial-Substring.

Note that the above values must not overlap. The following example shows an object of the OM class Filter, filter, whose purpose is to locate the entry that represents Joan Smith who works in the Sales department.

#define Astr1 DS_A_COMMON_NAME
#define Astr2 DS_A_ORG_UNIT_NAME
#define str1 "Joan Smith"
#define str2 "sales"

static OM_descriptor
filter_item_1 [] = {
OM_OID_DESC(OM_CLASS, DS_C_FILTER_ITEM),
{DS_ATTRIBUTE_TYPE, OM_S_OBJECT_IDENTIFIER_STRING, Astr1},
{DS_ATTRIBUTE_VALUES, OM_S_PRINTABLE_STRING, OM_STRING(str1)},
{DS_FILTER_ITEM_TYPE, OM_S_ENUMERATION, DS_APPROXIMATE_MATCH},
OM_NULL_DESCRIPTOR
},
filter_item_2 [] = {
OM_OID_DESC(OM_CLASS,DS_C_FILTER_ITEM),
{DS_ATTRIBUTE_TYPE, OM_S_OBJECT_IDENTIFIER_STRING, Astr2},
{DS_ATTRIBUTE_VALUES, OM_S_PRINTABLE_STRING, OM_STRING(str2)},
{DS_FILTER_ITEM_TYPE, OM_S_ENUMERATION, DS_APPROXIMATE_MATCH},
OM_NULL_DESCRIPTOR
},
filter [] = {
OM_OID_DESC(OM_CLASS,DS_C_FILTER),
{DS_FILTER_ITEMS, OM_S_OBJECT, {0,filter_item_1}},
{DS_FILTER_ITEMS, OM_S_OBJECT, {0,filter_item_2}},
{DS_FILTER_TYPE, OM_S_ENUMERATION, DS_AND},
OM_NULL_DESCRIPTOR
};

The filter object contains two subobjects of OM class Filter-Item; fil- ter_item_1 and filter_item_2. The first, filter_item_1, is only true if the entry has an attribute of type Common-Name, with a value of ‘‘Joan Smith’’.

The second, filter_item_2, is only true if the entry has an attribute of type Org-Unit-Name, with a value of ‘‘Sales’’.

The filter object has a Filter-Type value of and . Therefore, filter is only

true if both Filter-Items are true.

This section describes two ways you can use the OM-Get function to extract data from a Read-Result object. It also explains the advantages and disadvantages of each method.

The Read-Result that you get back from an Abstract Service is a hierarchical data structure which contains nested structures. The OM-Get function provides features for you to obtain data from any desired level in the structure. You can either extract all the data values or extract a pointer to a sub-object.

There are two ways to access the data within the structure.

Which method you use depends on:

You can also use a combination of these methods.

The following example code extract shows how to extract the data one level at a time (op tion 1) using the exclusions argument in the OM-Get function. The example uses the public trace object dsX_trace_object routine.

/* declare a OM-type-list structure and variables to hold pointers
to the entry, DS_object, and RDNS sub-object:
*/
OM_type included_types[2];
OM_public_object spub_entry;
OM_public_object spub_DS_object;
OM_public_object spub_RDNS;

/* and set up the OM attributes you want to get first: */
      included_types[0] = DS_ENTRY;
      included_types[1] = OM_NO_MORE_TYPES;
/* now get only a pointer to the first sub-object, the entry */
  om_status = om_get(read_result,
      OM_EXCLUDE_ALL_BUT_THESE_TYPES+OM_EXCLUDE_SUBOBJECTS,
           included_types, OM_FALSE, 0, OM_ALL_VALUES,
           &spub_entry, &desc_count);

/* the object spub_entry now contains only the
  OM-descriptor for an entry-information object */

dsX_trace_object(spub_entry);
/* Now, use OM-Get again to extract the distinguished name from
the entry information. */

         included_types[0] = DS_OBJECT_NAME;
         om_status = om_get(spub_entry->value.object.object,
                OM_EXCLUDE_ALL_BUT_THESE_TYPES+OM_EXCLUDE_SUBOBJECTS,   
                included_types, 0, 0, OM_ALL_VALUES,
                &spub_RDNS, &desc_count);

dsX_trace_object(spub_RDNS);
/* Now loop around each RDN, extract a pointer to the AVAS
and then extract the attribute type and value
   */
...

If you set the Local Strings parameter on the OM-GET call, the results are converted into the local string syntax (ISO Latin-1). See OSI-Abstract-Data Manipulation for more information.

Call the Add-Entry function to add an entry to the Directory.

Call the Modify-Entry function to modify an entry in the Directory. It can be used to add or remove an attribute with all its values, or just a specific attribute value.

You should not modify an entry by deleting it and then adding the new entry. In the time between the deletion and addition of the entry another user could add an entry with the same name.

The Modify-Entry function cannot modify the distinguished value of an entry. Instead, use the Modify-RDN function (see Section 2.6.4, “Modifying a Relative Distinguished Name”).

Note that the access control in operations can restrict a user’s ability to alter an entry or attribute. Your application must be able to handle the error returned in these circumstances.

Call the Remove-Entry function to remove an entry from the Directory. The entry that you remove must not have any subordinate entries. If you do not know that the entry has no subordinates then use the List function to verify this before calling the Remove-Entry function.

Specify the name of the entry you want to remove from the Directory in the Name parameter of the Remove-Entry function.

The Remove-Entry function has the parameters common to all modification functions, and no others.

Call the Modify-RDN function to change the Relative Distinguished Name (RDN) of an entry.

Specify the name of the entry that you want to change in the Name parameter of the Modify-RDN function.

Specify the new RDN as an object of OM class Relative-Name. You pass this object as the New-RDN parameter of the Modify-RDN function.

You have the option to delete the attribute values that were part of the old RDN but are not part of the new RDN. Use the Delete-Old-RDN parameter of the Modify-RDN function to indicate whether or not such attributes should be deleted:

The Delete-Old-RDN parameter must have the value true if an attribute in the RDN is only permitted to have one value, and has that value changed by the Modify-RDN function.

The return value of this function indicates whether or not the RDN was successfully changed.

The header files xom.h (which automatically includes xomi.h), and xds.h are mandatory. The header files xdssap.h, xdsbdcp.h, xdsmdup.h (which automatically includes xmhp.h), and xdsdec.h are optional. The following sections explain when you need to include them. The order in which you include the optional header files is not important but they must be included after the mandatory header files.

#include <xom.h>

#include <xds.h>

#include <xdsbdcp.h>

#include <xdsdec.h>

#include <xdssap.h>

#include <xdsmdup.h>

Use an ANSI C compiler to compile your application.

Note that although Digital does not support any other type of C compiler, the "#if_STDC_#else" statements in the header files make it possible to use a non- ANSI C compiler. If you use a non-ANSI C compiler, you will not be able to build public objects statically in your application by declaring a descriptor list. Instead you will have to use the Digital OMX_ macros to create public objects dynamically. These macros are described in OSI-Abstract-Data Manipulation .

On DEC OSF/1 systems, the XDS libraries are installed as both shareable libraries and archive libraries. Existing XDS applications can continue to function without relinking.

By default, when you link an application on a DEC OSF/1 system it links against the shareable libraries. For example, you can link an application as follows:

# cc file.c -lxds 

Note that on DEC OSF/1 systems, this version of the Directory Service also enables you to use the API to develop applications that can use the Cell Directory Service (CDS) of the Distributed Computing Environment (DCE), assuming those directories are installed.

Refer to Digital DCE for DEC OSF / 1 AXP Product Guide for details of DCE and CDS, and refer to the XDS and XOM manpages for details of how the API functions support CDS.

If you link an application against shareable libraries, then the link command automatically links to whichever libraries are present. To link using archive libraries, use the following command:

# cc -non_shared file.c -lxds -ldxdcds_stub -ldxd \ 
 -losak -lxti -lxtiosi -lc 

If you want to use CDS, you cannot link using archive libraries.

Note that an existing X.500 application is unlikely to work correctly with CDS without modification. CDS does not support all of the XDS functions. The XDS and XOM manpages on DEC OSF/1 systems include notes about how to use each function with CDS. Refer to Digital DCE for DEC OSF / 1 AXP Product Guide for further details.

Note that the functionality of libraries has not changed on OpenVMS systems or ULTRIX systems, and the option to develop applications for CDS is only available on DEC OSF/1 systems.

cc -g xds_read_example.c -lxds -o xds_read_example 

Link your application in the normal way, specifying the XDS shareable image using an options file, for example:

$ link program_name, sys$input:/option
sys$library:dxd$xds_shr/share
sys$library:vaxcrtl.exe/share
^z
$