Data Formats

The data structure section first defines some generic types that will be used throughout the definition of XEMS. Some of these types define standard C data types and some machine dependant types so that implementations of XEMS can define them to be machine dependent. There are also some other non-scalar types that are use to standardize use of items such as timestamp, and character strings.

Event attributes are used in several other data structures in XEMS, such as the event data structure as well as the event type schema data structure, and the attribute list data structure. Event attributes contain an attribute name as well as a self defining value which has a format and a value.

The XEMS Event structure contains a fixed header, and a variable size array of event attributes. The header contains fields that identify the event and its type, the event origin, what severity the event is, as well as a place for the Event Service to put the received time as well as the time the event was delivered to an interested consumer. An additional field has been added to mark the priority of an event.

The event type data structures allow the construction of event type schemas.

Event filters are constitute in XEMS using the event filter data structures. These structures allow building filters by first constructing event expressions that contain attribute names, operators, and attribute values. Expressions are then collected into expression lists which then become event filters. There is also a structure for event filter name lists which are used to define consumer filter groups and to return lists of filters from the event filter database.

The consumer and supplier data structures are used to return information about consumers and suppliers from XEMS.

There is also an attribute list data structure which allows getting and setting attributes in XEMS. The actual values of the attributes are not defined in the specification.

The event list data structure allows management of undelivered events. A list of undelivered events can be returned in an event list.

The ems_handle is an opaque data type which is used in calls to XEMS routines. An ems_handle represents a connection to an Event Service on a particular host. When calling XEMS routines, one of the XEMS registration routines is called to unitize the handle, and it is used in all subsequent calls to XEMS routines that want to affect the Event Service on that host.

Generic Data Types

Scalar Types

 

typedef unsigned_char          ems_boolean;     // 1 byte
#define ems_false              false
#define ems_true               true
typedef unsigned char          ems_byte;        // 1 byte
typedef unsigned char          ems_char;        // 1 byte
typedef signed char            ems_small_int;   // 1 byte
typedef unsigned char          ems_usmall_int;  // 1 byte
typedef short int              ems_short_int;   // 2 bytes
typedef unsigned short int     ems_ushort_int;  // 2 bytes
typedef long int               ems_long_int;    // 4 bytes
typedef unsigned long int      ems_ulong_int;   // 4 bytes

struct ems_hyper_int_rep_s_t {
    ems_long_int     high;
    ems_ulong_int    low;
} ems_hyper_int;

struct ems_uhyper_int_rep_s_t {
    ems_ulong_int    high;
    ems_ulong_int    low;
} ems_uhyper_int;

typedef float                  ems_short_float; // 4 bytes
typedef double                 ems_long_float;  // 8 bytes

Strings

 

typedef char *     ems_string_t;

Unique Identifier

 

typedef struct uuid_t {
    ems_ulong_int      time_low;
    ems_ushort_int     time_mid;
    ems_ushort_int     time_hi_and_version;
    ems_usmall_int     clock_seq_hi_and_reserved;
    ems_usmall_int     clock_seq_low;
    ems_byte           node[6];
} ems_uuid_t;

Time Stamp

 

typedef struct utc {
    ems_byte           char_array[16];
} ems_utc_t;

Error Status

 

typedef ems_ulong_int  ems_error_t;

Event Type

 

typedef ems_uuid_t     ems_event_type_t;

Delivery Type

 

typedef enum {
    ems_delivery_push = 0,
    ems_delivery_pull
} ems_delivery_t;

Security Object

 

typedef enum {
    ems_secobj_server = 0,
    ems_secobj_eventtypes,
    ems_secobj_filters,
    ems_secobj_consumers,
    ems_secobj_suppliers,
    ems_secobj_eventtype,
    ems_secobj_filter
} ems_secobjtype_t;

typedef struct {
    ems_secobjtype_t     secobjtype;
    ems_string_t         name;
    ems_uuid_t           uuid;
} ems_secobj_t;

Permissions Attributes

 

typedef struct {
    ems_usmall_int       control;
    ems_usmall_int       delete;
    ems_usmall_int       insert;
    ems_usmall_int       read;
    ems_usmall_int       write;
    ems_usmall_int       execute;
} ems_secperm_t;

Subject

 

typedef struct {
    ems_string_t         name;
    ems_uuid_t           uuid;
} ems_secsubj_t;

Principal

 

typedef struct {
    ems_ushort_int       len;
    ems_byte *           principal;
} ems_secprin_t;

Event Attributes

Event Attribute Types

 

typedef ems_ushort_int    ems_attr_type_t;

An event attribute type can be one of the following:

The actual attribute format type values are:

 

#define ems_c_attr_small_int     (0)
#define ems_c_attr_short_int     (1)
#define ems_c_attr_long_int      (2)
#define ems_c_attr_hyper_int     (3)
#define ems_c_attr_usmall_int    (4)
#define ems_c_attr_ushort_int    (5)
#define ems_c_attr_ulong_int     (6)
#define ems_c_attr_uhyper_int    (7)
#define ems_c_attr_short_float   (8)
#define ems_c_attr_long_float    (9)
#define ems_c_attr_boolean       (10)
#define ems_c_attr_uuid          (11)
#define ems_c_attr_utc           (12)
#define ems_c_attr_severity      (13)
#define ems_c_attr_byte_string   (15)
#define ems_c_attr_char_string   (16)
#define ems_c_attr_bytes         (17)

Event Attribute Values

 

typedef struct ems_bytes_s_t {
    ems_ulong_int    size;
    ems_byte         *data;
} ems_bytes_t;

typedef struct {
    ems_attr_type_t format;
    union {
        /* case(s): ems_c_attr_small_int */
        ems_small_int small_int;
        /* case(s): ems_c_attr_short_int */
        ems_short_int short_int;
        /* case(s): ems_c_attr_long_int */
        ems_long_int long_int;
        /* case(s): ems_c_attr_hyper_int */
        ems_hyper_int hyper_int;
        /* case(s): ems_c_attr_usmall_int */
        ems_usmall_int usmall_int;
        /* case(s): ems_c_attr_ushort_int */
        ems_ushort_int ushort_int;
        /* case(s): ems_c_attr_ulong_int */
        ems_ulong_int ulong_int;
        /* case(s): ems_c_attr_uhyper_int */
        ems_uhyper_int uhyper_int;
        /* case(s): ems_c_attr_short_float */
        ems_short_float short_float;
        /* case(s): ems_c_attr_long_float */
        ems_long_float long_float;
        /* case(s): ems_c_attr_boolean */
        ems_boolean bool;
        /* case(s): ems_c_attr_uuid */
        ems_uuid_t uuid;
        /* case(s): ems_c_attr_utc */
        ems_utc_t *utc;
        /* case(s): ems_c_attr_severity */
        ems_severity_t severity;
        /* case(s): ems_c_attr_byte_string */
        ems_byte *byte_string;
        /* case(s): ems_c_attr_char_string */
        char *char_string;
        /* case(s): ems_c_attr_bytes */
        ems_bytes_t bytes;
    } tagged_union;
} ems_attr_value_t;

Event Attribute

 

typedef struct ems_attribute_s_t {
    ems_string_t        name;
    ems_attr_value_t    value;
} ems_attribute_t;

Event Structure

Event Identifier

 

typedef struct ems_eventid_s_t {
    ems_event_type_t    type;
    ems_uuid_t          id;
} ems_eventid_t;

Event Type

Events of type Generic, do not have event type schemas associated with them, and can only be filtered by expressions with header attributes in them (see Event Header Attributes ).

Network Name

 

typedef enum {
    ems_ns_other,
    ems_ns_dns,
    ems_ns_dce,
    ems_ns_x500,
    ems_ns_nis,
    ems_ns_sna
} ems_nameservice_t;

The ems_netaddr_t structure specifies the actual network name. It can be interpreted according to the name service specified. Structure ems_octet_t defines an 8-bit field. len specifies how many 8-bit quantities there are in name.

 

typedef char ems_octet_t;
typedef struct ems_netaddr_s_t {
    ems_ulong_int     len;
    ems_octet_t       name[1];
} ems_netaddr_t;

The ems_netname_t consists of service which specifies which name service recognizes the name specified by netaddr.

 

typedef struct ems_netname_s_t {
    ems_nameservice_t    service;
    ems_netaddr_t        *netaddr;
} ems_netname_t;

For a DCE hostname, the following example will set the ems_netname_t structure:

 

static char * dce_hostname = "/.:/hosts/eagle.austin.ibm.com";
ems_netname_t    netname;
netname.service = ems_ns_dce;
netname.netaddr->len = strlen( dce_hostname )+1;
netname.netaddr->name = (char *)malloc( netname.netaddr->len );
strcpy( netname.netaddr->name, dce_hostname );

Event Origin

 

typedef struct ems_origin_s_t {
    ems_netname_t    netname;
    ems_string_t     descname;
    ems_ulong_int    pid;
    ems_ulong_int    uid;
    ems_ulong_int    gid;
} ems_origin_t;

Event Severity

 

typedef enum {
    ems_sev_info,
    ems_sev_fatal,
    ems_sev_error,
    ems_sev_warning,
    ems_sev_notice,
    ems_sev_notice_verbose,
    ems_sev_debug
} ems_severity_t;

Event Priority

 

typedef ems_ulong_int    ems_priority_t;

Event Header

 

typedef struct ems_hdr_s_t {
    ems_eventid_t     eventid;
    ems_origin_t      origin;
    ems_severity_t    severity;
    ems_utc_t         received;
    ems_utc_t         delivered;
    ems_priority_t    priority;
} ems_hdr_t;

A set of filter attributes are provided for event header filtering. The following names can be used for the filter attribute in an event filter expressions.

Event

 

typedef struct ems_event_s_t {
    ems_hdr_t          header;
    ems_ulong_int      count;
    ems_attribute_t    item[1];
} ems_event_t;

Event Types

Event Type Schema

 

typedef struct ems_event_schema_s_t {
    ems_event_type_t    type;
    ems_string_t        name;
    ems_long_int        size;
    ems_attribute_t     attribute[1];
} ems_event_schema_t;

Event Type List

 

typedef ems_event_schema_t     *ems_schema_ptr_t;

typedef struct ems_event_type_list_s_t {
    ems_long_int        size;
    ems_schema_ptr_t    schema[1];
} ems_event_type_list_t;

Event Filters

Attribute Operators

 

typedef ems_ushort_int         ems_attr_op_t;

The actual values of the operators are:

 

#define ems_c_attr_op_eq     (0)
#define ems_c_attr_op_gt     (1)
#define ems_c_attr_op_lt     (2)
#define ems_c_attr_op_ge     (3)
#define ems_c_attr_op_le     (4)
#define ems_c_attr_op_ne     (5)
#define ems_c_attr_op_bitand (6)
#define ems_c_attr_op_substr (7)

Event Filter Grammar

 

typedef unsigned16 ems_filter_grammar_t;
const ems_filter_grammar_t ems_c_fg_default   =  0;
const ems_filter_grammar_t ems_c_fg_OQL       =  1;
const ems_filter_grammar_t ems_c_fg_other     =  2;

OQL stands for Object Query Language.

Default Event Filter Grammar

 

typedef struct ems_default_fg_s_t  {
    ems_string_t        attr_name;
    ems_attr_op_t       attr_operator;
    ems_attr_value_t    attr_value;
} ems_default_fg_t;

Event Filter Expression

 

typedef struct ems_filter_exp_s_t  {
    ems_filter_grammar_t    grammar;
    union  {
        /* case: ems_c_fg_default */
        ems_default_fg_t    def_filter;
        /* case: ems_c_fg_OQL */
        ems_string_t        oql_filter;
        /* case: ems_c_fg_other */
        ems_string_t        other_filter;
    } tagged_union;
} ems_filter_exp_t;

Event Filter Expression List

 

typedef struct ems_filter_exp_list_s_t {
    ems_long_int            size;
    ems_filter_exp_t        filter_exps[1];
} ems_filter_exp_list_t;

Event Filter

Filters with event type of generic, can only have filter expressions with header attribute names in them (see Event Header Attributes ).

 

typedef struct ems_filter_s_t {
    ems_string_t             filter_name;
    ems_event_type_t         type;
    ems_filter_exp_list_t    filter_exp_list;
} ems_filter_t;

Event Filter Name List

 

typedef struct ems_filtername_list_s_t {
    ems_long_int             size;
    ems_string_t             filter_names[1];
} ems_filtername_list_t;

Event Filter List

 

typedef ems_filter_t *ems_filter_ptr_t;
typedef struct ems_filter_list_s_t {
    ems_long_int             size;
    ems_filter_ptr_t         filter[1];
} ems_filter_list_t;

Consumer Data Structures

Consumer

 

typedef struct ems_consumer_s_t {
    ems_string_t          name;
    ems_netname_t         *hostname;
    ems_uuid_t            uuid;
    ems_delivery_t        type;
} ems_consumer_t;

Consumer List

 

typedef struct ems_consumer_list_s_t {
    ems_long_list         size;
    ems_consumer_t        consumer[1];
} ems_consumer_list_t;

Event Handler

 

typedef void (*ems_handler)(void * arg, ems_event_t * event,
              ems_error_t * error);

Supplier Data Structures

Supplier Event Handler

 

typedef void (*ems_supplier_count_handler_t)(ems_event_type_t type, 
                           ems_long_int count, ems_error_t * error);

Supplier

 

typedef struct ems_supplier_s_t {
    ems_string_t           name;
    ems_netname_t          *hostname;
    ems_uuid_t             uuid;
    ems_delivery_t         type;
} ems_supplier_t;

Supplier List

 

typedef struct ems_supplier_list_s_t {
    ems_long_int           size;
    ems_supplier_t         supplier[1];
} ems_supplier_list_t;

Attribute and Event list

Attribute List

 

typedef struct ems_attrlist_s_t {
    ems_long_int           size;
    ems_attribute_t        attr[1];
} ems_attrlist_t;

Event List

 

typedef ems_event_t *ems_event_ptr_t;

typedef struct ems_event_list_s_t {
    ems_long_int           size;
    ems_event_ptr_t        event[1];
} ems_event_list_t;

Event Service Handle

Event Service Handle

 

typedef void *ems_handle_t;

Status Codes

Rather than list the specific status codes for each routine, the following summary lists all the status codes and their meanings.

ems_s_already_registered

Consumer with this name is already registered.

ems_s_consumer_already_started

Consumer already started.

ems_s_consumer_not_started

Consumer not started.

ems_s_empty_filter_db

The listed filters could not be returned because the filter database is empty.

ems_s_event_type_exists

The event type to be added already exists.

ems_s_event_type_not_found

The specified event type was not found.

ems_s_filter_exists

The given filter name already exists.

ems_s_filter_in_use

The filter cannot be deleted because it is currently in use.

ems_s_filter_not_found

The requested filter does not exist.

ems_s_forwarding_event_service_not_there

The event service to forward to is not available.

ems_s_forwarding_event_loop

The hostname introduces a loop condition, where XEMS would be forwarding events to itself.

ems_s_insufficient_permission

Caller does not have sufficient permission to perform operation.

ems_s_invalid_event_type

The schema for the event type is not valid.

ems_s_invalid_filter

The input parameters specifies an invalid filter.

ems_s_invalid_handle

The handle parameter is not valid.

ems_s_invalid_name

The name parameter contains invalid characters.

ems_s_no_consumers

No consumers are registered.

ems_s_no_event

Tried to pull an event of a specified type, but there are no events to pull.

ems_s_no_events

There are no undelivered events.

ems_s_no_memory

An XEMS handle cannot be allocated.

ems_s_no_suppliers

No suppliers are registered.

ems_s_no_type_list

There was no type list in the function invocation.

ems_s_status_ok

Success.

ems_s_unknown_consumer

Tried to unregister a consumer that was not registered.

ems_s_unknown_supplier

Tried to unregister a supplier that was not registered.

ems_s_unsupported_nameservice

Unsupported nameservice on host name.

Footnotes

1.

The underlying transport is responsible for the data representation changes between clients and servers.