Digital DCE for OpenVMS VAX and OpenVMS Alpha
Reference Guide


Previous Contents Index


om_decode(3xom)

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

Synopsis

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

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


om_delete(3xom)

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

Synopsis

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

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


om_encode(3xom)

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

Synopsis

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

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


om_get(3xom)

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)

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:

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:

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:


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


Previous Next Contents Index