The entry parameter contains the result of processing by om_get( ) of the read parameter generated by the ds_read( ) operation. A successful call to ds_read( ) returns an instance of OM class DS_C_READ_RESULT in the private object result. DS_C_READ_RESULT contains the information extracted from the directory entry of the target object. The following figure shows the relationship of some of the superclasses, subclasses, and the OM attribute of DS_C_READ_RESULT. Consider the following figure as a partial map of the contents of result.
The Read Result
The om_get( ) function call creates a public object to make the information contained in result available to the application program. The entry parameter is defined as data type OM_public_object. As such, it is composed of several nested layers of subobjects that contain entry information, OM attributes, and OM attribute values, as shown in the following figure. The series of om_get( ) calls removes these layers of objects to extract a list of telephone numbers.
The following figure also shows that the process of exposing the subobjects continues while the syntax of the subobjects is OM_S_OBJECT. In effect, example.h is reversing the process of building up a series of public objects as input to ds_read( ); namely, the distinguished name of Peter Piper and the descriptor list for entry_information_selection.
Extracting Information Using om_get( )
The following code fragment from example.c shows how the syntax of the variable telephones is tested for valid syntax; in this case, OM_S_PRINTABLE_STRING:
for (telephone = telephones;
telephone->type != DS_ATTRIBUTE_VALUES;
telephone++)
{
if (telephone->type != DS_ATTRIBUTE_VALUES ||
(telephone->syntax & OM_S_SYNTAX) !=
OM_S_PRINTABLE_STRING)
{
(void) fprintf(stderr, "malformed telephone number\n");
exit(EXIT_FAILURE);
}
(void) printf("Telephone number: %s\n",
telephone->value.string.elements);
}
The preceding example determines whether telephones is in a format that can be used by the application program as string data that can be printed out, and that the syntax is correct for a list of telephone numbers. Note that the program uses the constant OM_S_SYNTAX to mask off the top 6 bits. These bits are special bits that are used by XOM API. (Refer to XOM Service Interface for more information on these special bits.)