Most application programs require the use of a series of om_get( ) function calls to create service-generated public objects from which the program can extract requested information. For this reason, this topic uses the operation of om_get( ) as an example to describe how XOM API functions operate in general.
The following code fragment from example.h shows how a series of om_get( ) function calls extract a list of telephone numbers from a workspace. The ds_read( ) function call deposits the private object stored in result in the workspace and provides access to it by the pointer &result.
/*
* extract the telephone number(s) of "name" from the result
*
* There are 4 stages:
* (1) get the Entry-Information from the Read-Result.
* (2) get the Attributes from the Entry-Information.
* (3) get the list of phone numbers.
* (4) scan the list and print each number.
*/
CHECK_OM_CALL( om_get(result,
OM_EXCLUDE_ALL_BUT_THESE_TYPES
+ OM_EXCLUDE_SUBOBJECTS,
entry_list, OM_FALSE, 0, 0, &entry,
&total_num));
CHECK_OM_CALL( om_get(entry->value.object.object,
OM_EXCLUDE_ALL_BUT_THESE_TYPES
+ OM_EXCLUDE_SUBOBJECTS,
attributes_list, OM_FALSE, 0, 0, &attributes,
&total_num));
CHECK_OM_CALL( om_get(attributes->value.object.object,
OM_EXCLUDE_ALL_BUT_THESE_TYPES
+ OM_EXCLUDE_SUBOBJECTS,
telephone_list, OM_FALSE, 0, 0, &telephones,
&total_num));
/* We can now safely release all the private objects
* and the public objects we no longer need
*/
CHECK_OM_CALL(om_delete(session));
CHECK_OM_CALL(om_delete(result));
CHECK_OM_CALL(om_delete(entry));
CHECK_OM_CALL(om_delete(attributes));
CHECK_DS_CALL(ds_shutdown(workspace));
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);
}
CHECK_OM_CALL(om_delete(telephones));
The om_get( ) call makes a copy of all or a selected set of parts of a private object. The copy is a service-generated public object that is accessible to the application program. The application program extracts the list of telephone numbers from this copy.
More:
Extracting the Data from the Read Result