This chapter describes the following aspects of the XOM service interface:
See Chapter 7 for examples of using the XOM interface.
The DCE XOM implementation conforms to the following specification:
X/Open CAE Specification, OSI-Abstract-Data Manipulation (XOM) (November 1991)
The following apply to the DCE XOM implementation:
| Data Type | Description |
|---|---|
| OM_boolean | Type definition for a Boolean data value. |
| OM_descriptor | Type definition for describing an attribute type and value. |
| OM_enumeration | Type definition for an Enumerated data value. |
| OM_exclusions | Type definition for the exclusions parameter for om_get(). |
| OM_integer | Type definition for an Integer data value. |
| OM_modification | Type definition for the modification parameter for om_put(). |
| OM_object | Type definition for a handle to either a private or a public object. |
| OM_object_identifier | Type definition for an Object Identifier data value. |
| OM_private_object | Type definition for a handle to an object in an implementation-defined, or private, representation. |
| OM_public_object | Type definition for a defined representation of an object that can be directly interrogated by a programmer. |
| OM_return_code | Type definition for a value returned from all OM functions, indicating either that the function succeeded or why it failed. |
| OM_string | Type definition for a data value of one of the String syntaxes. |
| OM_syntax | Type definition for identifying a syntax type. |
| OM_type | Type definition for identifying an OM attribute type. |
| OM_type_list | Type definition for enumerating a sequence of OM attribute types. |
| OM_value | Type definition for representing any data value. |
| OM_value_length | Type definition for for indicating the number of bits, octets, or characters in a string. |
| OM_value_position | Type definition for designating a particular location within a String data value. |
| OM_workspace | Type definition for identifying an application-specific API that implements OM, such as directory or message handling. |
Some data types are defined in terms of the following intermediate data types, whose precise definitions in C are defined by the system:
The positive and negative integers that can be represented in 16 bits
The positive and negative integers that can be represented in 16 bits
The positive and negative integers that can be represented in 32 bits
The nonnegative integers that can be represented in 16 bits
The nonnegative integers that can be represented in 16 bits
The nonnegative integers that can be represented in 32 bits
Note: The OM_sint and OM_uint data types are defined by the range of integers they must accommodate. As typically declared in the C interface, they are defined by the range of integers permitted by the host machine's word size. The latter range, however, always encompasses the former.
The type definitions for these data types are as follows:
typedef int OM_sint; typedef short OM_sint16; typedef long int OM_sint32; typedef unsigned OM_uint; typedef unsigned short OM_uint16; typedef long unsigned OM_uint32;
typedef OM_uint32 OM_boolean;
A data value of this data type is a Boolean; that is, either FALSE or TRUE.
FALSE (OM_FALSE) is indicated by 0 (zero). TRUE is indicated by any other integer, although the symbolic constant OM_TRUE refers to the integer 1 specifically.
typedef struct OM_descriptor_struct
{
OM_type type;
OM_syntax syntax;
union OM_value_union value;
} OM_descriptor;
Note: Other components are encoded in high bits of the syntax member.
See the OM_value data type in Section 18.2.16 or the xom.h(4xom) reference page in the OSF DCE Application Development Reference for a description of the OM_value_union structure.
A data value of this type is a descriptor, which embodies an attribute value. An array of descriptors can represent all the values of all the attributes of an object, and is the representation called OM_public_object. A descriptor has the following components:
An OM_type data type. It identifies the data type of the attribute value.
An OM_syntax data type. It identifies the syntax of the attribute value. Components 3 to 7 (that is, the components long-string through private that follow) are encoded in the high-order bits of this structure member. Therefore, the syntax always needs to be masked with the constant OM_S_SYNTAX. For example:
my_syntax = my_public_object[3].syntax &
OM_S_SYNTAX;
my_public_object[4].syntax =
my_syntax + (my_public_object[4].syntax &
~OM_S_SYNTAX);
An OM_boolean data type. It is OM_TRUE only if the descriptor is a service-generated descriptor and the length of the value is greater than an implementation-defined limit.
This component occupies bit 15 (0x8000) of the syntax and is represented by the constant OM_S_LONG_STRING.
An OM_boolean data type. It is OM_TRUE only if the descriptor is a service-generated descriptor and the value is not present because OM_EXCLUDE_VALUES or OM_EXCLUDE_MULTIPLES is set in om_get().
This component occupies bit 14 (0x4000) of the syntax and is represented by the constant OM_S_NO_VALUE.
An OM_boolean data type, significant only if the syntax is one of the string syntaxes. It is OM_TRUE only if the string is represented in an implementation-defined local character set. The local character set may be more amenable for use as keyboard input or display output than the nonlocal character set, and it can include specific treatment of line termination sequences. Certain interface functions can convert information in string syntaxes to or from the local representation, which may result in a loss of information.
This component occupies bit 13 (0x2000) of the syntax and is represented by the constant OM_S_LOCAL_STRING. The DCE XOM implementation does not support translation of strings to a local character set.
An OM_boolean data type. It is OM_TRUE only if the descriptor is a service-generated descriptor and the first descriptor of a public object, or the defined part of a private object (see the XOM reference pages).
This component occupies bit 12 (0x1000) of the syntax and is represented by the constant OM_S_SERVICE_GENERATED.
An OM_boolean data type. It is OM_TRUE only if the descriptor in the service-generated public object contains a reference to the handle of a private subobject, or in the defined part of a private object.
Note: This applies only when the descriptor is a service-generated descriptor. The client need not set this bit in a client-generated descriptor that contains a reference to a private object.In the C interface, this component occupies bit 11 (0x0800) of the syntax and is represented by the constant OM_S_PRIVATE.
An OM_value data type. It identifies the attribute value. "OM"
The OM_enumeration data type is used to indicate an Enumerated data value. Its C declaration is as follows:
typedef OM_sint32 OM_enumeration;
A data value of this data type is an attribute value whose syntax is OM_S_ENUMERATION.
typedef OM_uint OM_exclusions;A data value of this data type is an unordered set of one or more values, all of which are distinct. Each value indicates an exclusion, as defined by om_get(), and is chosen from the following set:
Alternatively, the single value OM_NO_EXCLUSIONS can be chosen; this selects the entire object.
Each value except OM_NO_EXCLUSIONS is represented by a distinct bit. The presence of the value is represented as 1; its absence is represented as 0 (zero). Thus, multiple exclusions are requested by ORing the values that indicate the individual exclusions.
typedef OM_sint32 OM_integer;
A data value of this data type is an attribute value whose syntax is OM_S_INTEGER.
typedef OM_uint OM_modification;A data value of this data type indicates a kind of modification, as defined by om_put(). It is chosen from the following set:
typedef struct OM_descriptor_struct *OM_object;
A data value of this data type represents an object, which can be either public or private. It is an ordered sequence of one or more instances of the OM_descriptor data type. See the OM_private_object and OM_public_object data types for restrictions on that sequence (Sections 18.2.9 and 18.2.10, respectively).
typedef OM_string OM_object_identifier;
A data value of this data type contains an octet string that comprises the contents octets of the BER encoding of an ASN.1 object identifier.
Object identifiers are defined in the appropriate header files, with the definition identifier having the prefix OMP_O_ followed by the variable name for the object identifier. The constant itself provides the hexadecimal value of the object identifier string.
OM_OID_DESC(type, OID_name)
It sets the type component to that given, sets the syntax component to OM_S_OBJECT_IDENTIFIER_STRING, and sets the value component to the specified object identifier.
The following macro initializes a descriptor to mark the end of a client-allocated public object:
OM_NULL_DESCRIPTOR
For each class there is a global variable of type OM_STRING with the same name; for example, the External class has a variable called OM_C_EXTERNAL. This is also the case for other object identifiers; for example, the object identifier for BER rules has a variable called OM_BER. This global variable can be supplied as a parameter to functions when required.
This variable is valid only when it is exported by an OM_EXPORT macro and imported by an OM_IMPORT macro in the compilation units that use it. This variable cannot form part of a descriptor, but the value of its length and elements components can be used. The following code fragment provides examples of the use of the macros and constants.
/* Examples of the use of the macros and constants */
#include <xom.h>
OM_IMPORT(OM_C_ENCODING)
OM_IMPORT(OM_CANONICAL_BER)
/* The following sequence must appear in just one compilation
* unit in place of the above:
*
* #include <xom.h>
*
* OM_EXPORT(OM_C_ENCODING)
* OM_EXPORT(OM_CANONICAL_BER)
*/
main()
{
/* Use #1 - Define a public object of class Encoding
* (Note: xxxx is a Message Handling class which can be
* encoded)
*/
OM_descriptor my_public_object[] = {
OM_OID_DESC(OM_CLASS, OM_C_ENCODING),
OM_OID_DESC(OM_OBJECT_CLASS, MA_C_xxxx),
{ OM_OBJECT_ENCODING, OM_S_ENCODING_STRING, some_BER_value },
OM_OID_DESC(OM_RULES, OM_CANONICAL_BER),
OM_NULL_DESCRIPTOR
};
/* Use #2 - Pass class Encoding as a parameter to om_instance()
*/
return_code = om_instance(my_object, OM_C_ENCODING,
&boolean_result);
}
typedef OM_object OM_private_object;
A data value of this data type is the designator or handle to a private object. It comprises a single descriptor whose type component is OM_PRIVATE_OBJECT and whose syntax and value components are unspecified.
Note: The descriptor's syntax and value components are essential to the service's proper operation with respect to the private object.
typedef OM_object OM_public_object;
A data value of this data type is a public object. It comprises one or more (ususally more) descriptors, all but the last of which represent values of attributes of the object.
The descriptors for the values of a particular attribute with two or more values are adjacent to one another in the sequence. Their order is that of the values they represent. The order of the resulting groups of descriptors is unspecified.
Since the Class attribute specific to the Object class is represented among the descriptors, it must be represented before any other attributes. Regardless of whether or not the Class attribute is present, the syntax field of the first descriptor must have the OM_S_SERVICE_GENERATED bit set or cleared appropriately.
The last descriptor signals the end of the sequence of descriptors. The last descriptor's type component is OM_NO_MORE_TYPES and its syntax component is OM_S_NO_MORE_SYNTAXES. The last descriptor's value component is unspecified.
typedef OM_uint OM_return_code;
A data value of this data type is the integer in the range 0 to 216 that indicates an outcome of an interface function. It is chosen from the set specified in Section 18.4.
Integers in the narrower range 0 to 215 are used to indicate the return codes they define.
typedef OM_uint32 OM_string_length;
typedef struct {
OM_string_length length;
void *elements;
} OM_string;
#define OM_STRING(string)\
{ (OM_string_length)(sizeof(string)-1), (string) }
A data value of this data type is a string; that is, an instance of a String syntax. A string is specified either in terms of its length or whether or not it terminates with NULL. A string has the following components:
The number of octets by means of which the string is represented, or the OM_LENGTH_UNSPECIFIED value if the string terminates with NULL.
The string's elements. The bits of a bit string are represented as a sequence of octets (see Figure 18-1). The first octet stores the number of unused bits in the last octet. The bits in the bit string, commencing with the first bit and proceeding to the trailing bit, are placed in bits 7 to 0 of the second octet. These are followed by bits 7 to 0 of the third octet, then by bits 7 to 0 of each octet in turn, followed by as many bits as are required of the final octet, commencing with bit
The service supplies a string value with a specified length. The client can supply a string value to the service in either form, either with a specified length or terminated with NULL.
The characters of a character string are represented as any sequence of octets permitted as the primitive contents octets of the BER encoding of an ASN.1 type value. The ASN.1 type defines the type of character string. A 0 (zero) value character follows the characters of the character string, but is not encompassed by the length component. Thus, depending on the type of character string, the 0 (zero) value character can delimit the characters of the character string.
The OM_STRING macro is provided for creating a data value of this data type, given only the value of its elements component. The macro, however, applies to octet strings and character strings, but not to bit strings.
typedef OM_uint16 OM_syntax;
A data value of this data type is an integer in the range 0 to 29 that indicates an individual syntax or a set of syntaxes taken together.
The data value is chosen from among the following:
Integers in the narrower range 0 to 29 are used to indicate the syntaxes they define. The integers in the range 29 to 210 are reserved for vendor extensions. Wherever possible, the integers used are the same as the corresponding ASN.1 universal class number.
typedef OM_uint16 OM_type;
A data value of this data type is an integer in the range 0 to 216 that indicates a type in the context of a package. However, the following values in Table 18-2 are assigned meanings by the respective data types.
| Value | Data Type |
|---|---|
| OM_NO_MORE_TYPES@OM_type_list | |
| OM_PRIVATE_OBJECT@OM_private_object |
Integers in the narrower range 0 to 215 are used to indicate the types they define.
The OM_type_list data type is used to enumerate a sequence of OM attribute types. Its C declaration is as follows:
typedef OM_type *OM_type_list;
A data value of this data type is an ordered sequence of zero or more type numbers, each of which is an instance of the OM_type data type.
An additional data value, OM_NO_MORE_TYPES, follows and thus delimits the sequence. The C representation of the sequence is an array.
typedef struct {
OM_uint32 padding;
OM_object object;
} OM_padded_object;
typedef union OM_value_union {
OM_string string;
OM_boolean boolean;
OM_enumeration enumeration;
OM_integer integer;
OM_padded_object object;
} OM_value;
Note: The first type definition (in particular, its padding component) aligns the object component with the elements component of the string component in the second type definition. This facilitates initialization in C.The identifier OM_value_union is defined for reasons of compilation order. It is used in the definition of the OM_descriptor data type.
A data value of this data type is an attribute value. It has no components if the value's syntax is OM_S_NO_MORE_SYNTAXES or OM_S_NO_VALUE. Otherwise, it has one of the following components:
The value if its syntax is OM_S_INTEGER
The value if its syntax is OM_S_OBJECT
Note: A data value of this data type is only displayed as a component of a descriptor. Thus, it is always accompanied by indicators of the value's syntax. The latter indicator reveals which component is present.
typedef OM_uint32 OM_value_length;
A data value of this data type is an integer in the range 0 to 232 that represents the number of bits in a bit string, octets in an octet string, or characters in a character string.
Note: This data type is not used in the definition of the interface. It is provided for use by client programmers for defining attribute constraints.
typedef OM_uint32 OM_value_position;
A data value of this data type is an integer in the range 0 to 232-1 that indicates the position of a value within an attribute. However, the value OM_ALL_VALUES has the meaning assigned to it by om_get().
The OM_workspace data type is used to identify an application-specific API that implements OM; for example, directory or message handling. Its C declaration is as follows:
typedef void *OM_workspace;
A data value of this data type is the designator or handle for a workspace.
| 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<() | Not supported by the DCE XOM interface; it returns an OM_FUNCTION_DECLINED error. |
| om_delete() | Deletes a private or service-generated object. |
| om_encode() | Not supported by the DCE XOM interface; it returns an OM_FUNCTION_DECLINED error. |
| 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. |
The purpose and range of capabilities of the service interface functions can be summarized as follows:
This function creates an independent copy of an existing private object and all its subobjects. The copy is placed in the workspace of the original object, or in another workspace specified by the DCE client.
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.
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 client to explicitly create instances of all classes, but rather only those indicated by a package's definition as having this property.
This function deletes a service-generated public object or makes a private object inaccessible.
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, values of multivalued attributes, copies of (not handles for) subobjects, or all attribute values. Excluding all attribute values reveals only an attribute's presence.
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 since it reveals that an object is an instance of a particular class, even if the object is an instance of a subclass of that class.
This function places or replaces in one private object copies of the attribute values of another public 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.
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. This function enables the client to read an arbitrarily long value without requiring that the service place a copy of the entire value in memory.
This function removes and discards particular values of an attribute of a private object. The attribute itself is removed if no values remain.
This function writes a segment of an attribute value to a private object. The value must be a string. The segment can first be converted from one syntax to another. The written segment becomes the value's last segment since 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.
Refer to the ERRORS section of the (3xom) references pages for a list of the errors that each function can return. For an explanation of these error codes please refer to the OSF DCE Problem Determination Guide.
The return code values are as follows: