Digital DCE for OpenVMS VAX and OpenVMS Alpha
Reference Guide
Previous Contents Index

dsX_trace_object(3xds)

Displays an explanation of the content of an object on the current output device.

Syntax

(void ) dsX_trace_object(Object )

Argument Data Type Access
Object OM_object read

C Binding

dsX_trace_object(object)


dsX_trace_objectobject
OM_object object

Arguments

OM_Object

The object whose content you want to inspect.

Description

This function displays on the current output device information about the content of an OM object, as follows:

The routine also checks for null pointers.

Errors

None.

Examples

The following code extract shows an example call to the Trace Object function: 


 
{ 
  OM_workspace workspace; 
  OM_return_code status; 
  OM_object session = NULL; 
 
  status = om_create(DS_C_SESSION,OM_TRUE,workspace,&session); 
  if (status == OM_SUCCESS) 
    { 
      dsX_trace_object(session); 
    }  
}

Chapter 8
XOM Reference Pages

This chapter provides reference pages for the X/Open Object Management (XOM) API functions.

Compaq's XOM implementation supports two additional ways to create private objects. The functions are as follows:

om_intro(3xom)

Introduces the OM API functions.

Synopsis

#include <XOM.H>

Description

This reference page defines the functions of the C interface in the Digital X.500 product.
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 Creates a new private object that decodes an existing ASN.1 private object.
om_delete Deletes a private or service-generated object.
om_encode Creates a new private object that encodes an existing private object.
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.

As indicated in the table, the service interface comprises a number of functions whose purpose and range of capabilities are summarized as follows:
Function Description
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_decode This function creates a new private object by decoding the ASN.1 of the original object.
om_delete This function deletes a service-generated public object, or makes a private object inaccessible.
om_encode This function creates a new private object, the encoding, which exactly and independently encodes an existing private object, the original.
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 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.
om_put 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.
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 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.

In the C interface, the functions are realized by macros. The function prototype in the synopsis of a function's specification 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.

om_copy(3xom)

Creates a copy of an existing private object.

Synopsis

OM _return_code om_copy(original, workspace, copy)

Argument Data Type Access
original OM_private_object read
workspace OM_workspace read
copy OM_private_object write
return_code OM_return_code  

C Binding

OM_return_code om_copy(original, workspace, copy)

OM_private_object original,
OM_workspace workspace,
OM_private_object #copy

Arguments

Original

The original private object.

Workspace

The workspace in which the service creates the copy. The workspace that the client specifies in this argument must be one that is associated with a package containing the class of the original object.

Copy

The copy of the original object. The service returns this argument if the Return Code of the function is OM_SUCCESS.

Description

This function creates a new private object, the copy, which is an exact but independent copy of an existing private object, the original. The function also copies the original's subobjects, if it has any.

The client can specify a workspace in which the service should place the copy. If the client does not do so, the service places the copy in the original's workspace.

Return Values

Possible return values are as follows:
Return Description
OM_SUCCESS The function has completed its task successfully.
OM_FUNCTION_INTERRUPTED The function was aborted by external intervention.
OM_MEMORY_INSUFFICIENT There is not enough memory to complete the function.
OM_NETWORK_ERROR The service cannot use the underlying network.
OM_NO_SUCH_CLASS There is an undefined class identifier.
OM_NO_SUCH_OBJECT You have specified a nonexistent object, or an invalid Handle for an object.
OM_NO_SUCH_WORKSPACE You have specified a nonexistent workspace.
OM_NOT_PRIVATE There is a public object where there should be a private object.
OM_PERMANENT_ERROR The service encountered a permanent problem for which there is no defined error code.
OM_POINTER_INVALID An invalid pointer was supplied as a function argument.
OM_SYSTEM_ERROR The service cannot use the operating system.
OM_TEMPORARY_ERROR The service encountered a temporary problem for which there is no defined error code.
OM_TOO_MANY_VALUES An implementation limit prevents the addition to an object of another attribute value.

Examples

The following example shows how to copy an object of the MH class Local NDR (ndr). The copy is ndr_copy. 


 
OM_return_code      result; 
OM_private_object   ndr, 
                    ndr_copy; 
OM_workspace        workspace; 
     result = om_copy (ndr, 
                             /* object to be copied */ 
                       workspace, 
                             /* workspace in which to create copy */ 
                       &ndr_copy); 
                             /* the copy */

om_copy_value(3xom)

Copies a value (string) from a private object and places it in another private object.

Synopsis

OM _return_code om_copy_value(source, source _type, source_value_position, destination, destination_type, destination_value_position)

Argument Data Type Access
source OM_private_object read
source_type OM_type read
source_value_position OM_value_position read
destination OM_private_object read
destination_type OM_type read
destination_value_position OM_value_position read
return_code OM_return_code  

C Binding

OM_return_code om_copy_value(source, source_type, source_value_position, destination, destination_type, destination_value_position)

OM_private_object source,
OM_type source_type,
OM_value_position source_value_position,
OM_private_object destination,
OM_type destination_type,
OM_value_position destination_value_position

Arguments

Source

The object from which you want to copy the value.

Source Type

The type of the attribute value from which you want to copy the value.

Source Value Position

The position within the attribute of the value to be copied.

Destination

The object to which you want to copy the value.

Destination Type

The type of the attribute to which you want to copy the value.

Destination Value Position

The position within the destination attribute at which you want to place the copied value. If the value of this argument exceeds the number of values in the Destination attribute, then it is taken to be equal to that number.

Description

This function either replaces, or fills in for the first time, an attribute value in the destination object with a copy of an attribute value from the source object. The source value should be a string. The copy has the same syntax as the source value.

Return Values

Possible return values are as follows:
Return Description
OM_SUCCESS The function has completed its task successfully.
OM_FUNCTION_DECLINED The function does not apply to the object to which it is addressed.
OM_FUNCTION_INTERRUPTED The function was aborted by external intervention.
OM_MEMORY_INSUFFICIENT There is not enough memory to complete the function.
OM_NETWORK_ERROR The service cannot use the underlying network.
OM_NO_SUCH_OBJECT You have specified a nonexistent object, or an invalid Handle for an object.
OM_NO_SUCH_TYPE There is an undefined type identifier.
OM_NOT_PRESENT An expected attribute value is missing.
OM_NOT_PRIVATE There is a public object where there should be a private object.
OM_PERMANENT_ERROR The service encountered a permanent problem for which there is no defined error code.
OM_POINTER_INVALID An invalid pointer was supplied as a function argument or as the receptacle for a function result.
OM_SYSTEM_ERROR The service cannot use the operating system.
OM_TEMPORARY_ERROR The service encountered a temporary problem for which there is no defined error code.
OM_WRONG_VALUE_LENGTH There is an attribute with a value that violates the value length constraints in force.
OM_WRONG_VALUE_SYNTAX There is an attribute value with an illegal syntax.
OM_WRONG_VALUE_TYPE There is an attribute value of an illegal type.

Examples

The following example shows the copying of a string value between two objects of the MH class Delivery Envelope (envelope1 and envelope2). 


 
OM_private_object    envelope1, 
                     envelope2; 
OM_return_code       result; 
     result = om_copy_value (envelope1, 
                                 /* source object */ 
                             MH_T_CONTENT_IDENTIFIER, 
                                 /* source attribute */ 
                             0, 
                                 /* position of value in source attribute */ 
                             envelope2, 
                                 /* destination object */ 
                             MH_T_CONTENT_IDENTIFIER, 
                                 /* destination attribute */ 
                             0); 
                                 /* position in destination attribute */

This call to Copy Value reads the string value at position 0 in the Content Identifier attribute of envelope1. This value is then copied to position 0 in the Content Identifier attribute of envelope2.

om_create(3xom)

Creates a new private object that is an instance of a particular class.

Synopsis

OM _return_code om_create(class, initialize, workspace, object)

Argument Data Type Access
class OM_object_identifier read
initialize OM_boolean read
workspace OM_workspace read
object OM_private_object write
return_code OM_return_code  

C Binding

OM_return_code om_create(class, initialize, workspace, object)

OM_object_identifier class,
OM_boolean initialize,
OM_workspace workspace,
OM_private_object #object

Arguments

Class

The class of the object you are creating. It must be a concrete class.

Initialize


If you set this argument to OM_TRUE, the object that you create has some of its attributes initialized. These are the attributes for which initial values are specified in the class definition table. You can find these class definition tables in the documentation for the X.400 and X.500 APIs.

If you set this argument to OM_FALSE, the object you create has only its Class attribute initialized.

Workspace

The workspace in which the service should create the object. The class you specify for the object must be in a package that you already associated with this workspace.

Object

This is the created object. The service returns this argument if the Return Code of the function is OM_SUCCESS.

Description

This function creates a private object in the workspace that you specify.

You can add new values and replace or remove existing values, any time after the object has been created. In this way, you can create any possible instance of the object's class.

Return Values

Possible return values are as follows:
Return Description
OM_SUCCESS The function has completed its task successfully.
OM_FUNCTION_DECLINED The function does not apply to the object to which it is addressed.
OM_FUNCTION_INTERRUPTED The function was aborted by external intervention.
OM_MEMORY_INSUFFICIENT There is not enough memory to complete the function.
OM_NETWORK_ERROR The service cannot use the underlying network.
OM_NO_SUCH_CLASS There is an undefined class identifier.
OM_NO_SUCH_WORKSPACE You have specified a nonexistent workspace.
OM_NOT_CONCRETE A class is abstract, not concrete.
OM_PERMANENT_ERROR The service encountered a permanent problem for which there is no defined error code.
OM_POINTER_INVALID An invalid pointer was supplied as a function argument.
OM_SYSTEM_ERROR The service cannot use the operating system.
OM_TEMPORARY_ERROR The service encountered a temporary problem for which there is no defined error code.

Examples

The first example shows how to create a private object of Message Handling (MH) class Local Per-recipient NDR, with the Initialize argument set to OM_FALSE; the function does not initialize any of the object's attributes.

The second example shows the creation of a private object of X.500 class Entry-Info-Selection, with the Initialize argument set to OM_TRUE; the function initializes two of the object's attributes. 


 
OM_private_object    ndr; 
OM_workspace         workspace; 
OM_return_code       result; 
    
     result = om_create (MH_C_LOCAL_PER_RECIP_NDR, 
                             /* class of object */ 
                         OM_FALSE, 
                             /* do not initialize attributes */ 
                         workspace, 
                             /* workspace in which object created */ 
                         &ndr); 
                             /* created object */ 
 



 
OM_private_object    select_info; 
OM_workspace         workspace; 
OM_return_code       result; 
     result = om_create (DS_C_ENTRY_INFO_SELECTION, 
                             /* class of object */ 
                         OM_TRUE, 
                             /* initialize attributes */ 
                         workspace, 
                             /* workspace in which object created */ 
                         &select_info); 
                             /* created object */

Previous Next Contents Index