Introduction

Feature Summary

• Consolidated processing of  alarm messages, event messages, data change subscription notifications, timer expirations, error conditions, or other inputs as events.
• Managing and processing of arbitrary context data with events.  Context data is modifiable as it passes through the processing pipeline.
• Filtering of input events, mapping of input events to different identifiers, and mapping of the associated physical or state machine identifier.   Mapping of events can also depend on context data values.
• Execution of application logic based upon pattern matching of input events irrespective of state.
• Selective execution of application logic depending on state; table driven execution of multiple finite state machines.
• Execution of application logic triggered by state transitions.
• Configurable logging and saving of events and state changes.
• Configurable diagnostic tracing of event processing with a remote viewing application.
• Simplified access to SQL table data as global arrays with high performance, and with configurable persistence.
• Consistent and direct naming of states and events using dotted pathnames (ie., periods are used to separate substate names).  Simple and powerful configuration using string matching patterns such as "*.down" matching transitions to any down substate.
• Periodic timer events to support interval-based performance tracking.
• Cancelable one-shot timer events to support interval timing.

Installation

The EPC software is usually installed in its own directory, epc1.0 , as a subdirectory of the Tcl/Tk library directory.  So the EPC files are typically found as /usr/local/lib/epc1.0/*.*. As a subdirectory of the Tcl/Tk library directory, the EPC software can be found and made useable just by executing the statement "package require HumeEPC".

Server  Startup

1. Your application processes start and establish DMH communication to each other.  The datahub Tcl application is commonly used to provide the DMH server function.   If you are running your application as NT services, it is common just to start the DMH server process as a service, and then have the server start the other application processes.
2. If you are using a persistent database, you establish a DMH mailbox for SQL commands directed to the persistent database.  The dmh_SQLsrv Tcl application is commonly used to provide this function.
3. The EPC software is found and made useable by your application executing "package require HumeEPC".  This command will add the EPC installation directory to the Tcl auto_path global variable in the DMH server process so that the EPC procedures can be found.
4. The DMH server process executes the ep_hub_init procedure.  Optional arguments to the ep_hub_init procedure specify the DMH mailbox to be used for receiving EPC events, the persistent database mailbox name, and the type of persistent database in use, such as DB2, ORACLE, or SYBASE.  You may optionally specify an empty string for the EPC mailbox to indicate that EPC should function without reading DMH messages for input.
5. The EPC server logic will create and initialize its own persistent database tables if they do not exist, and a functional connection to the persistent database exists.
6. The EPC server logic will automatically read and initialize its in-memory tables from the saved data in the persistent database.
7. The EPC server logic will also load and initialize the Object Data Component (ODC) to provide simplified, high-performance access to object data.

start dmh_wish -tclargs "proc start args {} ; proc goto args {} ; source startup.bat"

goto EndOfTcl

#

set group APC

set connect "connect MYDB scott tiger"

exec datahub85 "set group=$group" "set server=HUB" eof &

exec dmh_SQLsrv "set group=$group" "set server=DB" $connect eof "eval wm iconify ." &

mbx init $group 4

mbx putr HUB TRACE {eval package require HumeDCC ; dc_hub_init DB SYBASE}

mbx putr HUB TRACE {eval package require HumeEPC ; ep_hub_init EPC DB SYBASE}

mbx end

exit

#

# \

:EndOfTcl

The above batch file is appropriate for development.  A production server is usually started as a service or background process.

EPC  Client Integration

You are not required to use the DMH message system as the input source for the EPC.  By initializing the EPC mailbox value to an empty string, the EPC receives and processes input "messages" that are added to an in-memory queue using the ep_post_event command.

The Hume GEM Host and GEM supervisor applications are able to send VFEI alarm and event report messages to the EPC DMH mailbox.  To demonstrate this capability:

1. Start the application with an additional command line argument such as "set MB_GROUP APC" to specify the DMH message system group name.  If using the supervisor, configure and start a Host interface for your equipment.
2. Check that the varvalue of the VFEI_OUTPUT_MAILBOX record in the ei_variable table is the mailbox name used by the EPC server.  The default VFEI_OUTPUT_MAILBOX varvalue is "equip_box".
3. Use the Host User Interface to define some VFEI reports such as a report whenever the process state changes.
4. Press the Initialize button to setup the event reports.
5. Exercise the equipment in order to have it send some event reports or alarms.
6. Display the contents of the ep_event_log table in the EPC server process.  By default, logging of events is enabled.

Event Processing  Overview

As the event message is received, the timestamp for the event, TS_EVENT,  is obtained by executing " localtime 16".  If the event message format is VFEI, the message is converted to the alternating name and value Tcl list format by the ep_vfei_2_namevals    procedure.  At this point, the TS_EVENT value and the optional message reply mailbox, mbxreply, are added to the event name-value list.

Now that the event data is in standard format, the matching and mapping stage of processing begins using the records in the ep_input table.  If there is already a machine identifier, MID, associated with the event, the class of the machine is looked up to determine which table records to use.  If there is no MID, or the MID class has not been configured, the machine class of "*" is used.  The ep_input table records for the machine class are selected and tested in ascending order by rank.  The first record found, where the event pattern and the data criteria match the input event, is used.  If there is no matching record, the event passes to the next stage of processing unchanged.  The matching record can optionally specify a mapping or transformation of the event_id.  If the event_id is mapped to an empty string, the event is discarded.  If the event_id is changed, the original event_id value is added to the event data with the name event_id_raw.  Next, the record can optionally specify a mapping or transformation of the MID value.  If the MID value is changed, the original MID value is added to the event data with the name MID_raw.  Next, the ep_input table record can optionally specify application logic (field rule_logic) to be executed after the event_id and MID are possibly mapped.  Note that this logic is executed independent of state; so the ep_input table is the place to configure application logic that is always executed when particular events are received.

The next stage of event processing is for state-dependent logic and optional triggering of state transitions using the records in the ep_input_rules table.  You may have changed the MID in the previous stage so the MID class and current state are looked up for the current MID value.  The MID class is found as the MID attribute, MID(MID.class) and the state is found as the MID attribute, MID(MID.state).  These values are stored in the od_attribute table and accessed as global data as explained with the od_attribute table description.  A selection is made from the ep_input_rules table for rows that match the MID class and current state.  The first row found where there is a match between the record event_pattern value and the current event_id is used.  The rule_logic field value is executed for the matching table record.  The return value from executing the rule_logic is examined.  If the return value is one of the values found in the next_state_list field of the record, the return value initiates a state transition to the returned state value, even if it is the same as the current state value.

At this point, if there is any active tracing of the EPC logic, or if the MID(MID.DoEventLogging) attribute value is 1, a record is added to the ep_event_log table.  Tracing occurs when the value of the MID(MID.EventTraceBits) attribute is non-zero.  If you are not configuring the MID(MID .EventTraceBits) attribute value for individual machines, the default value of MID(EventTraceBits) is used.

The following logic applies if a state transition has been initiated.  If the destination state is different than the current state, and MID(MID.DoStateLogging) is non-zero, a record is added to the ep_state_log table.  Next, all of the matching records from the ep_transition_rule table for the MID_class are processed, in ascending order by rank.  The rule_logic values of the matching records are executed.  At the time of execution, the current state of the MID has already been set to the new value.

For a non-VFEI message, if a non-blank reply mailbox is associated with the event, the final name-value list is sent as a reply message.

For a VFEI message that requests a reply, the EPC logic is able to create the standard VFEI CMD_ACK or REQ_QUERY reply message and send it.  You can send other reply formats if needed from the application rule_logic code.
 

Event Processing  Error Handling

1. If the EPC cannot interpret an input message as either VFEI or as a properly composed name-value list, the message is converted to an Error Event with the event_id of ERROR_REPORT.EPC_INPUT.
2. If the input message seems to be VFEI but then is found to be improper, it is converted to an Error Event with the event_id of ERROR_REPORT.EPC_VFEI_INPUT.
3. If an error is encountered when evaluating a data_criteria expression from the ep_input table, an additional event with the event_id of ERROR_REPORT.EPC_DATA_CRITERIA is posted.
4. If an error is encountered when evaluating an event_mapping subst expression from the ep_input table, an additional event with the event_id of ERROR_REPORT.EPC_EVENT_MAPPING is posted.
5. If an error is encountered when evaluating an MID_mapping subst expression from the ep_input table, an additional event with the event_id of ERROR_REPORT.EPC_MID_MAPPING is posted.
6. If an error is encountered when evaluating a rule_logic value from the ep_input table, an additional event with the event_id of ERROR_REPORT.EPC_INPUT_LOGIC is posted.
7. If an error is encountered when evaluating a rule_logic value from the ep_input_rules table, an additional event with the event_id of ERROR_REPORT.EPC_RULE_LOGIC is posted.
8. If an error is encountered when evaluating a rule_logic value from the ep_transition_rule table, an additional event with the event_id of ERROR_REPORT.EPC_TRANSITION_RULE is posted.

Startup and Shutdown Events

Configuration Summary

Data Items

Table Entries

Custom Tcl Code

myproc $event(MID)

1. event( ) is usable as an array with the subscripts being the names of the data items in the current event data.  So $event(MID) refers to the machine name.
2. MID is already declared a global array.  So  $MID($event(MID).state) refers to the current value of the machine's attribute, state.
3. Use "upvar event event" to access the event( ) array from within a called procedure.
4. Use $event(name_value_list) to access the complete set of name value items for the event.
5. If you write to event(name) value, you change the data seen by subsequent processing.  You will be writing the new name value pair name value.
6. Because of the way variable tracing is implemented, there are certain Tcl commands such as unset or incr that will not work on the event( ) array elements until they are read or written to.  The act of reading the variables is seen by the trace logic, and it is the trace logic that creates actual array elements.  Once the array elements actually exist, they can be acted upon by unset, incr, or other commands that test for array element existence before actual use.

The tclIndex file changes are not seen by running processes.  When you are actively developing new code and working with a running process, the easiest way to make sure it is using your new procedures and your new changes, is to use the source command and explicitly load the revised files into the process.  When the EPC is running on a different computer or in the background, you can use the inspect or hubclient applications to get a command prompt in order to enter the source command.
 

Runtime  Logging & Diagnostics

State Modeling

We suggest that the state diagram and flow implied by the records in the ep_input_rules should be for the "politically-correct" state diagram that appears in documentation and standards.  But the reality of finite state machine logic is that you may get an event in any state that tells you that communication is lost or the remote machine has shutdown.  In general, you may not want to diagram the truth; that there are several "bad" transitions from any state.  What you can do is to react to the handful of "bad" events in the ep_input record, and make your own procedure calls to force state transitions and invoke cleanup code.  We think this is cleaner to implement and maintain.  It leaves the state transition diagram implied by the ep_input_rules table understandable, and amenable to neat diagrams and real-time animation.
 

A Sample Application

Server API

Tcl Command Syntax

ep_event_log event_id MID TS_EVENT MID_state name_value_list

None

This procedure is used by the EPC server to create ep_event_log entries.  It can be called from your application logic to create additional log entries, or it can be customized by you.  The source is in the file ep_event_log.tcl.  When called by the EPC logic, the arguments are the context data items for the event.

Tcl Command Syntax

ep_hub_init {MB_EPC equip_box} {MB_DB DB} {DBtype SYBASE}

"Event Processing Component Initialized Successfully." is returned for the usual successful case.

The procedure will return a Tcl error if the system cannot be initialized.

This is the entry procedure to initialize the EPC server framework and then run the server engine.  The call initiates the following processing:

1. Creating the in-memory EPC table schema
2. Creating the persistent database table schema if needed
3. Loading "first-time" data if a new EPC instance is being created
4. Loading startup data from the persistent database or .tab files
5. Initializing the simplified access to persistent attribute and association data.
6. Setting up table subscriptions to keep the in-memory log tables finite sized
7. Calling the ep_server_init procedure to startup the EPC processing logic.

The first argument to the ep_hub_init procedure is MB_EPC, the DMH mailbox name that the EPC should use to receive event messages.  If the mailbox name is specified as an empty string, the EPC logic does not read from a DMH message system mailbox for its input.  In this case, the EPC processes input messages that are added to a queue data structure using the ep_post_event command.

The MB_DB argument is the DMH mailbox of the persistent database interface.  If a persistent database is not being used, the MB_DB argument value should be an empty string.  The optional DBtype arguments specifies the type of persistent database in use, such as DB2, ORACLE, or SYBASE.  For the most part the logic uses portable SQL but there are some differences between database field types and error replies that the software must accommodate.

Tcl Command Syntax

ep_namevals_del name_value_list [ name]+
ep_namevals_diff name_value_list_A name_value_list_B
ep_namevals_get name_value_list name {not_found {}}
ep_namevals_insert name_value_list [name value]+
ep_namevals_nev name_value_list {join_string { }}
ep_namevals_pop name_of_name_value_list name {not_found {}}
ep_namevals_set name_value_list [name value]+
ep_namevals_update name_value_list [name value]+

ep_namevals_del : revised_name_value_list
ep_namevals_diff: list_added_removed_changed
ep_namevals_get: value
ep_namevals_insert : revised_name_value_list
ep_namevals_nev: [name ="value"]*
ep_namevals_pop: value
ep_namevals_set: revised_name_value_list
ep_namevals_update: revised_name_value_list

These are procedures that facilitate working with Tcl lists containing alternating name and value elements.  The lists always contain an even number of elements.  These procedures are used on your behalf by the EPC logic to modify event data which is passed in the alternating name and value format.

The ep_namevals_set procedure is similar to an assignment statement.  It will add new name value elements to a list, or update the values if they already exist.  The procedure ep_namevals_insert is used to add name value elements to a list only if there is not already an existing value for the named items.  The procedure  ep_namevals_update is used to modify existing named values without adding new elements.

The procedure ep_namevals_del is used to delete named items from a list.

The procedure ep_namevals_get searches a list for a named value and returns it, or returns the value of the argument not_found if the named item is not found.  The procedure can also be used to test if a named item exists in a name value list.

The procedure ep_namevals_pop is called with the name of the name_value_list and not its value.  The procedure removes the named value from the list, changing the name_value_list by reference using the Tcl upvar command.  The return value of procedure is the value of the named item, or the value of the argument not_found if the named item is not found.

The procedure ep_namevals_diff compares two name_value_list arguments and returns a three element list of differences.  The three elements of the return value are name_value_lists for the items added, the items removed, and the items that have changed values in going from the first input argument to the second.

The procedure ep_namevals_nev converts the input name_value_list into a string of name=" value" terms.  Imbedded quotes in values are escaped with backslash characters.  The default separation of each term in the result is a single space character.  You are able to specify a different separation string as the join_string argument.
 
 

Tcl Command Syntax

ep_post_event name_value_list {mbxreplybox {}}

None

See the description of acceptable EPC server message formats .  Events that are posted to the EPC server are queued to the EPC server's DMH command mailbox, or to the EPC's input queue, and they are processed in the sequence of posting  You should not supply the TS_EVENT timestamp item with an event unless you have made provision to guarantee unique values.

When the EPC server's DMH command mailbox is an empty string,  the EPC logic does not read from a DMH message system mailbox for its input, it uses a queue data structure.  In this situation you can setup your own mailbox to receive messages from DMH clients and add them to the EPC input queue data structure.  You only need to combine the mbx and ep_post_event commands to do this.  We have created a simple procedure, mbx_EPC, as a "macro" to perform this function.

   # a "macro" to add DMH input to the EPC in-process queue input
   # eg.,   mbx whenmsg EI_EPC mbx_EPC
   proc mbx_EPC { } {
        global mbxmsg mbxreply
        mbx whenmsg again
        ep_post_event $mbxmsg $mbxreply
        }

Tcl Command Syntax

ep_schema_write {filename dc_schema.sql} {DBtype hub}

None

This procedure calls ep_schema and writes the result to a file with each create statement being written as a new line of text.

Tcl Command Syntax

ep_server_init

None

This procedure is called as the last part of the ep_hub_init call.  It calls the ep_server_data_init procedure which you can provide a custom version of, signals the EPC startup by processing the EVENT_REPORT.EPC_STARTUP event, turns on configured table subscription inputs , provides for the call to ep_server_shutdown at exit, and calls ep_server_run.

Tcl Command Syntax

ep_server_run
ep_server_step
ep_server_stop
ep_server_shutdown

None

The ep_server_run procedure is normally called from the ep_server_init procedure.  It causes the EPC server to receive messages that are directed to the $dc_hub(MB_EPC) DMH mailbox.  The ep_server_stop procedure can be used to stop the reception of input event messages.  When reception has been stopped, it can be done one event message at a time using the ep_server_step call.  Continual receiving and processing is resumed using the ep_server_run call.  The ep_server_shutdown procedure is ordinarily executed as part of processing the exit command.  When this call is made, further message input is not received.  The EPC logic is then made to process the EVENT_REPORT.EPC_SHUTDOWN event message.  It does no good to post additional events from your handling of this event since further message input is not received.  The ep_server_shutdown procedure has some logic to wait if needed until the feed of messages to the persistent database has caught up, or has been diagnosed as being unresponsive.

Tcl Command Syntax

ep_state_transition event_id mid_class mid state next_state name_vals TS_TRACE
ep_state_log_transition event_id mid state next_state ts_entry ts_exit

None

The ep_state_transition call is made by the EPC server to process state transitions and execute matching transition rules as configured in the ep_transition_rule table.  The ep_state_log_transition call does the core record-keeping and optionally logging of state transitions without executing matching transition rules.  The reality of programming state machine logic is that the state machine model needs to be "neat" and "politically correct", but that events such as entities going down can happen in any state.  So the real-world solution is to mix in a judicious amount of heavy-handed manipulation of the state machine, without trying to accomplish every state machine transition as part of the regular, configured flow.  The ep_state_log_transition call is the easiest one to make, and it will set the recorded data and ep_state_log records for the new state as if regular processing occurred.  The ts_entry and current state value are usually known from the MID( ) data, so calling the procedure from the rule_logic of an ep_input table record might look like:

ep_state_log_transition $event(event_id) $event(MID) $MID($event(MID).state)\

    "Offline" $MID($event(MID).ts_entry) $event(TS_EVENT)

See ../mann/ep_timer.html

Tcl Command Syntax

ep_trace ts_event text  [text_tag]
ep_trace_flush ts_event
ep_trace_final ts_event text  [text_tag]

None

These procedures are used by the EPC server to collect trace data as it processes events.  Trace data is detailed debugging and diagnostic data showing the flow of processing, including which table records were matched, and the configuration data that was used such as event_mapping and rule_logic values.  The collection of trace data is normally off, since it greatly expands the volume of data added to the ep_event_log table.  When trace data is collected, it is written into the trace_data field of the ep_event_log.  This column only exists in the in-memory schema.  Trace data collection can be controlled per machine instance by setting the value of MID( mid.EventTraceBits).  Similar to other attributes, the value of MID(EventTraceBits) is read and used if a value has not been specifically configured for the machine.  As the name suggests, the configured value is intended to support the bitwise choice of traced data content.  However, for the current software, options are minimal and we suggest you configure the value 15 when tracing is desired, and 0 when it is not.  The traceview application script (traceview.bat) is used to connect to the EPC server and display trace data.

The ep_trace procedure can be called from your custom procedures to provide trace data.  The ts_event argument is the timestamp of the current event, $event(TS_EVENT).  The text argument is ordinary prose which may contain tabs and/or newline characters to create a nicely formatted display.  The optional text_tag argument is used to pass highlighting information to the viewing application.  The following tags are used to indicate the context of trapped errors:

cfg_err - errors with data_criteria evaluation

map_err - errors with event_mapping or MID_mapping evaluation
rule_err - errors with rule_logic evaluation
epc_err - unexpected error within the EPC server code
fmt_err - improper format of input event data

The EPC logic has to begin the collection of trace data for an event before the MID instance is known, and thus before the configuration of tracing is known.  The ep_trace_flush call is used internally to signal that tracing of the event is not desired.  Trace data is written if ep_flush_trace is not called, or if your logic calls ep_trace after ep_trace_flush has been called.  When tracing has been configured off, the EPC framework ordinarily follows the ep_trace_flush call with the ep_trace_final call and writing of trace data does not occur.

Tcl Command Syntax

ep_vfei_2_namevals vfei_message [ts_trace]

name_value_list

This procedure is used by the EPC server to translate a SEMATECH VFEI 2.2 message format into the EPC alternating name and value list format.  There is logic in the procedure to check for selected mandatory data items, and to supply selected default values.  If the message cannot be successfully converted, it is converted into an error report name value list with the event_id of ERROR_REPORT.EPC_VFEI_INPUT.  If the optional argument ts_trace is supplied, and the input format is erroneous, the procedure calls ep_trace to add diagnostic information to the ep_trace_log table record for the event.  The ts_trace argument is passed by the EPC depending on the value of the configuration item MID(*.EventTraceBits).

Tcl Command Syntax

ep_vfei_reply name_value_list

vfei_reply

This procedure is used by the EPC server logic to create reply messages for EPC events that are received in the format of VFEI command messages.  VFEI is a SEMATECH standard format for messages that are used for equipment integration.  This procedure creates the "boilerplate" acknowledgment message,

CMD/A="CMD_ACK" MID/A="<MID>" MTY/A="R" TID/U4="<TID>" ECD/U4=<ECD> ETX/A="<ETX>"

using data items found in the event name_value_list.  The command will prepare a CMD_ACK or RES_LIST reply message.  If you are using VFEI, and supporting the RES_REQUEST or STATUS_QUERY commands, you need to provide your own application logic to create the more complex RES_TRANSFER, or STATUS_LIST reply messages, and to send them, and not rely on the built-in EPC support.    When you send your own reply messages, you remove the "mbxreply" data item from the event name_value_list using the Tcl unset command so that the EPC logic does not attempt to send a second reply.

See ../mann/tsdiff.html

The command is often used with the ep_state_log table records to determine the elapsed time spent in a state given the entry and exit timestamp values.

SQL Table Schema

ep_event_catalog Table - Catalog of Expected Input Events

The EPC accepts text messages sent to its DMH input mailbox which are formatted as:

• SEMATECH VFEI 2.2 messages starting with the character sequences CMD/A= or CMD=.  For example,   {CMD/A="ALARM_REPORT" MID/A="gemsim"  MTY/A="E" ECD/U4=0 ETX/A="" ALARM_ID/I4=1000 ALARM_STATE/U1=1 ALARM_TEXT/A="Software test alarm 1000"}.  The SEMATECH VFEI 2.2 standard is publicly downloadable as Technology Transfer document #95113016ATR through www.sematech.org .
• A Tcl formatted list consisting of an even number of elements.  There are alternating names and values of event data items.  There are at least two elements.  The first element is always the literal text event_id, and the second element is the value of the event_id such as ALARM_REPORT.1000.  Additional pairs of elements are optionally present in no particular order.  This format is simple to prepare or parse in different language environments.  For example, {event_id ALARM_REPORT.1000 MID gemsim ALARM_ID 1000 ALARM_STATE 1 ALARM_TEXT "Software test alarm 1000"}  Note that Tcl is able to parse text strings that are delimited with braces or with double quotes.

ep_event_log Table - History of Events

You should be careful about enabling the saving of event data without having functionality or procedures in place to eventually delete the acquired data from the persistent database.

As a new event record is added to the table, event records that are older than $ts_event - $EPC(EventLogInterval) are removed from the in-memory table.
 

Column Name	Key	Type	Description
ts_event	PCK	timestamp	The high resolution timestamp for the occurrence in the UTC timezone.
MID	PCK*	varchar(32)	A key in the persistent database where the event time can be duplicated in multiple EPC instances.
event_id		varchar(32)	Not part of the key.  Because of serialized processing, no two events will have the same event time.  This is the value of the event_id after mapping.
state_name		varchar(32)	The state of the MID at the time of the event occurrence.
name_value_list		varchar(2000)	The list of alternating name and value elements that contains context data acquired with the event and added to by business rule processing.  The logic examines the field length at runtime and if needed removes name value pairs when saving to make the collected data fit without corrupting its list structure.
trace_data		varchar(80000)	This field only exists in the in-memory schema.  It is used to hold optionally collected trace data.  The column data is formatted as a Tcl list, consisting of alternating text and tag elements.  The tag elements are optionally non-empty to indicate highlighted text conditions such as the presence of errors in the user's executed rule_logic code.  The traceview application script renders the column data as formatted text with color highlights.  See the discussion of the ep_trace procedure.
is_ignored		int	This column exists only in the in-memory tables.  It is used to hide deletes from the persistent database when those deletes are performed for keeping the number of in-memory rows finite.

ep_input Table - Matching, Filtering, Mapping, and Early Processing of Input Events

The identifier for an event can be mapped to a different identifier.  For example, EVENT_REPORT.COM_DISABLE can be mapped to the simpler name, COM_DISABLE.  Often, this mapping is used to convert integer identifiers into meaningful character string identifiers.  It is also desirable to convert the SECS alarm and event identifiers reported by various machines to a common set of values.  For example, it is possible for different Event Reports from different equipment which have the same meaning to be mapped to same Event Report identifier.   It is also possible for the data of an event report to be used as part of the mapping criteria.  For example, alarm reports where the data indicates the alarm is set or cleared, can be mapped to separate alarm set and alarm clear events.

Events can also be ignored from further processing by configuring the mapping of their identifiers to an empty string.

Events are associated with machine instances for the purpose of managing state information and context data.  This table can supply default values for associated machine instances for event reports that do not identify an associated machine.  For example, the EPC can be used to manage business rule processing associated with production Lot processing.  Events and data that are related to production lots can be associated with a state machine name such as "SFC" to create a locus for configuration and runtime context.

The combination of the event_pattern, MID_class, and data_criteria, is used to match input events.  There can be more than one matching record in the table.  The matching record with the lowest rank value is used.  The MID_class is determined from the MID of the event data if found.  If the MID is not found, or the MID_class is not configured for the found MID value, default values are used.  For the as-shipped configuration, the default MID value is "*", and the default MID_class value is "*".

When mapping of the event_id value occurs, the original event_id value is added to the event <name value list> with the name "event_id_raw".  The original event_id may need to be known for debugging and diagnostics, and it may be of use to business rules.  Similarly if the MID value is mapped, the original value is preserved with the name MID_raw.

At configuration time, the user is guided to configure sets of records for a particular class of Machine.   With the MID mapping feature, it is possible that the configuration records for a particular MID_class may affect different MID_classes.  This is something to be mindful of.
 

Column Name	Key	Type	Description
MID_class	PCK	varchar(32)	The class of machines for which the record pertains.
rank	PCK	int	It is possible for more than one record in this table to match an input event.  Therefore, the records are examined in sorted order from the lowest value of this field to the highest, and the first match is used.  It is proper to have repeated values in this field - it is used as a priority indication and not as a sequencing.  The configuration GUI should assign lower values to records that contain a specific event identifier than to records containing the wildcard * character.   Logically this value is not a key column of the table and it is not a key in the persistent database.  This row is declared a key column in the in-memory database to take advantage of the row ordering provided by the keys.  Further, values are restricted to the range from 0 to 9 so that the ordering works correctly when string comparisons are used.
event_pattern	PCK	varchar(32)	A specific event name such as EVENT_REPORT.373 or a string matching pattern such as ALARM_REPORT.* to be used for matching the input event.
data_criteria	PCK*	varchar(500)	Events optionally have associated data attributes.  The data items are accessed as elements of the event( ) array.  A Tcl boolean expression such as $event(ALARM_STATE) == 1 can be entered into this field to restrict the matching of the input events based on the values of associated data attributes.   The expression should conform to the syntax of the Tcl expr command.  Variable names are case sensitive.  The data_criteria expression can also use the global array MID to access machine attributes as in the example,  $MID($event(MID).target) == $event(TOTAL).  The field is declared as part of the table key in the in-memory database but not in the persistent database.
description		varchar(80)	A user provided comment or description that is viewable when configuring input business rules and state machine transition rules.
event_mapping		varchar(100)	The event name to assign to the matched input event for further processing.  An empty string implies matched events are to be discarded.  The value = means that the mapped event identifier should be the same as the input value.  A specific string value, such as COM_DISABLE, is typical.  If the value in this field starts with subst followed by a space, the contents are processed by the Tcl subst command to compute the mapped identifier.  For example, 'subst EVENT_REPORT.[expr $event(ALID) + 1]' could be used to map the value of an alarm report identifier, ALID, to an event report.
MID_mapping		varchar(100)	The machine identifier to be assigned to the event for further processing.  The value = means that the mapped value should be the input value.   If the value in this field starts with subst followed by a space, the contents are processed by the Tcl subst command to compute the mapped identifier.  The MID_mapping capability is useful for providing an MID when there isn't one.  Another use might be to route events for a complex system to separate machines that model simpler components of the complex system.
rule_logic		varchar(2000)	Optionally Tcl code that is executed after matching and mapping of the input event.  The code can read or change the event data by reading or writing values to the array event( ).  An example of calling a procedure with arguments is:    MyEventXInputLogic $event(MID) $event(event_id)  From within a called procedure, access to the event( ) array is obtained by executing "upvar event event".  You can also have inline Tcl statements such as:     set MID($event(MID).state) Unknown  The complete set of name value items for the event is accessible through the array element event(name_value_list).

ep_input_rules Table - Logic to execute upon receiving an event in a specific state

ep_state_def  Table - Definition of Finite State Machine States

ep_state_log Table - History of State Changes

There is an attribute of state machine classes that determines whether the transitions of their machine instances are copied to the persistent database.  It is a good idea to disable persistent saving of state changes unless the saved records are used and there is provision for eventual deletion from the persistent database.

The combination of MID and ts_entry is used as a key for the in-memory and persistent database.  Therefore you cannot share a persistent database across different MID instances of the same name.  The alternative is to also include the EPC instance name as a key in the table, and we do not think that it is worth the added storage consumption.

It is easy to determine the MID_class for an MID using the od_attribute table.  Therefore the MID_class is not copied into each record.

As new records are added to the table, completed rows that are older than $EPC(StateLogInterval) in seconds are deleted.  This is done to keep the amount of data that is resident in memory finite.
 

Column Name	Key	Type	Description
MID	PCK	varchar(32)	The machine instance for which the record pertains.
ts_entry	PCK	timestamp	A high resolution timestamp in the UTC timezone for the instant in which the state was entered.  It is also the same value entered as the ts_exit of the previous record for the machine.
ts_exit		timestamp	A high resolution timestamp in the UTC timezone for the instant in which the state was exited.  Because some persistent databases do not accept empty strings as NULL timestamp values, the ts_exit value is set to the ts_entry value when the record is first inserted.  When the state is exited, the ts_exit value is updated with the actual value which is the same as the ts_entry of the next state.  The time spent in the state, measured in seconds as a floating point value, is easily calculated in Tcl logic by:  tsdiff $ts_entry $ts_exit Because both the ts_entry and ts_exit are provided in each record, it is easy to find the state value at a moment in time by selecting with a comparison expression involving both.  Also, it is easy to traverse the rows for a machine using the ts_entry and ts_exit values.  The timestamp of an event that causes a state transition is equal to the ts_exit value of one record and the ts_entry of another.  So you may wish to think about how you will use the comparison operators if you are attempting to assign the machine state of the trigger event.  Most people would choose (ts_entry < '$ts') and ('$ts' <= ts_exit).
state_name		varchar(32)
entry_event		varchar(32)	The input event_id which triggered the state change to enter into the recorded state.
discard_flag		int	This column is used to hide deletes from the persistent database when those deletes are performed for keeping the number of in-memory rows finite.

ep_subscription Table - Subscriptions opened by the EPC to receive Data Events

For best efficiency, you will ordinarily have only one subscription per table and datahub process.  However, more than one subscription on a table may be a reasonable way to configure complex mapping of the table rows to MIDs.

The epc_hub field is not part of the primary composite key for the table in the datahub, but it is part of the primary composite key in the persistent storage system.
 

Column Name	Key	Type	Description
epc_hub	PCK*	varchar(80)	In order to have more than one EPC instance share a persistent database, they need to be distinguished.   This field is a key in the persistent database but not the in-memory table.  The name of the EPC is usually boxname@groupname.  Some may want to have the hostname be part of the key, so they can have the same groupname on different hosts, and still a shared persistent database.  So, as with DCC, we allow for a global to be already defined as boxname @hostname:groupname per the user's desires.
datahub	PCK	varchar(80)	The value identifies a DMH mailbox name that processes SQL commands, and is the target for where the subscription should be opened.  This field needs to made a key so that upon delete we can identify which table subscription in the distributed system to close.  Persistent databases can have problems with using empty strings in key fields.  Therefore a mailbox name is always specified.  The value is ordinarily a name such as DATAHUB, but it can be groupname qualified name boxname@[host :]groupname.  The target process is expected to have the EPC software accessible through the usual auto_path mechanism.  The value should not be the epc_hub value because the DMH mailbox specified by the epc_hub processes EPC events and not SQL commands.
subtable	PCK	varchar(32)	The tablename for the subscription.  Made a key so upon delete we can identify which table subscription to close.
subname	PCK	varchar(32)	A unique name for the subscription suggested by the configuration software or by the user.  Suggested names are of the form "EPC_${table}" or possibly "EPC_${table}_${N}
MID_expression		varchar(200)	The subscription notifications must be mappable to an MID.  The MID_expression is a Tcl expression such as "FixedName", or such as $ colname, or such as '[my_proc $colA $colB]' which the EPC logic evaluates using the Tcl subst command in context when the table key columns are the names of local Tcl variables.  The evaluation result is the MID value that the subscription notification is mapped to.
subcolumns		varchar(1000)	Either * to indicate all columns or a list of column names.  The column names and values show up as part of the name value list associated with the event.
notifications		varchar(32)	Either * to indicate all notifications or one or more of the words  insert update or delete.  Warning - with an empty string there are no subscription notifications - this is a feature that can be used to temporarily disable a subscription input.
where_clause		varchar(1000)	An optional where clause for the subscription.  Includes the literal "where" keyword if provided.

ep_transition_rule Table - Business Rules to Execute when Leaving or Entering a State

The rule_logic in the ep_input_rules table can optionally initiate a state transition.  When a transition is initiated, all matching records in this table are processed even if the transition is for leaving and entering the current state.
 

Column Name	Key	Type	Description
MID_class	PCK	varchar(32)	The class of machines for which the record pertains.
rank	PCK	int	A user provided value in the range of 0..9 used to set the order of execution.  Records are matched and executed in ascending order by rank.
leaving_state_pattern	PCK	varchar(32)	A specific state name such as product.running or a string matching pattern such as product.*, or *.running to be used for matching the state that is being exited.
entering_state_pattern	PCK	varchar(32)	A specific state name such as product.running or a string matching pattern such as product.*, or *.running to be used for matching the state that is being entered.
rule_logic		varchar(2000)	The code has read/write access to the event data items using the array event( ) as described earlier.  The state being left may be referenced as $event(state) and the state being entered may be referenced as $event(next_state).

License Terms

Document Version

This document covers the Hume Integration Software developed Event Processing Component which is available for the Tcl 8.3/Tk 8.3 environment on the Windows 2000/NT and UNIX/POSIX platforms.