Previous section.

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

UMA Message and Header Formats

UMA API messages, called UMA Data Units (UDUs), consist of a tagged header and either a control segment or one or more data segments. A limited degree of ASN.1/BER encoding has been provided by incorporating ASN.1 tags and length descriptors at the message, header, and segment levels.

UDU Message Headers

The class and subclass of a message are indicated in the message header. These are as defined by the UMA API unless flags (in the mh_flags field) indicate that they are specific to a provider. The provider identifier is specified in the header (in the mh_provider field). Thus, depending on these flag settings, a provider may be a source of either datapool-defined data or of data that is unique to that provider. An example of the difference would be a datapool-defined DBMS data class that is provided by the XYZ product designated by the integer nnn (flag setting off) versus a DBMS data class that is specific to XYZ (flag setting on). Both would have the integer nnn in the provider identifier field.

A UDU Indicators field in the message header includes specification of data encoding formats. Three canonical formats are defined:

  1. Canonical A, which provides data in the native format of the processor where captured along with metadata (see reference DCI). In this form the metadata must be used to interpret subclass data.

  2. Canonical B, which encodes all items following the UDU Indicators field according to ASN.1/BER tag-length-value format. Where tags and lengths are already specified in the message or segment headers, they would be incorporated into the BER encoding for Canonical B Format.

  3. Canonical C, which permits data to be mapped to standardised C structures. In this format there is limited ASN.1/BER encoding at the constructed types level (for example, headers and data segments). In this format, metadata may also be made available.

UDU Control Segments

UDU control segments contain directives to UMA to take some action (for example, create a session, start measuring some class/subclass, query a status, etc.)

The UDU header indicates that the UDU contains a control segment by a flag and by the control segment class.

Compatibility Support

The UDU header optionally contains a "Protocol Section" that provides UMA-specific, vendor-specific, and platform-specific level and version information that may be needed for interoperable or vendor-optimized communications between UMA Data Services Layers.

The protocol parameters supported are:

UMA

Indicates communications protocols supported (indicated in the acknowledgement) - Flag 0x0001 is TCP/IP with socket interface

UMA

Indicates the UMA message header and UDU format specification level - Level 1 is the level specified by this document.

UMA+Message

Indicates the document specification base - Level 1 is the level specified by this document.

UMA

Indicates vendor name in text form (mhpro_vndname).

UMA

Indicates private vendor protocol level available (mhpro_vndplvl).

Protocol level indicators are positive integers, nominally 0-127.

Status Reporting

Control segments can report status back to the MAP. For all status messages, the class is the defined constant C_CONDITION. The subclass identifies the severity.

The source field, cs_source, identifies the UMA component affected:

The subclass of a message identifies the severity of the problem. The severity may be one of the following:

The body bgcolor="#FFFFFF" identifies the condition (through defined constants). For each source, there is a separate list of possible conditions. In addition, the message includes a textual description of the problem, for example: 

 

"Data not collected for this interval"
"Requested timestamp not contained in any interval"
"End of session encountered"

The text description is useful for reporting the condition back to a user. It can be used, for example, in printing a status message to the user's terminal.

UMA API Message Header Format for Control UDUs

The following table shows the proposed UMA message header format for control messages.

Table: UMA API UMA Control Message Header

Data Type Name Description
UMAOctetString[4] mh_msgtag BER-encoded UMA message indicator tag 0x7fd5cd41
UMAOctetString[1] mh_msglenlen ASN.1/BER length of mh_msglen
  1000 0011 Leading bit always 1; shows mh_msglen length of 3 octets.
UMAOctetString[3] mh_msglen Length of the message including the standard header starting at the next field
UMAOctetString[3] mh_hdrtag UDU Header Tag 0xbf1081 (includes length of mh_hdrlen in the low order 7 bits). The first octet of the string marks the global start of the message.
UMAOctetString[1] mh_hdrlen Length of UDU Header
UMAOctetString[3] mh_indtag UDU Indicators tag (for mh_flags) indicators - 0x9f3081 (includes length of mh_flags in the low order 7 bits).
UMAOctetString[1] mh_indlen Length of UDU Indicators
UMAMsgFlags mh_flags UDU Indicators
  1... .... .... .... UDU contains control information
  010. .... .... .... Canonical A format1
  001. .... .... .... Canonical B format
  011. .... .... .... Canonical C format
  1... 0... .... .... 16-bit byte order H to L2
  1... 1... .... .... 16-bit byte order L to H
  1... .0.. .... .... integer component order H to L
  1... .1.. .... .... integer component order L to H
  1... .... 1... .... First message for this class, this system ID
  1... .... .1.. .... Last message for this class, this system ID
  1... .... ...0 .... dst not in effect
  1... .... ...1 .... dst in effect
  1... .... .... 1... Protocol Section present
UMAOctetString[3] mh_protag UDU Protocol Section tag (if section present) - 0xbf708n (includes length of protocol section, n, in the low order 7 bits).
UMAOctetString[3] mhpro_wdsztag Tag for this platform's wordsize - 0x9f7181 (includes length of mhpro_wdsize in the low order 7 bits).
UMAOctetString[1] mhpro_wdsize This platform's wordsize in bytes
UMAOctetString[3] mhpro_cplvltag Tag for UMA Communication Protocols - 0x9f7384 (includes length of mhpro_umaplvl in the low order 7 bits).
UMAUint4 mhpro_umacps UMA Message Communications Protocols supported
UMAOctetString[3] mhpro_mflvltag Tag for UMA Message Format Level - 0x9f7581 (includes length of mhpro_umamflvl in the low order 7 bits)
UMAOctetString[1] mhpro_umamflvl UMA Message Format Specification Level3
UMAOctetString[3] mhpro_sblvltag Tag for UMA Specification Base Level - 0x9f7681 (includes length of mhpro_umamslvl in the low order 7 bits)
UMAOctetString[1] mhpro_umasblvl UMA Message Specification Base Level
UMAOctetString[3] mhpro_vndtag Tag for Vendor Name string - 0x9f778n (includes length of mhpro_vndname in the low order 7 bits, max length 64).
UMAOctetString[] mhpro_vndname Vendor Name - Text not null terminated
UMAOctetString[3] mhpro_vndptag Vendor Protocol Level tag - 0x9f7981 (includes length of mhpro_vndplvl in the low order 7 bits).
UMAOctetString[1] mhpro_vndplvl Vendor Protocol Level
UMATimeStamp mh_time Timestamp of message creation
UMAClass mh_class UMA class of the message
UMASubclass mh_subclass UMA subclass of the message
UMAOctetString[8] mh_address Host network address that generated the data in the message
UMAOctetString[4] mh_addr_family Host network address type (e.g. internet, SNA, ...)4

UMA API Control Segment Format for Control UDUs

The following table shows the UMA control segment format for control messages (Canonical C format shown).

Data Type Name Description
UMAOctetString[4] cs_segtag BER-encoded control segment tag 0xbfd5c300 ("UC", counter 0x00)
UMAOctetString[1] cs_seglenlen ASN.1/BER length of cs_seglen
  1000 0011 Leading bit always 1; indicates cs_seglen length of 3.
UMAOctetString[3] cs_seglen Length of the control segment that follows (not including this field); the next octet marks the local start position for this segment
  .  
  Control Segment Content  
  .  

Table: UMA API UDU Control Segment

Hints

The message body bgcolor="#FFFFFF" provides three hint fields. The following table lists the conditions that use the hint fields. 




Condition
Hint 1
Hint 2
Hint 3

U_EGAP
Start time of gap
Duration of gap
not used

RHIST_GAP
 
 
 

DSL_NODATA
Start time of interval
Duration of interval
not used

DSL_GAP
Start time of gap
Duration of gap
not used

DSL_EOS
Session end time
not used
not used

DSL_INTVL
Closest available interval
not used
not used

U_EOF
Timestamp of last
not used
not used

 
interval in data source.
 
 

 
Either UMADS or file.
 
 







Table: Conditions Using Hint Fields



When provided, the MAP can use the hints to respond 
to the condition. Here are two examples:

    

    

  1. 
If an interval of data does not exist, a gap message will be sent. The first 
two of the hint fields are used with gap messages: the first contains the gap 
start time and the second contains the gap duration. A MAP graphing the data 
can use the hints in a gap message to display the start time and duration of 
the gap.

    

  2. 
Another situation that uses the hint fields is when a MAP requests data for 
an interval that UMA is unable to provide. This situation will happen if 
the interval is not already being collected and the site-configured maximum 
number of collectors are active. In this case, hint 1 provides the closest 
available interval size.

    




Each hint field is a union of the following data types:




Each hint field is preceded by a hint type field, which identifies the type
actually used for the hint.

UDU Data Segments




UDU data segments contain either interval or event data (traces are

treated as a form of event data). The
presence of either category is indicated by a flag in the message
header.  Interval data is that which is specifically scheduled for
capture at each expiration of a specified time interval.  The data
reported for the interval is the increment of the item values over the
interval.  


Within the categories of interval or event data, there are currently
three kinds of data segments as defined by the Data Pool Definitions
(see reference DPD):

    

    

  1. 
Basic data, which each implementation must supply


    

  2. 
Optional data, which is generally available in open operating systems

but is not mandatory

    

  3. 
Extension data, which is associated with a class and subclass, but is

vendor and/or implementation-specific.

    




Following each fixed data segment section (Basic,
Enhanced, Extension) there is a VLDS (Variable Length


Data Section) that may contain one or more data items
of varying length (for example, text strings, arrays).  Each
of these variable length items is pointed to and
described by descriptors of the appropriate type (for example
UMATextDescr, UMAArrayDescr) in the fixed length section.


Each of the UDU data segments begins with an ASN.1/BER tag-length
prefix.  The location of each segment is specified in the UDU header
as an offset from a message global start position.


The following figure, UMA Data UDU Message Layout, illustrates the
details of how a data UDU is assembled.












Figure: UMA Data UDU Message Layout


UMA API Message Header Formats for Data UDUs


The following table shows the UMA message header format for data UDUs
(Canonical C format shown).



Table: UMA API Data UDU Message Header






Data Type
Name
Description

UMAOctetString[4]
mh_msgtag
BER-encoded UMA message indicator tag 0x7fd5cd41

UMAOctetString[1] 
mh_msglenlen
ASN.1/BER length of mh_msglen

 
1000 0011
Leading bit always 1; indicates mh_msglen length of 3 octets.

UMAOctetString[3]
mh_msglen
Length of the message including the standard header starting at
the next field

UMAOctetString[3]
mh_hdrtag
UDU Header Tag 0xbf0181 (includes length of mh_hdrlen in the low order
7 bits).  The first octet of the string marks the global start of the
message.

UMAOctetString[1]
mh_hdrlen
Length of UDU Header

UMAMsgFlags
mh_flags
UDU Indicators

 
0... .... .... ....
UDU contains interval/event data

 
010. .... .... ....
Canonical A format

 
001. .... .... ....
Canonical B format

 
011. .... .... ....
Canonical C format

 
0... 0... .... ....
16-bit byte order H to L

 
0... 1... .... ....
16-bit byte order L to H

 
0... .0.. .... ....
integer component order H to L

 
0... .1.. .... ....
integer component order L to H

 
0... 1... .... ....
Interval data (interval header extension will be present)

 
0... 0... .... ....
Event or trace data (event header extension will be present)

 
0... ...0 .... ....
dst not in effect

 
0... ...1 .... ....
dst in effect

 
0... .... 1... ....
First message for this class, this system ID

 
0... .... .1.. ....
Last message for this class, this system ID 

 
0... .... ...1 ....
Last message for this subclass

 
0... .... .... 1...
Class specified is provider-specific

 
0... .... .... .1..
Subclass specified is provider-specific

 
0... .... .... ...1
Threshold screening has been applied to this UDU

UMATimeStamp
mh_time
Timestamp of message creation (data received from Data Capture Interface)

UMAClass   
mh_class
UMA class of the message

UMASubClass   
mh_subclass
UMA subclass of the message

UMAOctetString[8]   
mh_address
Host network address that generated the data in the message

UMAOctetString[4]   
mh_addr_family
Host network address type (Internet, SNA, etc.)

UMAUint4   
mh_provider
Identifier of the data provider 
that registered to supply this data.

UMAUint4   
mh_provinst
The instance of this provider.







Interval Header Extension and Data UDU Basic Segment



The following table shows the interval header extension and
basic segment for data UDUs (Canonical C format shown).



Table: UMA API Interval Header Extension and Data UDU Basic Segment






Data Type
Name
Description

 
Interval Data Header Extension
(Type UMAIntExt)

UMAOctetString[3]
mhix_ixlenlen
BER-encoded header interval extension tag and length of mhix_ixlen
(0xbf0581)

UMAOctetString[1]    
mhix_ixlen
Length of the interval extension

UMAMsgFlags    
mhix_flags
Interval extension flags

 
1... .... .... ....
First message for interval, this system ID

 
.1.. .... .... ....
Last message for interval, this system ID

 
..1. .... .... ....
Source for this data was recent history

UMATimeStamp
mhix_schedtime
Datetime measurement scheduled as timestamp (nsec)

UMATimeStamp
mhix_intime
Actual timestamp for this interval (nsec)

UMATimeUsec
mhix_intlen
Duration of this interval in microseconds

UMAUint4
mhix_baseoff
Offset from global start to basic data segment, if it is present (zero
otherwise)

UMAUint4
mhix_optoff
Offset from global start to optional segment, if it is present (zero
otherwise)

UMAUint4
mhix_extoff
Offset from global start to extension segment, if it is present (zero
otherwise)

=
Data UDU Basic Segment
=

UMAOctetString[4]
bs_segtag
BER-encoded basic data segment tag 0xbfd5c200 ("UB", counter 0x00).
This and the next 2 fields are included in the type UMASegDescr.

UMAOctetString[1] 
bs_seglenlen
ASN.1/BER length of bs_seglen

 
1000 0011
Leading bit always 1; indicates bs_seglen length of 3.

UMAOctetString[3] 
bs_seglen
Length of the basic segment that follows, not including this field
or the length of the Variable Length Data Section (VLDS); the next
octet marks the local start position for this segment.

 
   .
 

 
  Basic Segment Data
 

 
   .
 

=
UDU VLDS
=

UMAOctetString[4]
vlds_sectag
ASN.1/BER-encoded VLDS tag 0xbfuutt80
This and the next 2 fields are included in the type UMASegDescr.

 
uutt = 0xd5c2
Basic segment

 
uutt = 0xd5cf
Optional segment

 
uutt = 0xd5c5
Extension segment

UMAOctetString[1]
vlds_seclenlen
ASN.1/BER length of vlds_seclen

 
1000 0011
Leading bit always 1; gives vlds_seclen length 3 octets.

UMAOctetString[3]
vlds_seclen
VLDS length (not including this field)

 
   .
 

 
  Variable length data item
 

 
   .
 







Event Header Extension and Data UDU Basic Segment



The following table shows the event header extension and
basic segment for data UDUs (Canonical C format shown).



Table: UMA API Event Header Extension and Data UDU Basic Segment






Data Type
Name
Description

 
 
 

 
Event Data Header Extension
(Type UMAEvtExt)

UMAOctetString[3]
mhex_exlenlen
BER-encoded event header extension tag and length of mhex_exlen
(0xbf0681). 

UMAOctetString[1]    
mhex_exlen
Length of the event header extension

UMATimeStamp
mhex_evtime
Timestamp of this event (nsec)

UMAUint4
mhex_baseoff
Offset from global start to basic data segment, if it is present (zero
otherwise)

UMAUint4
mhex_optoff
Offset from global start to optional segment, if it is present (zero
otherwise)

UMAUint4
mhex_extoff
Offset from global start to extension segment, if it is present (zero
otherwise)

=
Data UDU Basic Segment
=

UMAOctetString[4]
bs_segtag
BER-encoded basic data segment tag 0xbfd5c200 ("UB", counter 0x00).
This and the next 2 fields are included in the type UMASegDescr.

UMAOctetString[1] 
bs_seglenlen
ASN.1/BER length of bs_seglen

 
1000 0011
Leading bit always 1; indicates bs_seglen length of 3.

UMAOctetString[3] 
bs_seglen
Length of the basic segment that follows, not including this field and
not including the length of the VLDS; the next
octet marks the local start position for this segment.

 
   .
 

 
   .
 

 
  Basic Segment Data
 

 
   .
 

 
   .
 

=
UDU VLDS
=

UMAOctetString[4]
vlds_sectag
ASN.1/BER-encoded VLDS tag 0xbfuutt80.
This and the next 2 fields are included in the type UMASegDescr.

 
uutt = 0xd5c2
Basic segment

 
uutt = 0xd5cf
Optional segment

 
uutt = 0xd5c5
Extension segment

UMAOctetString[1]
vlds_seclenlen
ASN.1/BER length of vlds_seclen

 
1000 0011
Leading bit always 1; indicates vlds_seclen length of 3 octets.

UMAOctetString[3]
vlds_seclen
VLDS length (not including this field)

 
   .
 

 
   .
 

 
  Variable length data item
 

 
   .
 







Optional and Extension Segments



The Data Capture Committee Measurement Data Pool document 
defines two data segments in addition to that for basic data.  The
optional segment contains standard data that is part of the pool,
but may be implemented at an individual vendor's choice.  The
extension segment contains additional data items that a specific
vendor considers useful.



Data Type
Name
Description

UMAOctetString[4]
os_segtag
BER-encoded optional data segment tag 0xbfd5cf00 ("UO", counter 0x00)

UMAOctetString[1] 
os_seglenlen
ASN.1/BER length of os_seglen

 
1000 0011
Leading bit always 1; indicates os_seglen length of 3.

UMAOctetString[3] 
os_seglen
Length of the optional segment that follows, not including this field
and not including the length of the VLDS; the
next octet marks the local start position for this segment.

 
   .
 

 
   .
 

 
  Optional Segment Data
 

 
   .
 

 
   .
 





Table: Optional Segment Header







Data Type
Name
Description

UMAOctetString[4]
es_segtag
BER-encoded extension data segment tag 0xbfd5c500 ("UE", counter 0x00)

UMAOctetString[1] 
es_seglenlen
ASN.1/BER length of es_seglen

 
1000 0011
Leading bit always 1; indicates es_seglen length of 3.

UMAOctetString[3] 
es_seglen
Length of the extension segment that follows, not including this
field; the next octet marks the local start position for this segment.

 
   .
 

 
   .
 

 
  Extension Segment Data
 

 
   .
 

 
   .
 





Table: Extension Segment Header





Variable Length Data



In a UDU data segment (basic, optional, extension), a variable
length data item is comprised of two
parts.  The first is a fixed-length descriptor giving the offset to
the item from the segment local start position
and the length of the item.  The second part is the
variable length data
itself which is located in the segment's VLDS.
Variable length text data, described by the
UMA type UMATextDescr is an example of the use of this format.



Data Type
Name
Description

 
   .
 

xxxxxx	
pppppp
Fields preceding descriptor

 
   .
 

UMAUint4   
yyy_off
Offset from segment local start to variable length data item yyy

UMAUint4   
yyy_len
Length of the variable length data item (in bytes)

 
   .
 

xxxxxx   
ffffff
Field(s) following variable length data descriptor

=
UDU VLDS
=

UMAOctetString[4]
vlds_sectag
ASN.1/BER-encoded VLDS tag 0xbfuutt80

 
uutt = 0xd5c2
Basic segment

 
uutt = 0xd5cf
Optional segment

 
uutt = 0xd5c5
Extension segment

UMAOctetString[1]
vlds_seclenlen
ASN.1/BER length of vlds_seclen

 
1000 0011
Leading bit always 1; indicates vlds_seclen length of 3 octets.

UMAOctetString[3]
vlds_seclen
VLDS length (not including this field)

 
   .
 

 
   .
 

 
  Variable length data item
 

 
   .
 





Table: Format for Variable Length Data Items





Array Data

In a UMA data message segment (basic, optional, extension), an array
data entry is comprised of two parts.  The 
first is a fixed-length descriptor (of type UMAArrayDescr)
giving the offset to the array from
the segment local start position, the count of array elements, and the
size of each.  The second part is the array itself which is located
in the segment's VLDS.



Data Type
Name
Description

 
   .
 

xxxxxx	
pppppp
Fields preceding array descriptor

 
   .
 

UMAUint4   
yyy_off
Offset from segment local start to first element of array yyy

UMAUint4   
yyy_elmtcount
Number of array elements in yyy

UMAUint4   
yyy_elmtsize
Size of each array element in yyy

 
   .
 

xxxxxx   
ffffff
Field(s) following array descriptor

 
   .
 

 
   .
 

 
 
 

=
UDU VLDS
=

UMAOctetString[4]
vlds_sectag
BER-encoded VLDS tag 0xbfuutt80

 
uutt = 0xd5c2
Basic segment

 
uutt = 0xd5cf
Optional segment

 
uutt = 0xd5c5
Extension segment

UMAOctetString[1]
vlds_seclenlen
ASN.1/BER length of vlds_seclen

 
1000 0011
Leading bit always 1; indicates vlds_seclen length of 3 octets.

UMAOctetString[3]
vlds_seclen
VLDS length of following (not including this field)

 
   .
 

 
  Array Data
 

 
   .
 

 
   .
 





Table: Format for Array Data Items









Footnotes


1.
Format designated (A, B, or C) is in effect for the remainder of the
message following the optional Protocol Section.

2.
Local DSL preferred byte order in Create and Reconnect protocol.

3.
Specification Level indicators are positive integers, nominally 0-127

4.
The provider identifier is an integer which may refer to the 
operating system kernel, its subcomponents, or to subsystems such as DBMSs,
transaction managers, or other applications.  A default value of the
identifier may be established by vendors of subsystems for their products.
However these must be capable of being overridden by systems administrators
at sites where they are in use.  The provider identifier is mapped to
text labels by the subclass "UMA Providers" of the class "UMA
Configuration".








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