| Previous | Contents | Index |
Determines whether an object is an instance of a particular class or of one of its subclasses.
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 |
OM_return_code om_instance(subject, class, instance)OM_object subject,
OM_object_identifier class,
OM_boolean #instance
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.
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.
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_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_SYNTAX There is an undefined syntax identifier. OM_NOT_THE_SERVICES An object is client generated rather than 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.
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 */
Places copies of the attribute values of a private or public object into a private object.
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 |
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
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.
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.
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_CLASS There is an undefined class identifier. OM_NO_SUCH_MODIFICATION There is an undefined modification identifier. 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_CONCRETE There is an abstract class where there should be a concrete class. OM_NOT_PRESENT An expected attribute value is missing. 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_VALUES_NOT_ADJACENT The descriptors for the values of a particular attribute are not adjacent. 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_POSITION The position specified for an attribute value is invalid. 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.
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 */
Reads a segment of a string from a private object.
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 |
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
Subject
The private object from which you want to read the segment.Type
The type of the attribute containing the value that you want 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 table 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.
The function enables you to read a long string without requiring the service to place a copy of the entire string in memory.
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_TYPE There is an undefined type identifier. OM_NOT_PRESENT An expected attribute value is missing. 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.
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.
| Previous | Next | Contents | Index |