NAME

SYNOPSIS

#include <xom.h>
#include <xomext.h>

DESCRIPTION

This xom_intro reference page defines the functions of the C interface. The following table lists the relevant functions.

___________________________________________________________________________________
                   Service Interface Functions - xom_intro(3xom)
___________________________________________________________________________________
 Function                 Description
___________________________________________________________________________________
 omX_extract()            Get attribute values from specified object
 omX_fill()               Initialize an OM_descriptor structure
 omX_fill_oid()           Initialize an OM_descriptor with an OID value
 omX_object_to_string()   Convert an OM_object to string format
 omX_string_to_object()   Convert a string to OM_object
 om_copy()                Copies a private object.
 om_copy_value()          Copies a string between private objects.
 om_create()              Creates a private object.
 om_decode()              This function is not supported by the DCE XOM interface,
                          and returns with an OM_FUNCTION_DECLINED error.
 om_delete()              Deletes a private or service-generated object.
 om_encode()              This function is not supported by the DCE XOM interface,
                          and returns with an OM_FUNCTION_DECLINED error.
 om_get()                 Gets copies of attribute values from a private object.
 om_instance()            Tests an object's class.
 om_put()                 Puts attribute values into a private object.
 om_read()                Reads a segment of a string in a private object.
 om_remove()              Removes attribute values from a private object.
 om_write()               Writes a segment of a string into a private object.
___________________________________________________________________________________
8|

As indicated in the table, the service interface comprises a number of functions whose purpose and range of capabilities are summarized as follows:

omX_extract()

This function creates a new public object, that is an exact but independent copy of an existing subobject in a private object. It is similiar to the om_get() function but includes an additional parameter navigation_path which contains directions to the required object to be extracted.

omX_fill()

This function is used to initialize an OM descriptor structure with user supplied values for it's type, syntax and value.

omX_fill_oid()

This function is used to initialize an OM descriptor structure with user supplied values for it's type and value. The syntax of the descriptor is always set to OM_S_OBJECT_IDENTIFIER_STRING.

omX_object_to_string()

This function converts an OM object into a string format.

omX_string_to_object()

The omX_string_to_object() function creates a new private object, which is build from the string and class input parameters.

om_copy()

This function creates an independent copy of an existing private object and all its subobjects. The copy is placed in the original's workspace, or in another specified by the XOM application.

om_copy_value()

This function replaces an existing attribute value or inserts a new value in one private object with a copy of an existing attribute value found in another. Both values must be strings.

om_create()

This function creates a new private object that is an instance of a particular class. The object can be initialized with the attribute values specified as initial in the class definition.

The service does not permit the API user to explicitly create instances of all classes, but rather only those indicated by a package's definition as having this property.

om_delete()

This function deletes a service-generated public object, or makes a private object inaccessible.

om_get()

This function creates a new public object that is an exact but independent copy of an existing private object. The client can request certain exclusions, each of which reduces the copy to a part of the original. The client can also request that values be converted from one syntax to another before they are returned.

The copy can exclude: attributes of types other than those specified, values at positions other than those specified within an attribute, the values of multivalued attributes, copies of (not handles for) subobjects, or all attribute values (revealing only an attribute's presence).

om_instance()

This function determines whether an object is an instance of a particular class. The client can determine an object's class simply by inspection. This function is useful since it reveals that an object is an instance of a particular class, even if the object is an instance of a subclass of that class.

om_put()

This function places or replaces in one private object copies of the attribute values of another public or private object.

The source values can be inserted before any existing destination values, before the value at a specified position in the destination attribute, or after any existing destination values. Alternatively, the source values can be substituted for any existing destination values or for the values at specified positions in the destination attribute.

om_read()

This function reads a segment of a value of an attribute of a private object. The value must be a string. The value can first be converted from one syntax to another. The function enables the client to read an arbitrarily long value without requiring that the service place a copy of the entire value in memory.

om_remove()

This function removes and discards particular values of an attribute of a private object. The attribute itself is removed if no values remain.

om_write()

This function writes a segment of a value of an attribute to a private object. The value must be a string. The segment can first be converted from one syntax to another. The written segment becomes the value's last segment since any elements beyond it are discarded. The function enables the client to write an arbitrarily long value without having to place a copy of the entire value in memory.

In the C interface, the functions are realized by macros. The function prototype in the synopsis of a function's specification simply shows the client's view of the function.

The intent of the interface definition is that each function be atomic; that is, either it carries out its assigned task in full and reports success, or it fails to carry out even a part of the task and reports an exception. However, the service does not guarantee that a task is always carried out in full.

ERRORS

The possible error return values are listed in the function reference pages.

XOM functions check for NULL pointers and return an error, except for workspace pointers. Pointers are only checked at the function interface. The check is only for NULL and not for validity. If NULL or invalid pointers are passed this may result in an undetermined behaviour.