The example.c program uses XDS API in synchronous mode to read a telephone number or numbers of a distinguished name. The program consists of the following general steps:
1. Define the required object identifier constants.
2. Declare the variables involved with directory service operations (Steps 3, 4, 7, 8, and 9).
3. Build the distinguished name of Peter Piper as a public object for the input parameter to ds_read( ).
4. Build a public object for the selection parameter to ds_read( ).
5. Declare the variables to extract the telephone numbers by using om_get( ).
6. Initialize the directory service and get an OM workspace.
7. Pull in the required packages.
8. Bind to a default directory session.
9. Perform the read operation to extract the telephone number of a distinguished name from the directory.
10. Terminate the directory service session.
11. Extract the telephone number(s) by using a series of om_get( ) calls.
12. Release the storage occupied by private and public objects that are no longer needed.
13. Print the telephone number string.
14. Release the storage occupied by public objects containing telephone numbers.
15. Continue processing and exit.
Step 1 uses the OM_EXPORT macro to allocate memory for the object identifier constants that represent an OM class or OM attribute. These constants are the OM attribute values that are used to build the public objects that are required as input to ds_read( ).
Step 2 declares the variables for directory service operations and error handling. The session and workspace variables are required for binding a session to a server and creating a workspace into which ds_read( ) can deposit the results of the read operation on the directory.
The result variable is a pointer that is returned by ds_read( ) to the workspace. The information stored in result is in implementation-specific private format that is not accessible directly by the application program. Subsequent om_get( ) calls extract the telephone number(s) requested by the program from result and store the information in the variable telephones (declared in Step 5).
The error and return_code variables are used by the program for error handling. The error variable is used for processing the return code from XDS API function calls. The return_code variable is used by the error handling header file example.h for processing return codes from om_get( ) function calls.
Step 3 builds the public object representing the distinguished name of Peter Piper. The program uses statically defined public objects to demonstrate the basic principles of building public objects. However, a more sophisticated approach is presented in the last sample program in this topic, teldir.c. The teldir.c program dynamically defines a public object from a user-supplied name in DCE string format.
In this program (example.c), the process starts with the definition of an array of descriptor lists as AVAs. These AVAs are public objects that are included in the definition of RDNs. The RDNs, in turn, are included in the distinguished name of Peter Piper stored in name. Using the same method of static definition, Step 4 defines the DS_C_ENTRY_INFO_SELECTION public object and stores it in the variable selection. The name and selection variables are required as input parameters to ds_read( ). This process is described in detail in XDS Programming.
Step 5 declares the variables required by om_get( ) to extract the telephone number(s) from result. The entry_list, attributes_list, and telephone_list variables are of type OM_type and are initialized to the values of the OM attribute types DS_ENTRY, DS_ATTRIBUTES, and DS_ATTRIBUTE_VALUES, respectively. DS_ENTRY contains the selected list of entries, DS_ATTRIBUTES contains the selected list of attribute types, and DS_ATTRIBUTE_VALUES contains the actual values of the telephone numbers.
The entry, attributes, and telephones variables are of type OM_public_object because they store the output parameters of om_get( ). The om_get( ) call makes these objects available to the application program as public object data types. The program must remove layers of objects and subobjects to get at the actual string data values of the telephone numbers.
The telephones variable contains the actual string values of the telephone number(s). It is a descriptor in the array of descriptors that make up the public object that contains the actual string data that the program wants to extract from the directory.
Step 6 initializes the directory service and gets an OM workspace in which ds_read( ) deposits the result of the read operation.
Step 7 pulls the basic directory contents package into the program because it contains features that are required by the program not included in the default package (the directory service package).
Step 8 binds the session to the default session. An application program can bind with a specifically tailored session object, by using an instance of OM class DS_C_SESSION. In most cases, however, it is sufficient to use the constant DS_DEFAULT_SESSION. DS_DEFAULT_SESSION uses the default values of DS_C_SESSION and the values of specific OM attributes that are set locally in the cache. These OM attributes are DS_DSA_ADDRESS (the address of the default DSA) and DS_DSA_NAME (the distinguished name of the default DSA). It is the responsibility of local administrators to make sure that these default values are set correctly in the cache.
Step 9 performs the read operation and deposits the result in the workspace in result. The Sresult variable is one of the input parameters for the om_get( ) function call. The session variable and the DS_DEFAULT_CONTEXT constant are the session and context parameters required to be present in the ds_read( ) function call.
The name variable holds the public object representing the distinguished name of Peter Piper; the selection variable contains the public object indicating which attributes and values are selected by the read operation from the entry. The invoke_id parameter is not used by the DCE implementation of XDS and is ignored.
Step 10 terminates the directory session.
Step 11 uses a series of om_get( ) calls to extract the telephone number(s). The first om_get( ) extracts the information about the entry from result and puts it in entry. The second om_get( ) extracts the attribute types from entry and puts them in attributes. The third om_get( ) extracts the actual values of the telephone numbers from attributes and puts them in telephones. The telephones variable contains the string data values of the telephone number(s).
Step 12 releases the storage occupied by the private and public objects that are no longer needed. The program has the data values in telephone that it needs to continue processing. A ds_shutdown( ) call is issued to shut down the interface established by ds_initialize( ).
Step 13 prints out each telephone number associated with the distinguished name Peter Piper in the directory, or returns an error message if the number is not in the correct format. It checks for an attribute with type DS_ATTRIBUTE_VALUES and a syntax of OM_S_PRINTABLE_STRING, the proper syntax for a telephone number. The constant OM_S_SYNTAX is used to mask the six high-order bits in the syntax because they are used internally by the XOM service.
Step 14 releases the storage occupied by telephones because it is no longer needed.
Step 15 continues processing and exits.
More: