Previous section.
DCE 1.1: Directory Services
Copyright © 1997 The Open Group
The Open Group OSI-Abstract-Data Manipulation (XOM)
This chapter identifies the conformance requirements of The Open Group
OSI-Abstract-Data Manipulation (XOM) API implementations for the DCE.
For the full Open Group XOM API, see the referenced XOM specification.
The XOM specification is the specification of a general purpose API for use in
conjunction with other application-specific APIs, such as XDS.
XOM consists of the creation, examination, modification and deletion of
potentially complex information objects. It presents to the programmer a
uniform model of information based on the concept of classes of similar
information objects.
The information objects to which XOM applies are those that arise in OSI
- that is, those that correspond to the types defined by, or by means
of, Abstract Syntax Notation One (ASN.1). The XOM API comprises tools for
manipulating ASN.1 objects.
XOM Conformance
DCE XOM conforms to the XOM specification.
DCE XOM has the following characteristics:
-
Multiple workspaces for XDS objects are supported.
-
The OM package is supported.
-
The om_encode () and om_decode () functions
are not supported. The transfer of objects between workspaces
is not envisaged within the DCE environment, and the OM classes
used by the DCE XDS/XOM API are not encodable.
-
Translation to local character sets is supported.
XOM Functions
XOM Interface Functions
lists the functions of the XOM C interface.
| Function
| Description
|
|---|
| 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.
|
Table: XOM Interface Functions
The service interface comprises a number of functions, whose purpose and
range of capabilities are described in the following sections.
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 workspace specified by the XOM application.
om_copy_value()
Replaces an existing attribute value, or inserts a new value, into a private
object. The value is a copy of an existing attribute value found in another
private object. Both values must be strings.
om_create()
Creates a new private object that is an instance of a particular class. The
object can be initialised with the attribute values specified as initial in
its class definition.
The service does not permit the API user explicitly to 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 caller can request certain exclusions, each of
which reduces the copy to some part of the original. Exclusions can be as
follows:
-
attributes of types other than those specified
-
values at positions other than those specified
within an attribute
-
the values of multi-valued attributes
-
copies of (but not handles for) subobjects
-
all attribute values (with the result that only an
attribute's presence is indicated by the return).
The caller can also request that values be converted from one syntax to
another before they are returned (that is, copied).
om_instance()
Determines whether an object is an instance of a particular class. An
application can determine an object's immediate class simply by inspection.
However, this function is useful because it can be used to find whether 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 a specified private object copies of the attribute
values of some other specified public or private object.
The source values can be inserted:
-
before any existing values in the destination attribute
-
before the value at a specified position in the
destination attribute
-
after any existing destination values.
Alternatively, the source values can be made to overwrite all existing
destination values, or only 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. This function enables the caller 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 exist.
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 truncated as a result of the call. This function
enables the caller to write an arbitrarily long value without having to
place a copy of the entire value in memory.
The intention of the interface definition is that each function be atomic;
that is, that it will either carry out its assigned task to completion and
then report success, or that it fails to carry out even a part of the task,
whereupon it will report an exception. However, the service does not
guarantee that a task is always carried out in full.
Please note that the html version of this specification
may contain formatting aberrations. The definitive version
is available as an electronic publication on CD-ROM
from The Open Group.