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

Synopsis

OM _return_code om_decode(encoding, original)

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

Possible return values are as follows:

Return	Description
OM_SUCCESS	The function has completed its task successfully.
OM_ENCODING_INVALID	The value of the Object Encoding is invalid.
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_RULES	There is an undefined rules identifier.
OM_NOT_AN_ENCODING	There is an object that is not an instance of the Encoding class.
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.
OM_WRONG_VALUE_LENGTH	There is an attribute with a value that violates the value length constraints in force.
OM_WRONG_VALUE_MAKEUP	There is an attribute with a value that violates a constraint of its syntax.
OM_WRONG_VALUE_NUMBER	There is an attribute with a value that violates the value number 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 with an illegal type.

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

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

Synopsis

OM _return_code om_delete(subject)

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

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_OBJECT	You have specified a nonexistent object, or an invalid Handle for an object.
OM_NO_SUCH_SYNTAX	There is an undefined syntax identifier.
OM_NO_SUCH_TYPE	There is an undefined type identifier.
OM_NOT_THE_SERVICES	There is an object that is client generated when it should be service generated or private.
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 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 */

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

Synopsis

OM _return_code om_encode(original, rules, encoding)

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

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_RULES	There is an undefined rules identifier.
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.

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

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

Synopsis

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

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 behavior 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, so this exclusion is not requested implicitly.

Return Values

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_EXCLUSION	There is an undefined exclusion identifier.
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_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_WRONG_VALUE_SYNTAX	There is an attribute value with an illegal syntax.
OM_WRONG_VALUE_TYPE	There is an attribute value with an illegal type.

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