4 — XDS Object ManagementReference Pages

[Previous] [Next] [Contents]

This chapter provides reference pages for the X/Open Object Management (XOM) API functions. The Gradient DCE for Tru64 UNIX XOM implementation supports two additional ways to create private objects. The functions are as follows:

• The om_encode function uses the encoding rules you specify to create a private object independent of the original private object.

• The om_decode function decodes the ASN.1 of the original object to create the new one. You must specify the class of the existing object and the rules used to encode it.

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

om_copy(3xom)

om_copy - Creates a copy of an existing private object.

Syntax

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

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 =   copy (ndr,
                             /* object to be copied */
                       workspace,
                             /* workspace in which to create copy */
                       &ndr_copy);
                             /* the copy */

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

Syntax

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 tocopy 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 thevalue.

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

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)

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

Syntax

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

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 */

om_decode - Creates a new private object that decodes an existing ASN.1 private object.

Syntax

OM_return_code om_decode(encoding, original)

Argument	Data Type	Access
encoding	OM_private_object	read
original	OM_private_object	write
return_code	OM_return_code

C Binding

OM_return_code om_decode(encoding, original)

OM_private_object encoding,
OM_private_object #original

Arguments

Encoding

The encoded object that you want to decode. It must be an instance of the Encoding class.

Original

An object that is the decoded version of the encoding. The Service creates this object in the workspace in which the encoding is located. The Service returns this argument if the Return Code of the function is OM_SUCCESS.

Description

This function creates a new private object by decoding the ASN.1 of the original object.

In the Encoding argument, you specify the class of the existing object and the rules used to encode it. In the current version of the OM API, you must specify ASN.1 BER.

Return Values

Examples

The following example shows the decoding of the object encoded in the code example from OSI-Abstract-Data Manipulation. The encoded object is encoding, and the decoded object is decoded_object .

OM_return_code      result;
OM_private_object   encoding,
                    decoded_object;
     result = om_decode (encoding,
                             /* object to be decoded */
                         &decoded_object);
                             /* decoded object */

om_delete - Deletes a service-generated public object or makes a private object inaccessible.

Syntax

OM_return_code om_delete(subject)

Argument	Data Type	Access
subject	OM_object	read
return_code	OM_return_code

C Binding

OM_return_code om_delete(subject)

OM_object subject

Arguments

Subject

The object that you want the Service to delete. It must be a service-generated public object or a private object. If the object that you specify is a client-generated public object, the function returns an error status.

Description

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

When you apply this function to a service-generated public object, the function deletes the object and releases the resources associated with it. The resources include the space occupied by descriptors and attribute values. The function also deletes all public subobjects of the subject. This function does not delete private subobjects.

When you apply this function to a private object, the function makes the object inaccessible by making its Handle invalid. The function also makes invalid the Handles of any private subobjects of the subject. Note that the effect of using an object's Handle once it has been made invalid is undefined.

Return Values

Examples

The following example shows how to delete a service-generated public object of the X.500 class Entry-Info-Selection (info_select_copy). The object is a public copy of a private object of class Entry-Info-Selection info_select .

OM_return_code      result;
OM_private_object   info_select;
OM_object           info_select_copy;
OM_value_position   total_number;
     result = om_get (info_select,
                             /* object to be copied */
                      OM_NO_EXCLUSIONS,
                             /* no exclusions */
                      NULL,
                             /* ignored because no exclusions specified */
                      OM_FALSE,0,0,
                             /* no translation into local char set */
                      &info_select_copy,
                             /* the copy */
                      &total_number);
                             /* number of attributes copied */
/* Examine info_select_copy public object using C programming language
constructs */
/* Delete object when finished with it */
     result = om_delete (info_select_copy);
                             /* the object to be deleted */

om_encode - Creates a new private object that encodes an existing private object.

Syntax

OM_return_code om_encode(original, rules, encoding)

Argument	Data Type	Access
original	OM_private_object	read
rules	OM_object_identifier	read
encoding	OM_private_object	write
return_code	OM_return_code

C Binding

OM_return_code om_encode(original, rules, encoding)

OM_private_object original,
OM_object_identifier rules,
OM_private_object #encoding

Arguments

Original

The object you want to encode.

Rules

The set of rules that the Service must follow to produce an encoding. In this version of the OM API, you can only specify ASN.1 BER.

Encoding

An object that is the encoded version of the original. The Service creates this object in the workspace in which the original is located. The Service returns this argument if the Return Code of the function is OM_SUCCESS. The returned object is an instance of the Encoding class.

Description

This function creates a new private object, the encoding, which exactly and independently encodes an existing private object, the original. When you apply this function to a private object, the function uses the encoding rules you specify to create a new private object. The new encoded private object is independent of the original private object.

Return Values

Examples

The following example shows the encoding of an object of the MH class Report ((encodable_object). The object is encoded according to the rules OM_BER, and the encoded object is encoding.

OM_return_code      result;
OM_private_object   encodable_object,
                    encoding;
     result = om_encode (encodable_object,
                             /* object to be encoded */
                         OM_BER,
                             /* encoding rules */
                         &encoding);
                             /* encoded object */

om_get - Creates a new public object that is a copy of the whole or part of a private object.

Syntax

OM_return_code om_get(original, exclusions, included_types, local_strings, initial_value, limiting_value, copy, total_number)

Argument	Data Type	Access
original	OM_private_object	read
exclusions	OM_exclusions	read
included_types	OM_type_list	read
local_strings	OM_boolean	read
initial_value	OM_value_position	read
limiting_value	OM_value_position	read
copy	OM_public_object	write
total_number	OM_value_position	write
return_code	OM_return_code

C Binding

OM_return_code om_get(original, exclusions, included_types, local_strings, initial_value, limiting_value, copy, total_number)

OM_private_object original,
OM_exclusions exclusions,
OM_type_list included_types,
OM_boolean local_strings,
OM_value_position initial_value,
OM_value_position limiting_value,
OM_public_object #copy,
OM_value_position #total_number

Arguments

Original

The private object, all or part of which you want to copy.

Exclusions

A list of zero or more values, each of which reduces the copy to a portion of the original. The exclusions apply to the attributes of the original object, but not to the attributes of its subobjects. This argument has one or more of the following values:

• OM_EXCLUDE_ALL_BUT_THESE_TYPES

  The copy includes descriptors of attributes of specified types only.

• OM_EXCLUDE_MULTIPLES

  The copy includes a single descriptor for each attribute having two or more values, instead of one descriptor for each value. Each such descriptor contains no attribute value, and the No-Value bit of the syntax component is set. If the attribute has values of two or more syntaxes, the descriptor identifies one of those syntaxes. Which syntax it identifies is unspecified.

• OM_EXCLUDE_ALL_BUT_THESE_VALUES

  The copy includes descriptors encompassing only values at specified positions within an attribute.

• OM_EXCLUDE_VALUES

  The copy includes a single descriptor for each attribute value, but the descriptor does not contain the value, and the No-Value bit of the syntax component is set.

• OM_EXCLUDE_SUBOBJECTS

  The copy includes a descriptor for each value which has a syntax of object. Each descriptor contains an object Handle for the original private subobject, instead of a public copy of the original private subobject. The Handle makes the private subobject accessible for use in OM function calls.

• OM_EXCLUDE_DESCRIPTORS

  The function does not return any descriptors, nor does it return a value in the Copy argument. The value of the Total Number argument gives the number of descriptors which would have otherwise been returned.

• OM_NO_EXCLUSIONS

  The copy contains descriptors and values for all attributes in the original.

  If you specify multiple exclusions, the Service applies the exclusions in the order in which they occur in the above list. If a portion of the object disappears after the Service applies an exclusion, the Service applies no further exclusions to that portion.

Included Types

The types of attributes that are to be included in the copy, provided they appear in the original. This argument must be present if you select the OM_EXCLUDE_ALL_BUT_THESE_TYPES exclusion, but must otherwise be set to null.

Local Strings

If you set this argument to OM_TRUE, you indicate to the Service that it must translate all String(*) values included in the Copy into the local character set representation. This translation may cause the loss of some information.

Initial Value

The position within each attribute of the first value to be included in the copy. This argument must be present if you select the OM_EXCLUDE_ALL_BUT_THESE_VALUES exclusion, but must otherwise be set to null. If the value of Initial Value is OM_ALL_VALUES, or if it exceeds the number of values present in an attribute, the Service takes Initial Value to be equal to the number of values present in the attribute.

Limiting Value

The position in each attribute that is one element beyond the position of the last value included in the copy. This argument must be present if you select the OM_EXCLUDE_ALL_BUT_THESE_VALUES exclusion, but must otherwise be set to null. If the value of Limiting Value is less than that of Initial Value, the Service does not put any values in the copy. If the value of Limiting Value is OM_ALL_VALUES, or if it exceeds the number of values present in an attribute, then the Service takes Limiting Value to be equal to the number of values present in the attribute.

Copy

An exact but independent copy of the original. The Service returns this argument if both the following conditions are true:

• The Return Code of the function is OM_SUCCESS
  
• You do not specify the OM_EXCLUDE_DESCRIPTORS exclusion
  

  You do not have to allocate any space to the copy. If you alter any portion of this space, you may affect the behaviour of the Service.

Total Number

The number of attribute descriptors in the copy. This does not include descriptors in any subobjects of the copy. If you specify the OM_EXCLUDE_DESCRIPTORS exclusion, then there is no copy. Therefore, the value in Total Number is the number of descriptors that the Service would return if you did not specify OM_EXCLUDE_DESCRIPTORS (applying any other exclusions that you specified). Total Number excludes the special descriptor that signals the end of a public object, OM_NULL_DESCRIPTOR.

Description

This function creates a new public object, the copy, which is an exact but independent copy of an existing private object, the original.

When using this function, you can request certain exclusions, each of which reduces the copy to a portion of the original.

When this function is used with the X.400 API, one exclusion is requested implicitly. For each attribute value in the original that is a string exceeding 1024 bytes in length, the copy includes a descriptor that omits the elements, but specifies the length of the string. In this case, the following applies:

• The syntax of the descriptor has its Long-String bit set.

• The value of the descriptor is a string whose elements component is set to OM_ELEMENTS_UNSPECIFIED, but whose length component does specify the correct length.

  Note that if you are using the OM API with the X.400 API, you can read long strings using om_read.

  When used with the X.500 API, there is no limit to the length of string returned by om_get, and so this exclusion is not requested implicitly.

Examples

The following example shows om_get being used to make a public copy of an object of the X.400 API MH class Local Per-recipient NDR (ndr) containing the attribute MH_T_TEMPORARY.

OM_private_object ndr;
OM_public_object  ndr_copy;
OM_value_position total_number;
OM_type  
 temporary[] = {MH_T_TEMPORARY, OM_NO_MORE_TYPES};
              	                                        
     result = om_get (ndr,
                             /* object to be copied */
                      OM_EXCLUDE_ALL_BUT_THESE_TYPES,
                             /* include attributes of specified types */
                      temporary,
                             /* type to be included */
                      OM_FALSE,0,0,
                             /* no translation into local char set */
                      ndr_copy,
                             /* the copy */
                      &total_number);
                             /* number of attributes copied */

The example shows the use of the exclusion exclude-all-but-these-types. The public copy (ndr_copy) includes a descriptor representing the attribute MH_T_TEMPORARY (temporary), and its single value.

The following example shows how to use the Get function to work down a nested structure, getting one level at a time. The structure is a Result object returned from a call to the X.500 API DS Read function. Note that this code example uses the dsX_trace_object function, which is not available in Version 1.0 of the MAILbus 400 API.

/* declare an OM-type-list structure and variables to hold pointers to the 
   entry, DS_object and RDNS subobjects: 
   */
OM_integer        desc_count;
OM_object         read_result;
OM_type           included_types[2];
OM_public_object  spub_entry;
OM_public_object  spub_DS_object;
OM_public_object  spub_RDNS;
/* and set up the OM attributes you want to get first: */
          included_types[0] = DS_ENTRY;
          included_types[1] = OM_NO_MORE_TYPES;
 

/* now get only a pointer to the first subobject, the entry */
  om_status = om_get(read_result, 
		     OM_EXCLUDE_ALL_BUT_THESE_TYPES+OM_EXCLUDE_SUBOBJECTS,
                    included_types, OM_FALSE, 0, OM_ALL_VALUES,
                    &spub_entry, &desc_count);
 

/* the object spub_entry now contains only the 
   OM-descriptor for an entry-information object */
dsX_trace_object(spub_entry);
* Now use OM_get() again to extract the DN of the object */
         included_types[0] = DS_OBJECT_NAME;
         om_status = om_get(spub_entry->value.object.object,
                     OM_EXCLUDE_ALL_BUT_THESE_TYPES+OM_EXCLUDE_SUBOBJECTS,
                    included_types, OM_FALSE, 0, OM_ALL_VALUES,
                    &spub_DS_object, &desc_count);
dsX_trace_object(spub_DS_object);
   

/* Next, use OM_get() again to extract the RDNS */
         included_types[0] = DS_RDNS;
         om_status = om_get(spub_DS_object->value.object.object,
                     OM_EXCLUDE_ALL_BUT_THESE_TYPES+OM_EXCLUDE_SUBOBJECTS,
                    included_types, OM_FALSE, 0, OM_ALL_VALUES,
                    &spub_RDNS, &desc_count);
 

dsX_trace_object(spub_RDNS);
/* Now loop around each RDN, extract a pointer to the AVAS 
   and then extract the attribute type and value
   */
   ...
/* When finished, remember to delete all the objects you have used */

om_instance - Determines whether an object is an instance of a particular class or of one of its subclasses.

Syntax

OM_return_code om_instance(subject, class, instance)

Argument	Data Type	Access
subject	OM_object	read
class	OM_object_identifier	read
instance	OM_boolean	write
return_code	OM_return_code

C Binding

OM_return_code om_instance(subject, class, instance)

OM_object subject,
OM_object_identifier class,
OM_boolean #instance

Arguments

Subject

The object whose class you want to verify.

Class

The class against which you want to verify the subject.

Instance

The Service sets this argument to OM_TRUE if the subject is an instance of the class you specified, and OM_FALSE if the subject is not. The Service returns this argument if the Return Code of the function is OM_SUCCESS.

Description

This function enables you to determine whether an object is an instance of a specified class or of any of the subclasses of that class.

Note that it is possible to determine an object's class by using programming constructs to inspect the object, if it is public, or by using om_get, if it is private. The advantage of the Instance function is that it indicates whether the object is an instance of the specified class, even when it is also a subclass of the specified class.

Return Values

Examples

The following example shows how to check a private object, an_object, to see if it is an instance of the X.400 Message Handling class Submitted Message RD. inst_true is the return argument. The function returns OM_TRUE in the parameter if the object is an instance of the class Submitted Message RD, or its subclass Message RD.

OM_private_object   sub_mess_rd;
OM_return_code      result;
OM_boolean          inst;
     result = om_instance (an_object,
                                /* object to be checked */
                           MH_C_SUBMITTED_MESSAGE_RD,
                                /* class to be checked against */
                           &inst);
                                /* result */
     if (inst == OM_TRUE)
              /* the object is an instance of specified class */
     else
              /* the object is not an instance of specified class */

om_put - Places copies of the attribute values of a private or public object into a private object.

Syntax

OM_return_code om_put(destination, modification, source, included_types, initial_value, limiting_value)

Argument	Data Type	Access
destination	OM_private_object	read
modification	OM_modification	read
source	OM_object	read
included_types	OM_type_list	read
initial_value	OM_value_position	read
limiting_value	OM_value_position	read
return_code	OM_return_code

C Binding

OM_return_code om_put (destination, modification, source, included_types, initial_value, limiting_value)

OM_private_object destination,
OM_modification modification,
OM_object source,
OM_type_list included_types,
OM_value_position initial_value,
OM_value_position limiting_value

Arguments

Destination

The object into which you want to put attribute values. This function does not affect the class of the destination.

Modification

A list of modifications to the attributes selected for copying. The modifications you request determine how the function modifies the destination object with the attributes, that is, where it puts them.

The Modification argument can have one of the following values:

• OM_INSERT_AT_BEGINNING

  The Service inserts the source values before all existing destination values. This does not affect the existing destination values.

• OM_INSERT_AT_CERTAIN_POINT

  The Service inserts the source values before the value at a specified position in the destination attribute. This does not affect the existing destination values.

• OM_INSERT_AT_END

  The Service inserts the source values after all existing destination values. This does not affect the existing destination values.

• OM_REPLACE_ALL

  The Service replaces any destination values with the source values, and discards the original destination values.

• · OM_REPLACE_CERTAIN_VALUES

  The Service replaces the values at specified positions in the destination attribute with values from the source. The Service discards the original destination attribute values at those positions.

Source

The object from which you want to copy attribute values. This function ignores the class of the source.

Included Types

The types of attributes that should be copied to the destination, if they appear in the source. If you do not specify a value for this argument, the Service copies all attributes from the source to the destination.

Initial Value

You need to pass a value for this argument when you select the OM_INSERT_AT_CERTAIN_POINT modification or the OM_REPLACE_CERTAIN_VALUES modification. The following table shows what the Initial Value argument represents in each of these cases.

Modification

Meaning of the Initial Value Argument

insert-at-certain-points

The position within each destination attribute at which the Service should insert source values

replace-certain-values

The first value that the Service should replace

If you give this argument a value that is greater than the number of values present in a destination attribute, or if you use the value OM_ALL_VALUES, the Service takes Initial Value to be equal to the number of values present in the destination attribute.

Limiting Value

You need to pass a value for this argument when you select the OM_REPLACE_CERTAIN_VALUES modification. The argument specifies the position within each destination attribute that is one beyond that of the last value to be replaced. The value of Limiting Value must be greater than that of Initial Value.

If you give this argument a value that is greater than the number of values present in a destination attribute, or if you use the value OM_ALL_VALUES, the Service takes Limiting Value to be equal to the number of values present in the destination attribute.

Description

This function places in one private object, the destination, copies of the attribute values of another object, the source. The source can be a public or private object.

You must specify that the Service does one of the following:

• Replace all the values in the destination with values from the source.
  
• Replace specified values in the destination with values from the source.
  
• Insert values from the source in a particular position in the destination.
  

Only use om_put to copy attributes from the source that occur in the definition of the class to which the destination belongs.

The Service first converts all string values that are in the local representation into the nonlocal representation for that syntax.

There is no attribute of type C in the source object. The destination object therefore contains no attributes of this type, even though type C is specified in the Included Types argument.

The destination object contains an attribute, D, which is not affected by om_put.

Return Values

Examples

The following example shows how to put the values from a public object into the private object.

result = om_put (modification,
                             /* destination object */
                      OM_REPLACE_ALL,
                             /* type of modification */
                      pub_mod,
                             /* source of values to be put */ 
                      0,0,0);
                             /* include all attributes, all positions */

om_read - Reads a segment of a string from a private object.

Syntax

OM_return_code om_read(subject, type, value_position, local_string, string_offset, elements)

Argument	Data Type	Access
subject	OM_private_object	read
type	OM_type	read
value_position	OM_value_position	read
local_string	OM_boolean	read
string_offset	OM_string_length	read-write
elements	OM_string	write
return_code	OM_return_code

C Binding

OM_return_code om_read(subject, type, value_position, local_string, string_offset, elements)

OM_private_object subject,
OM_type type,
OM_value_position value_position,
OM_boolean local_string,
OM_string_length #string_offset,
OM_string #elements

Arguments

Subject

The private object from which you want to read the segment.

Type

The type of the attribute containing the value that youwant to read.

Value Position

The position in a multivalued attribute of the value that you want to read.

Local String

If you set this argument to OM_TRUE, the Service translates the attribute segment into the local character set. This translation may result in the loss of some information.

String Offset

If provided by the Client, this argument denotes the position within the attribute value of the first element that you want to read. If you give this argument a value that exceeds the number of elements present in the attribute value, the Service takes the argument to be equal to the number of elements present in the attribute value.

If returned by the Service, this argument denotes the position of the next segment within the attribute value, as an offset in octets. If the segment just read was the last in the string, then this argument is set to zero. The result is present only if the Return Code result is OM_SUCCESS.

The value indicating the next position can be specified in a subsequent call as the position to start from, enabling sequential reading of the segments in a string value.

Elements

A space into which the Service returns the segment of the attribute value that you want to read. This argument is a string with two components, Elements and Length.

The following shows the initial values that you should give to these components:

String Component	Initial Value
Elements	Pointer to a buffer
Length	The number of octets required to contain the segment that the function returns

You must make sure that the buffer is big enough to hold the number of octets.

The Service modifies the Elements argument. Each element that the function returns becomes an element in the string. The string's length becomes the number of octets actually required to hold the segment read (which may be smaller than the length initially specified.)

If the value of Local Strings is OM_TRUE, the final length of the string may not be the same as the initial length of the string. This depends on the characteristics of the translation into the local character set.

Description

The function enables you to read a long string without requiring the Service to place a copy of the entire string in memory.

Return Values

Examples

The following example shows the reading of a string value from an object of the IM class IA5 Text Body Part (body_part). The Service will return 0 when there is no more text left to read.

OM_private_object   body_part;
OM_return code      result;
OM_string           message;
OM_string_length    offset;
char                read_buffer[1024];
message.length = 1024
message.elements = read_buffer;
offset = 0;
     result = om_read (body_part,
                             /* object containing value to be read */
                       IM_TEXT,
                             /* attribute from which value is to be read */
                       0,
                             /* position of value to read from */
                       OM_FALSE,
                             /* no translation into local char set */
                       &offset,
                             /* string offset of segment to be read */ 
                       &message);
                             /* the string read from the value */

The type of the attribute read is IM_TEXT. The first element of the first value in this attribute is read into message.

om_remove(3xom)

om_remove - Removes and discards specified values of an attribute of a private object.

Syntax

OM_return_code om_remove(subject, type, initial_value, limiting_value)

Argument	Data Type	Access
subject	OM_private_object	read
type	OM_type	read
initial_value	OM_value_position	read
limiting_value	OM_value_position	read
return_code	OM_return_code

C Binding

OM_return_code om_remove(subject, type, initial_value, limiting_value) OM_private_object subject,

OM_type type,
OM_value_position initial_value,
OM_value_position limiting_value

Arguments

Subject

The private object from which you want to remove attribute values. The function does not affect the class of the subject.

Type

The type of the attribute from which you want to remove values. The type must not be OM_CLASS.

Initial Value

The position within the attribute of the first value to be removed.

If the value of Initial Value is OM_ALL_VALUES, or if it exceeds the number of values present in the attribute, the Service takes this argument to be equal to the number of values present in the attribute.

Limiting Value

The position within the attribute one beyond that of the last value to be removed. If this argument is less than theInitial Value argument, no values are removed.

If the value of Limiting Value is OM_ALL_VALUES, or if the value exceeds the number of values present in an attribute, the Service takes this argument to be equal to thenumber of values present in the attribute.

Description

This function removes and discards particular values of an attribute of a private object, the subject. If no values remain in an attribute after removal of the values you specify, the Service removes the attribute. If one of the values you specify is a subobject, the Service removes that value, and then applies om_delete to make the subobject inaccessible.

Return Values

Examples

The first example shows a single value being removed from a private object of MH class Message (message). MH_T_LATEST_DELIVERY_TIME is the attribute type whose value is removed. This attribute has one value. The function therefore removes the value and deletes the attribute.

The second example shows a range of values being removed from a private object of the X.500 class Entry-Information-Selection (select_info). DS_ATTRIBUTES_SELECTED is the attribute type whose values are removed. If this attribute has five values (positions 0 to 4), then this function removes the second, third and fourth values.

OM_private_object    message;
OM_return_code       result;
     result = om_remove (message,
                             /* object from which to remove value */
                         MH_T_LATEST_DELIVERY_TIME,
                             /* attribute to remove */
                         0,1));
                             /* position of single value to remove */

OM_private_object    select_info;
OM_return_code       result;
     result = om_remove (select_info,
                             /* object from which to remove value */
                         DS_ATTRIBUTES_SELECTED,
                             /* attribute to remove */
                         1,4));
                             /* range of values to remove */

om_write - Writes a segment of a string to an attribute in a private object.

Syntax

OM_return_code om_write(subject, type, value_position, syntax, string_offset, elements )

Argument	Data Type	Access
subject	OM_private_object	read s
type	OM_type	read
value_position	OM_value_position	read
syntax	OM_syntax	read
string_offset	OM_string_length	read-write
elements	OM_string	read
return_code	OM_return_code

C Binding

OM_return_code om_write(subject, type, value_position, syntax, string_offset, elements )

OM_private_object subject,
OM_type type,
OM_value_position value_position,
OM_syntax syntax,
OM_string_length #string_offset,
OM_string elements

Arguments

Subject

The object into which you want to write the string segment.

Type

The type of the attribute to which you want to write the string segment.

Value Position

In a multi-valued attribute, the position of the value in which you want to place the string. This argument must have a positive value, and it must not exceed the number of values present in the attribute. If it equals the number of values present, the Service inserts the segment at the end of the attribute as a new value.

Syntax

If you are writing a new value to an attribute, identify in this argument the syntax that you want the new value to have. It must be a permissible syntax for the attribute to which you are writing. To check that the syntax is permissible, consult the definition of the class of which the subject is an instance.

If you are overwriting or amending a value that is already present in the subject, the Service preserves the syntax of that value, so you can supply a null value.

String Offset

If supplied by the Client, this argument denotes the position, p, within the attribute value at which you want the first segment written. The position is specified as an offset in octets relative to the start of the string value.

If this argument has a value greater than the number of elements in the attribute value, the Service takes the argument to be equal to that number.

If returned by the Service, this argument denotes the position of the end of the last segment written. The position is specified as an offset in octets relative to the start of the string value.

The value returned by the Service as the position of the end of the last segment written can be specified as the position from which to start writing the next segment. This enables you to write segments sequentially.

Elements

The string segment that you want to write to the attribute, n elements in number. Copies of these elements occupy the positions, within the value, in the interval between p and (p) + n. The function discards any elements already in or beyond these positions.

The elements are bits, octets, or characters, depending on the nature of the string.

Description

This function writes a segment of an attribute value in a private object, the subject. The segment that the Service writes becomes the last segment in the attribute value. The function discards any segments in the attribute value whose offsets are equal to or greater than the offset specified in String Offset.

If the segment that the Service writes is in the local representation, the Service converts it to the nonlocal representation. This can result in loss of information and may result in a different number of elements than that specified.

Return Values

Examples

The following example shows a string segment being written to an object of the Interpersonal Messaging (IM) class IA5 Text Body Part (body_part).

OM_return_code result;
OM_value_position position;
input_string = OM_STRING ("Text Body");
position = 0;
     result = om_write (body_part,
                             /* object containing string segment */ 
                        IM_TEXT,
                             /* attribute containing string segment */
                        0,
                             /* position of value to write to */
                        OM_S_IA5_STRING,
                             /* syntax of value */
                        &position,
                             /* starting position for current/next string */

                        input_string);
                             /* string segment to be written */

In this example the type of attribute being written to is IM_TEXT; the 
position of the value being written to is 0; the syntax of the value is 
OM_S_IA5_STRING.

[Previous] [Next] [Contents]

To make comments or ask for help, contact support@entegrity.com.

Copyright © 2001 Entegrity Solutions Corporation & its subsidiaries.

Copyright © 1998-2001 Compaq Computer Corporation.

All rights reserved.