Name

xom_intro - Introduction to X/OPEN OSI-Abstract-Data Manipulation (XOM) functions

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. 

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()
Creates a new public object that is an exact but independent copy of an existing subobject in a private object. This function is similiar to the om_get() function but includes an additional parameter navigation_path that contains directions to the required object to be extracted. 

omX_fill()Initializes an OM descriptor structure with user supplied values for its type, syntax and value. 

omX_fill_oid()
Initializes an OM descriptor structure with user supplied values for its type and value.  The syntax of the descriptor is always set to OM_S_OBJECT_IDENTIFIER_STRING. 

omX_object_to_string()
Converts an OM object into a string format.

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

om_copy()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()
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()
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()
Deletes a service-generated public object, or makes a private object inaccessible.

om_get()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()
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()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()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()
Removes and discards particular values of an attribute of a private object. The attribute itself is removed if no values remain.

om_write()
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

Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.  The possible error return values are described 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.