Previous section.

UMA Measurement Layer Interface (MLI)
Copyright © 1997 The Open Group

Distributed UMA

This chapter defines specifications that will allow multiple UMA implementations to interoperate in a distributed environment. The UMA MLI interface supports the semantics of distributed data sources and destinations. Examples include the explicit use of a remote node name for sysid in umaCreate(), or references to (implicitly) remote UMADS areas.

The UMA Data Services Layer (DSL) provides this distributed support either directly or indirectly through the use of other service providers, but in any case certain DSL-to-DSL communications must be provided to implement these distributed functions. Ensuring interoperability between DSLs implemented by different vendors and on different hardware architectures will require common messages (logical protocol) and a common message transport. As the DSL is the coordinator of distributed services for UMA, the subsequent discussion will be focused on this functional layer.

For the purposes of this discussion, the local DSL is defined as being a UMA Data Services Layer that co-resides with a requesting MAP and MLI on a local host. A remote DSL will mean a responding Data Services Layer on a remote host that is to provide data to the requesting MAP and MLI via the local DSL. The remote host may or may not have MAPs executing, nor does it necessarily have a Data Capture Layer (meaning it may be a UMADS data provider only). The following figure illustrates the relationship:

Figure: Distributed UMA - Host/DSL Relationships

Message Transport

The default message transport for UMA is TCP/IP with a socket interface1. This choice is based on the need for both efficiency and reliability in transporting UMA control and data messages. To fulfill the requirements for connection establishment, and in- and out-of-band message delivery, the following ports are defined:

uma
The service name for a registered port used to establish connections between local and remote Data Service Layers. Once the connection is established, this port is used to deliver command messages, interval data messages, and those event data messages that are to be sent in-band.

The constant UMA_PORT, giving the port number for the service defined, is defined in the header file <mli.h>.

uma_high
A port used to deliver status messages and event data messages that are to be sent out-of-band. See the umaStart() call description in a previous section for a further discussion of in-band and out-of-band reporting. This port is dynamically assigned and is returned in the Connection ack and Reconnection ack subclass messages defined by the logical protocol. See Logical Message Protocol for further details.

Logical Buffer Sizing

When establishing a connection with a remote DSL, either as a consequence of a umaCreate() or a umaReconnect() call, a remote DSL uses a message buffer of size indicated by the "maximum buffer size to be used for communications" field in the Create or Reconnect control messages sent by the local DSL. This ensures compatible message exchanges governed by the socket interface.

Byte Ordering

In order to ensure that a remote DSL correctly interprets control and data messages sent by a local DSL host that has a different byte order data architecture for integers, the UMA message header contains indicator flags in field mh_flags to indicate the byte order of the host sending the message. These indicators are interpreted thus:

  1. If the indicator for the 16-bit byte order is on (a binary 1), each 16-bit component of an integer quantity has internal byte order from low to high with increasing addresses and its low order byte is coincident with the component starting address (little endian). Otherwise, the component has byte order high to low with its high order byte at the component starting address (big endian).

  2. If the indicator for the integer component order is on (a binary 1), the 16-bit components of the integer are ordered from low to high with increasing addresses; the start of the low order 16-bit component is coincident with the integer starting address. Otherwise, the 16-bit components are ordered from high to low with the start of the high order 16-byte component coincident with the integer starting address.

Furthermore, the default byte ordering for all integers or integer-based quantities in the UMA message header (including mh_flags itself) is network standard byte order. This is mandatory for the Create and Reconnect logical messages, and in these instances the byte ordering indicators in mh_flags represent the local DSL's preferred byte ordering for header content. In the Connection Acknowledement, the DSL server indicates the header byte order it will use for the Acknowledgement and for all subsequent messages.

Lastly, UMADS data is always transported to a local DSL with the same byte ordering as for the host on which it originated. This means that a receiving DSL will always see the same byte ordering regardless of the architecture of the platform that may be acting as a data server.

Message Buffering - Normal Priority Channel

Messages sent on the normal priority channel - uma - may be blocked with other messages in a single buffer for the purposes of efficient transmission.

A token called a seek number, a monotonically increasing integer, is included in the buffer. The seek number is increased with each umaSeek() call to reflect that a change is to take place in the MAP's (and the MLI's) notion of current time for the session. The seek number is provided so that both local and remote data buffers may be resynchronised after the repositioning. This resynchronisation consists of discarding data buffers with lower seek numbers. The normal priority channel buffer format is:

UMAUint4
Byte count of data in buffer in bytes not including this field

UMAUint8
Seek number

Message 1

Message 2

.

.

Message n

Message Buffering - High Priority Channel

Status messages and out-of-band condition messages from a source DSL are sent via the high priority channel, uma_high, and may be blocked with other messages in a single buffer. The buffer format is as follows:

UMAUint4
Byte count of data in buffer in bytes not including this field

Message 1

Message 2

.

.

Message n

Logical Message Protocol

Messages sent from DSL to DSL include both control and data messages. Control messages include:

  1. Requests resulting from calls to an MLI to be acted on by a remote DSL (class Command, subclass depends on MLI call, eg. subclass 'Seek')

  2. Status messages from a remote DSL for the local DSL (for example, class Connection Status)

  3. Condition messages from a remote DSL to be forwarded to a local MLI/MAP (class Condition, subclass depends on type, for example Informational, Severe)

Data messages from a remote DSL are sent to the local DSL, and depending on the MLI session destination, may either be written to UMADS or private files by the local DSL or may be forwarded to a MAP/MLI.

The general structure of UMA control and data messages has been described in a previous section. The remainder of this section describes specific messages used for DSL-to-DSL communications organised by the types defined above.

The following table summarises the relationship of MLI calls, messages emitted by the MLI's associated DSL, and remote DSLs in a distributed environment.

MLI Call Local DSL Remote DSL Notes
  'Command' Message Status/Condition/Data  
  Request Subclass Response Subclass  
umaClose() Close - -
umaCreate() Create Connection Ack Synchronous response
umaGetAttr() - - -
umaGetMsg() Request Data Buffer (Data, Condition, Status) Request to replenish buffer
umaGetReason() - - -
umaReconnect() Reconnect Reconnect Ack Synchronous response
umaRelease() Release - -
umaRequestConfig() Request Configuration - -
umaSeek() Seek - -
umaSetAttr() Set Attribute - One message per attribute
umaSetThreshold() Set Threshold - MLI may issue prior Request Configuration to verify class/subclass status
umaStart() Start - MLI may issue prior Request Configuration to verify class/subclass status
umaStop() Stop - -

Table: MLI Calls and Resulting DSL-to-DSL Messages

Note that condition messages (class Condition, subclasses Informational, Warning, Severe or Fatal) may be sent to the MLI as a result of any of the above MLI calls. These messages may be originated by either the remote or local DSL.

Forwarded Requests - Message Class - Command

These messages are in class Command and result from MLI requests. The subclass depends on the specific action requested.
Message Subclass - Create

This message requests that the UMA facility create a session.

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMAUint4
maximum buffer size to be used for communications.

UMAUint4
user id for remote authorisations.

UMAUint4
remote host I/P address for which data is to be reported.

UMATextDescr
source as specified in MLI umaCreate() call.

UMATextDescr
destination as specified in MLI umaCreate() call.

UMAProp
session properties as specified in MLI umaCreate() call.

Message Subclass - Reconnect

This message informs the UMA facility to reestablish session control to a previously shut down session with the NOTERM property.

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMAUint4
maximum buffer size to be used for communications.

UMATextDescr
destination as specified in MLI umaReconnect() call.

Message Subclass - Set Attribute

This message informs the UMA facility of the session attributes. One attribute is sent per message.

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMATextDescr
attribute name. The following attribute strings are defined: "STIME", "ETIME", "INTERVAL", "PRIO", "HISTORY_ONLY", "RECENT_ONLY", "PARTIAL".

UMAInt4
attribute value.

Message Subclass - Close

This is a request to shut down a session. This message is composed of a header only. The subclass field in the header identifies the request.

UMAHeader
standard UMA message header.

Message Subclass - Start

This message informs the UMA facility to report data specified by the fields in this subclass (that is, class, subclass, . . .)

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMAProvider
data provider as specified in the umaStart() MLI call.

UMAClass
data class as specified in the umaStart() MLI call.

UMASubClass
data subclass as specified in the umaStart() MLI call.

UMASegFlags
data segments as specified in the umaStart() MLI call. The value will be one of UMA_BSEG, UMA_OSEG, UMA_ESEG, UMA_ASEG representing basic, optional, vendor extension, and all, respectively.

UMAUint4
length of workload definition structure or zero, if none specified.

UMAWorkDefn
workload definition structure as specified in the umaStart() call. This parameter is optional and will not be present if the preceding sentinel length indicator is zero.

Message Subclass - Set Threshold

This message informs the UMA facility to report data specified by the fields in this subclass (that is, class, subclass, . . .) only if the selection expression evaluates to true.

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMAProvider
data provider as specified in the umaSetThreshold() MLI call.

UMAClass
data class as specified in the umaSetThreshold() MLI call.

UMASubClass
data subclass as specified in the umaSetThreshold() MLI call.

UMASegFlags
data segments as specified in the umaSetThreshold() MLI call. The value will be one of UMA_BSEG, UMA_OSEG, UMA_ESEG, UMA_ASEG representing basic, optional, vendor extension, and all, respectively.

UMATextDescr
selection expression as specified in the umaSetThreshold() MLI call. See the description for the umaSetThreshold() MLI call for expression syntax.

UMATextDescr
workload identifier as specified in the umaSetThreshold() call.

Message Subclass - Release

This message informs the UMA facility to begin the collection and reporting of started data classes and subclasses. This message is composed of a header only. The subclass field in the header identifies the request.

UMAHeader
standard UMA message header.


Message Subclass - Request Data
This message informs the UMA facility that a receiving buffer is empty and therefore able to receive more data.

UMAHeader
standard UMA message header

UMAUint4
buffer selection. The value will be one of UMA_HIGH_BUFF, UMA_NORM_BUFF, representing high and normal buffers, respectively.

Message Subclass - Stop

This message informs the UMA facility to stop reporting data specified by the fields in this subclass (that is, class, subclass, . . .)

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMAProvider
data provider as specified in the umaStop() MLI call.

UMAClass
data class as specified in the umaStop() MLI call.

UMASubClass
data subclass as specified in the umaStop() MLI call.

UMASegFlags
data segments as specified in the umaStop() MLI call. The value will be one of UMA_BSEG, UMA_OSEG, UMA_ESEG, UMA_ASEG representing basic, optional, vendor extension, and all, respectively.

UMAFlushFlags
queue of data to flush as specified in the umaStop() MLI call. The value will be one of UMA_HELD, UMA_RELEASED, UMA_ALLSTARTED, to indicate whether held requests or only those released or all started requests are to be stopped.

UMAUint4
length of workload definition structure or zero, if none specified.

UMAWorkDefn
workload definition structure as specified in the umaStop() call. This parameter is optional and will not be present if the preceding sentinel length indicator is zero.

Message Subclass - Seek
This message informs the UMA facility to reposition the next reported interval.

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMAWhence
whence value: one of UMA_CTIME, UMA_LTIME, UMA_STIME or UMA_TSTAMP. Indicates what the seek is relative to.

UMATimeSpec
if the whence is UMA_TSTAMP, this field contains an arbitrary timestamp value which the seek is relative to.

UMAInt4
relative position (number of intervals of data messages) from timestamp as specified in the umaSeek() MLI call. The value may be zero, positive, or negative.

UMAUint4
port number for high priority channel (uma_high).

UMATimeStamp
session's current time (as known by the local DSL).

UMAUint4
session's last seek number (as known by the local DSL).

Message Subclass - Request Configuration
This message requests that the UMA facility return (as messages) the configuration status of classes and subclasses specified in the fields.

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMAProvider
data provider as specified in the umaRequestConfig() MLI call.

UMAClass
configuration data class as specified in the umaRequestConfig() MLI call.

UMASubClass
configuration data subclass as specified in the umaRequestConfig() MLI call.

UMAUint4
port number for high priority channel (uma_high).

Message Class - Connection Status

Message Subclass - Connection Ack
This message is a status acknowledgment for a connection request.

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMAStatusCode
status code. This code identifies the general outcome of the connection request. Defined values are specified elsewhere in this document.

UMAReasonCode
reason code. This code provides more in depth identification for a status code. Defined values are specified elsewhere in this document.

Message Subclass - Reconnect Ack
This message is a status acknowledgment for a reconnection request.

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMAStatusCode
status code. This code identifies the general outcome of the connection request. Defined values are specified elsewhere in this document.

UMAReasonCode
reason code. This code provides more in depth identification for a status code. Defined values are specified elsewhere in this document.

UMATextDescr
source.

UMAProp
session properties.

UMAAttr
session attributes.

Message Class - Condition

Message Subclass - Informational

This message provides informational status regarding a condition that has occurred in UMA.

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMAInt4
source of the condition.

UMAInt4
condition identifier.

char[]
condition description.

UMAInt4
type of hint1.

UMAHint
value of hint1.

UMAInt4
type of hint2.

UMAHint
value of hint2.

UMAInt4
type of hint3.

UMAHint
value of hint3.

Message Subclass - Warning

This message provides warning status regarding a condition that has occurred in UMA.

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMAInt4
source of the condition.

UMAInt4
condition identifier.

char[]
condition description.

UMAInt4
type of hint1.

UMAHint
value of hint1.

UMAInt4
type of hint2.

UMAHint
value of hint2.

UMAInt4
type of hint3.

UMAHint
value of hint3.

Message Subclass - Severe

This message provides status regarding a severe condition that has occurred in UMA.

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMAInt4
source of the condition.

UMAInt4
condition identifier.

char[]
condition description.

UMAInt4
type of hint1.

UMAHint
value of hint1.

UMAInt4
type of hint2.

UMAHint
value of hint2.

UMAInt4
type of hint3.

UMAHint
value of hint3.

Message Subclass - Fatal

This message provides status regarding a fatal condition that has occurred or is imminent in UMA.

UMAHeader
standard UMA message header.

UMASegDescr
ASN.1/BER tags and lengths for the segment.

UMAInt4
source of the condition.

UMAInt4
condition identifier.

char[]
condition description.

UMAInt4
type of hint1.

UMAHint
value of hint1.

UMAInt4
type of hint2.

UMAHint
value of hint2.

UMAInt4
type of hint3.

UMAHint
value of hint3.

Footnotes

1.
The OMG is in the process of defining message and transport specifications for CORBA that will ensure that different Object Request Broker (ORB) implementations will interoperate. In future, PMWG will evaluate these specifications when they are finalised, along with others, to determine their applicability for UMA message transport.

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index