(c) Digital Equipment Corporation. 1994. All rights reserved.

Name

om_intro − This reference page introduces the OM API functions. 
 
 
 

Syntax

#include <xom.h>
 
 
 

Description

 
This reference page defines the functions of the C interface in the Digital X.500 product.

Function@Description  
 
 
om_copy@T{ Copies a private object T} om_copy_value@T{ Copies a string between private objects T} om_create@T{ Creates a private object T} om_decode@T{ Creates a new private object that decodes an existing ASN.1 private object.  T} om_delete@T{ Deletes a private or service-generated object T} om_encode@T{ Creates a new private object that encodes an existing private object.  T} om_get@T{ Gets copies of attribute values from a private object T} om_instance@T{ Tests an object’s class T} om_put@T{ Puts attribute values into a private object T} om_read@T{ Reads a segment of a string in a private object T} om_remove@T{ Removes attribute values from a private object T} om_write@T{ Writes a segment of a string into a private object T}

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

om_copy@T{
 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. T}  
om_copy_value@T{ 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.  T}  
om_create@T{ 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.  T}  
om_decode@T{ This function creates a new private object by decoding the ASN.1 of the original object.  T}  
om_delete@T{ This function deletes a service-generated public object,  or makes a private object inaccessible.  T}  
om_encode@T{ This function creates a new private object, the encoding, which exactly and independently encodes an existing private object, the original.  T}  
om_get@T{ 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). T}  
om_instance@T{ 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 because it reveals that an object is an instance of a particular class, even if the class is an instance of a subclass of that class.  T}  
om_put@T{ This function places or replaces in one private object copies of the attribute values of another public object 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.  T}  
om_read@T{ 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.  T}  
om_remove@T{ This function removes and discards particular values of an attribute of a private object.  The attribute itself is removed if no values remain.  T}  
om_write@T{ 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 because 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.  T}  

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 exeception.  However, the service does not guarantee that a task is always carried out in full.