om_get(3xom) — Subroutines
(c) Digital Equipment Corporation. 1994. All rights reserved.
Name
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)
original@OM_private_object@T{ read T} exclusions@OM_exclusions@T{ read T} included_types@OM_type_list@T{ read T} local_strings@OM_boolean@T{ read T} initial_value@OM_value_position@T{ read T} limiting_value@OM_value_position@T{ read T} copy@OM_public_object@T{ write T} total_number@OM_value_position@T{ write T} return_code@T{ OM_return_code T}
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.
Return Values
The function has completed its task successfully T} OM_FUNCTION_INTERRUPTED@T{ The function was aborted by external intervention T} OM_MEMORY_INSUFFICIENT@T{ There is not enough memory to complete the function T} OM_NETWORK_ERROR@T{ The Service cannot use the underlying network T} OM_NO_SUCH_EXCLUSION@T{ There is an undefined exclusion identifier T} OM_NO_SUCH_OBJECT@T{ You have specified a nonexistent object, or an invalid Handle for an object T} OM_NO_SUCH_TYPE@T{ There is an undefined type identifier T} OM_NOT_PRIVATE@T{ There is a public object where there should be a private object T} OM_PERMANENT_ERROR@T{ The Service encountered a permanent problem for which there is no defined error code T} OM_POINTER_INVALID@T{ An invalid pointer was supplied as a function argument T} OM_SYSTEM_ERROR@T{ The Service cannot use the operating system T} OM_TEMPORARY_ERROR@T{ The Service encountered a temporary problem for which there is no defined error code T} OM_WRONG_VALUE_SYNTAX@T{ There is an attribute value with an illegal syntax T} OM_WRONG_VALUE_TYPE@T{ There is an attribute value with an illegal type T}
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.
Exhibit 0-0.
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.
Exhibit 0-0.
/∗ 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 ∗/