The GEM Equipment Interface Applications

Contents

Introduction

Installation

The SEMI Standards

Using the Gemhost and Gemsim Applications

The Gemsim Command Line
The Gemsim User Interface
Understanding the Gemsim Application
The Gemhost Command Line
The Gemhost User Interface
Gemhost Message System Integration
Understanding the Gemhost Application
The GEM Supervisor Application


Building Equipment Interfaces

SQL Table Schema

Document Version

(C)Copyright 2001, 2008 Hume Integration Software
All Rights Reserved

Introduction

Hume provides a GEM compliant equipment simulator application, gemsim, which is a starting point for developing GEM interfaces for real equipment, as well as a useful tool for developing, demonstrating, and testing host software.  An equipment manufacturer deploys a GEM interface by revising and extending the gemsim application using Tcl programming, or by using the GEM application as a background process, and controlling it from his own application software.  Hume Integration has developed several examples demonstrating how this can be done from different programming environments.  The newest example is the .NET SecsPort Component which can be used from any of the .NET languages including C#, Visual Basic, C++, and Java.  The SecsPort Component exposes all of the usual GEM equipment capabilities in a native .NET CLS-compliant API.  The SecsPort Component documentation has more detailed information on the built-in SECS/GEM message handling and data items than are presented in this document.  This document is mostly oriented towards the Host developer, whereas the SecsPort Component document is exclusively for the Equipment developer. In addition to the .NET SecsPort, there is also the Java SecsEquipLibrary, the Visual Basic Active-X SecsEquip Control and the Visual C++ SecsEquip library which offer nearly the same comprehensive feature set as the .NET component for the Java 2 platform or the established Visual platforms.

The Tcl/Tk Host GEM-EI Applications, gemhost and supervisor, are designed to interface with equipment that conforms to the GEM standard without any custom coding.   Configuration information is obtained dynamically through communication with the equipment, and saved in SQL data tables.  A graphical user interface is provided for defining and managing event reports,  alarm reports, initiating remote commands, and  managing recipes.  But not all SECS equipment is GEM compliant. The Host GEM-EI Applications are also designed to accommodate non-GEM equipment, often with little or no custom Tcl code needed.  The basic functions such as capturing event reports and alarms, and managing recipes, will work for any equipment that supports the underlying SECS messages.  When custom code is needed, whether to accommodate equipment variations, or to fulfill custom integration requirements, the GEM-EI software provides a well designed framework for organizing and accomplishing the effort.  A directory is provided for user written custom Tcl logic that can replace or supplement the provided code. For host developers who prefer other programming language platforms, Hume Integration provides the features of the Tcl/Tk supervisor application for the Java 2 Platform, and also for .NET.

The GEM-EI applications can use any of the SECS connection variations supported by the Datahub SDK:

• HSMS on ethernet LANs
• SECS-I using RS-232 ports
• SECS-I with direct connections to TCP/IP terminal servers

• VFEI 2.2 command messages are accepted in mailbox name_VFEI.
• SQL commands are accepted in mailbox name_SQL for remote data access.
• Tcl language commands are accepted in mailbox name_RPC which enables remote inspection or remote interaction with the EI.
• Asynchronous VFEI messages such as alarm and event reports are sent to a configurable mailbox destination.  This has been a useful mechanism to tie the Host EI drivers into higher level software such as the Hume Event Processing Component for the purpose of controlling production activities and monitoring equipment utilization.  With a small amount of customization, a different format, for example XML, could be used for the notification messages.

The integrator can create subscriptions to SQL data tables that are activated when new equipment events occur and the table data is changed.  The subscription mechanism provides an elegant interface such that the integrator does not need to change the GEM and SECS logic that acquires the equipment data in order to use it in new ways.  Some possibilities include:

• Integrating with .NET, Visual Basic, Java, or Visual C++ applications using the DMH message system.  The POSIX C DMH client is also available for applications that are portable between POSIX systems such as Linux and HP-UX, and Windows.
• Using the Tcl  socket command, or the Tcl comm command as a high level interface to TCP/IP or to a serial device.
• Creating text files, and using the Tcl exec command to activate another program.
• On Windows systems, using the Tcl odbc command to integrate with a ODBC database.
• Using third party or custom Tcl extensions to interoperate with other messages systems or protocols such as XML-RPC, or SOAP.  Extensions can be dynamically loaded into dmh_wish, or the Hume provided GEM-EI features can be dynamically loaded into your custom Tcl/Tk executable.

Installation

The SEMI Standards

• SEMI E4 - SEMI Equipment Communication Standard 1 - Message Transport (SECS-I)
• SEMI E5 - SEMI Equipment Communication Standard 2 - Message Content (SECS-II)
• SEMI E30 - Generic Model for Communications and  Control of SEMI Equipment (GEM)
• SEMI E37 - High-Speed SECS Message Services (HSMS) Generic Services
• SEMI E37.1 - High-Speed SECS Message Services Single-Session Mode (HSMS-SS)

The SEMATECH Virtual Factory Equipment Interface Version 2.2 standard is available through SEMATECH as Technology Transfer document 95113016A-TR.  VFEI describes a text message based programming interface to integrate semiconductor manufacturing equipment into factory information systems.
 

SECS Basics

To communicate with the equipment, you have to know the connection information.  For a SECS-I RS-232 cable connection, you need the baud rate, and the equipment's device ID.  Use a break-out box or other RS-232 tools to make sure your cable connection is proper;  you only need to connect lines 2, 3 and 7.  You may need to swap lines 2 and 3.   For an HSMS LAN connection, you need to know the IP address of the equipment, the TCP/IP port number, and the device ID.  Always try to ping the IP address or hostname to establish that the network is functioning properly.

Equipment expects to see its own device ID in messages that are directed to it.  You should know what it is or configure it to a known value.  You set the device ID in the gemhost software by setting the array element DEVID.  You can set this on the command line, or in your custom version of the gemhost script as explained later.  Newer versions of the Hume GEM Host software have logic to automatically correct the DEVID value, if the equipment implements standard error messages.

Each data item in a SECS messages is a specific low level type such as a 2 byte unsigned integer.  There are variations is the specific data types used, and the specific message formats used.  Your driver application should readily accommodate this, by not being fussy about the type codes in received messages.  You should elevate yourself and work with data items as strings.  You can work with data values such as "2" or "0" in your application logic, and then supply the proper type code when you format messages to the equipment.

For many command messages, SECS defines multiple replies indicating different reasons for failure.  We suggest that you avoid coding for different failure reasons as much as possible.  It is difficult to test intricate conditional logic.  Write straightforward, maintainable code - the transaction either succeeds or fails.  For the things that fail, leave log messages that can be viewed after the fact.

Using the Gemhost and Gemsim Applications

Most users of this package will want to focus more on understanding the gemhost application than the equipment role.  Because of the requirements of GEM, the gemsim equipment logic is a little more complex than the host side.  The equipment needs to respond differently to messages depending on whether its offline, online in local control, or online in remote control.  Whether your focus is the host or the equipment role, we suggest you get comfortable with the following resources.

• The user interfaces of the gemhost or gemsim applications.  For both applications, three separate windows are provided that offer different views of the application.  Follow the instructions below to get the applications running and communicating.  Then spend some time exploring the Trace windows, the Data Table window, and the User Interface windows.  Be sure to explore the Tracing menu on the Trace windows.  Being able to dynamically change the detail of traced information is invaluable when it comes to building and debugging your own applications.
• The online documentation.  Most HTML browsers will let you open several browser windows so you can easily view multiple documents at once.  If you are new to Tcl, the syntax of the language is summarized in .../mann/Tcl.html.  The secsport and hsms commands are explained in the .../mann/secsport.html document.  These commands are used to create and manage SECS protocol communication connections.  The .../mann/TSN.html document describes Tcl SECS Notation.  This is the text representation of SECS binary messages that is used for sending or receiving SECS messages from Tcl code.
• The inspect application.  This application can attach to an interpreter running on the same display, or can attach to an interpreter that is receiving messages from the DMH message system and executing them as Tcl statements.  Inspect gives you the means to dynamically examine and change the Tcl procedures and global data items of the attached application.  You can also use inspect to execute manually entered Tcl statements in the target application.  This is commonly used during development to source a revised version of the Tcl application code.
• The pertinent SEMI and SEMATECH standards.

The Gemsim Command Line

$ gemsim "set PORT /dev/tty01" &

C:\usr\local\gem\equip> gemsim "set PORT :5556,S"

$  gemsim "set PORT :5556,S" &

The gemsim application also recognizes the global variables PASSIVE and HOST which can be used from the command line to specify the HSMS active role. Usually HSMS equipment is a passive listener on the default network interface of the computer that it is running on. To start the gemsim application so that it actively attempts to connect to a passive host, a command line such as the following may be used:

gemsim "set PORT 5555" "set PASSIVE 0" "set HOST 192.168.2.14" &

The Gemsim User Interface

GEM Equipment User Interface

This window provides an operational user interface for the equipment.  The window is divided into sub panels each of which controls different aspects of the equipment.

 

The Communications panel gives you two push buttons to enable or disable communications.  The current communication state is shown.  Upon startup, before the host connects, the state will be "ENABLED {NOT COMMUNICATING}".  On this panel, there is a button labelled "Edit Startup...".  Use this button to bring up a configuration dialog that lets you set the desired connection, communication, and control properties for the next time the program is started.

 

The Control panel provides switches that conform to the GEM control model.  With GEM, the Communications state indicates the ability for the host and the equipment to communicate, but the Control state characterizes the equipment's responsibility to act upon the received messages.   The operator can choose for the Control state to be Off-line or On-line.  In the Off-line control state, the use of messaging for automation purposes is severely restricted.   If the operator choose to go online, the gemsim application will not respond to further presses of the On-line/Off-line radio buttons until the communication attempt to the host has succeeded or failed.  With HSMS, the button can seem stuck on Off-line because the communication attempt fails immediately if the host is not connected.  The local and remote pushbuttons affect the On-line control state.  With real equipment, the local and remote choices affect the degree to which the operator or the host interface is in charge of processing.

 

The Alarms panel provides buttons to Enable, Disable, Set, Clear, or Add alarms.  Alarms will be reported when they transition from Set to Clear, or from Clear to Set, if they are Enabled for reporting.  The panel shows which alarms have been defined, and what their current Enable/Disable and their current Set/Clear states are.

 

The Processing panel allows the operator to select a PPExecName (a Process Program Name or "recipe"), and then choose to Start running it.  While the process program is running, other buttons can be used to Pause, Stop, or Abort.  A Paused process run can be Resumed using another button.

 

The Terminal Services panel allows the equipment operator to send a message to the host, and to view and acknowledge a message that the host has sent the equipment.

 

The Spooling panel shows you the status of SECS message spooling.  The "Spooled Msg Types" indicates the SECS streams or streams and functions that have been configured to be spooled and corresponds to the status variable SpoolStreamFns.  The host configures this value using S2F43.  The operator can clear this value using the "Stop Spooling" button, or choose specific streams using the "Configure..." button.   The "In Spool" count corresponds to the status variable "SpoolCountActual" which is a measure of the number of messages currently spooled.  The "Max In Spool" count corresponds to the equipment parameter "SpoolMax" which is the limit on the number of messages that can be spooled.  The "Input Total" count corresponds to the status variable "SpoolCountTotal' which is the count of messages handled by the spooling logic since spooling last began.  If this value is bigger than "Max In Spool" it indicates that the spool was filled and data was lost.  The "Purge Spool" button empties the spool.

 

gemsim Trace window

This window is the usual trace window that can be displayed for any secsport or hsms communication connection.  The window is used to display the messages that the gemsim application sends and receives.  Also, trouble-shooting information such as displaying communication attempts and low level protocol state changes are available, if you check the corresponding item choices under the Tracing menu button.  The Send menu can also be handy - you can cause the binary echo message to be sent, or the S1F1 "Are you online?" query to be sent.  The items under the Object menu let you Reset the state of the connection.  The Reset action causes the interface to stop expecting any outstanding replies, and to discard any messages that have become queued for sending.  Also under the Object menu, the Show action will display the data items stored in the gemsim array.   Under the Replay menu there are actions to re-send or re-receive SECS messages. There is also the Window... action to bring up a separate Replay Window. The replay actions are extremely useful during development; you can update your Tcl logic on the fly, and artificially cause a previous message to be re-received or re-sent. The Replay window has actions to save and restore message conversations as well as re-send or re-receive selected displayed messages. Under the Window menu button, there are actions to save the current window data to a file, to append the current data to a file, to clear the current data from the window display, to dismiss the window, or to Exit the program.  If you dismiss the window and later want to recreate it, you need to have the gemsim Tcl interpreter execute the command "gemsim tracewin".  You can get a Tcl command prompt using the window described next, or by attaching to the gemsim interpreter using the inspect application.

 

gemsim Data Tables

The Data Table window is the same user interface obtained by running the Datahub application.  The gemsim application uses in-memory SQL tables to manage its data.  You can use this windowing interface to interactively examine or modify any of the table data.  Under the File menu button, select the Refresh action to see the list of tables that are currently in use, and the number of data rows in each table.  Also under the File button, there are actions that provide additional windows for the execution of SQL statements or Tcl commands.  Other menu items are available to execute files that contain Tcl statements or SQL statements, or to Exit the program.  The Table menu has action items to display the schema or data of the tables that are selected in the list on the Data Table window.

Understanding the Gemsim Application

If you are creating a GEM interface for your equipment, you want to understand how to add your own alarms and events to these tables, and then how to initiate alarm reports and event reports from the appropriate contexts in your control software.  According to GEM, the setting and clearing of an alarm are reportable events in their own right.  The simulator design is to number alarm ID's from 1000 by two's.  Even numbers are used for both the alarm ID (ALID) and the alarm set event ID (CEID).  The odd numbers are used for the alarm clear event ID.  Therefore for each alarm type, there is one record in the ei_alarm table and two records in the ei_event table.  The ei_report and ei_event_report tables get populated when the host side uses SECS messages to define data collection reports, and to link defined reports to events.  At startup, both these tables are empty.

The data items that the equipment manages are configured in table ei_variable.  The data items are distinguished by class as represented in the varclass field.  Class "SV" data items are Status Variables.  From the standpoint of the host, these are read-only variables whose values can be reported in event reports or individually queried.  They should always have a valid value.  Typical process equipment Status Variables are observable quantities such as temperatures and pressures.  Another class is "ECV" is the acronym for Equipment Constant Variable.  These variables can have their values set or queried by messages from the host.  Each ECV type variable has a minimum, maximum, and default value, as configured in the fields ECMIN, ECMAX, and ECDEF.  These variables are used for configurable operation parameters such as setpoints or processing options.  The ECV variables are usually independent of the processing characteristics that are controlled from information in Process Programs (recipes).  The remaining class is "DVVAL",  representing Data Value Variables.  These are similar to SV items except they may not always have a valid value.  An example would be the "AlarmID" variable whose value is the current alarm identifier (ALID) at the time an alarm is set or cleared.  The host interface could ask for this variable in a report to be sent with an alarm set or alarm clear event report.  However, it makes little sense for the host to ask for the value of this variable whenever the process state change event is reported.

To support your own variable definition, add a row to the ei_variable table following an example of one of the rows that is already there.  You can add the row manually using the Data Table user interface, or you can add an SQL insert statement to the Tcl code.  In the varmethod column, you supply the Tcl code to be executed to obtain the current value of the variable.  The Tcl code "return $varvalue" indicates that the value of the variable is obtained by using the current value stored in the field varvalue.  This is adequate for relatively static data whose value is maintained in the table.  A dynamic item such as the Clock variable is configured to call a procedure to obtain the current value.
 

The Gemhost Command Line

c:\usr\local\gem\host> gemhost "set PORT :5556"

$ gemhost "set PORT :5556" &

$ gemhost "set PORT 192.168.2.4:5555" "set HSMS 1" &

$ gemhost "set PORT 192.168.2.4:5555" "set HSMS 1" "set DEVID 5" &

When using HSMS, the host side typically plays the active role, using network communication calls to actively find and connect to the passive equipment. The passive and active roles can be reversed if needed. You can specify the passive role for the host using the global data item PASSIVE:

$ gemhost "set PORT localhost:5555" "set HSMS 1" "set PASSIVE 1" &

The Gemhost User Interface

Host Equipment Interface - "gemhost"

The Host Equipment Interface window is divided into five panels; Communications & Control, Alarms, VFEI Reports, Processing & Process Programs, and Terminal Services.

 

The Communications & Control panel shows the current communication and control states.  When you start the application, the communication state will be "ENABLED {NOT COMMUNICATING}".  When the gemhost connects successfully to the equipment you see "COMMUNICATING".  The control state of the equipment, ON-LINE or OFF-LINE is also displayed.  There are two buttons to request that the equipment go ON-LINE or go OFF-LINE.  These buttons cause the S1F17 or S1F15 request messages to be sent.  The button labeled "Trace Window" is used to raise or create the Trace window.  The button labeled "Comm Enable/Disable" is used to toggle the state of communication; enable if it is disabled, or disable it if it is enabled.

 

The Alarms panel has a list of the alarm types that are known to the host interface, and whether they are enabled or disabled for reporting, and whether they are currently Set or Clear.  Buttons are provided to enable or disable selected alarms.  There is also a Save button that records which alarms you have enabled or disabled in a file.  When you perform an initialization, the interface enables or disables the alarms according to what you have configured.

 

The Processing & Process Programs displays the current Process State, and the current PPExecName (Process Program Name or "recipe") .  The Refresh button is used to query the equipment for these items as well as for the resident process programs which are then displayed in a list.

 

If the Refresh button does not show this information for your equipment, your equipment may not support it, or you may need customize the pertinent queries.  The code driving the window is in the file .../gem/host/host_ui.tcl.  The Process State and PPExecName items are displayed by subscribing to variable items in the ei_variable table where the VFEIname is PP_EXEC_NAME or PROCESS_STATE.  You can fix the display of these items by assigning these VFEIname values to the rows in the ei_variable table that have the corresponding data items but were named differently by your equipment manufacturer.  In other words, update just the VFEIname fields of the data items that represent the process state and the PPExecName to the standard VFEI names PROCESS_STATE and PP_EXEC_NAME.

 

The Select button is used to change the current PPExecName to the one selected in the Process Programs list.  Ordinarily you cannot do this unless the equipment is idle.  The Upload and Download buttons are used to upload and download Process Programs using the Tcl procedures defined in file ei_recipes.tcl.  Finally there is a row of buttons named Start, Pause, Resume, Stop, and Abort.  These buttons cause the corresponding remote commands to be issued to your equipment.  The configuration of the remote commands is represented as corresponding rows in the ei_variable table.  It is likely that you will need to update the varvalue fields for these commands to make them correspond to the SECS commands used by your equipment.

 

The Terminal Services panel is used to send a text message for display at the machine, and to display messages that are sent by the equipment to the host.  If the equipment supports the operator acknowledging the message, per GEM it comes up as an event report.  The gemsim application sends acknowledgments with the event ID (CEID) of 4100.

 

The VFEI Reports panel is used to create, edit, and save report definitions as well as perform related online actions.  The "Initialize" button causes the configured event reports and alarm configuration to be setup at the equipment.  The "Enable Events" button requests that the equipment enable and report all of its events.  The "Data Refresh" button is used to query the equipment about the variables that it supports.  Usually this action occurs automatically when the gemhost software first obtains an online control state with the equipment.  The "Event Discovery" button attempts to determine which events the equipment reports by enabling all of them, and then querying for the value of the "EventsEnabled" variable.  GEM equipment is supposed to support this Status Variable, but the equipment manufacturer is free to use a different name.  If the equipment uses a different name, update the variable's entry in the ei_variable table, and give it the VFEIname EVENTS_ENABLED before using the "Event Discovery" button.   You only need to execute "Event Discovery" once to determine the events.  If your equipment does not support the "EventsEnabled" variable, use the "Enable Events" button to make sure the reports are enabled, then you work with the equipment to cause it to create events and send them.  The gemhost software receives the events, and stores the event identifiers in the ei_event table.  Using the manufacturer's documentation, you can then update the ei_event table to provide descriptions of the reported events.  These descriptions are seen when you configure event reports, so the time it takes is well spent.  After you have updated the event descriptions, you should press the Save button on this panel to save your work.

 

To setup a VFEI report, you press the Create button and choose the event that you wish to base the report on.  Some of the events are created by the gemhost software, such as the COM_DISABLE event which is signaled whenever communication with the equipment is lost.  The Create button creates an empty event report - one with no variables attached.  You select the Event Report from the list, and press the Edit button to attach variables to the report.  After configuring your reports, you will want to press the Save button to preserve your work for future sessions.  Next, press the Initialize button to have the reports that you have configured be setup at the equipment.  From this point forward, you should get the event reports that you have configured, created as VFEI messages in the ei_vfei_output table.  If you are running as part of a DMH message group, the VFEI event report messages will be deleted from this table after they have been transferred to the VFEI_OUTPUT_MAILBOX, a configurable parameter that is specified in the ei_variable table.

 

gemhost Trace Window

This window is the same type as in the gemsim application, described above.

 

EI Data Tables Window

As with the gemsim application, the gemhost provides the user interface of the datahub application for your convenience in managing the SQL tables that are used by the equipment interface logic.  See the description above.

Gemhost Message System Integration

$  dmh_server gem &

$  gemhost "set MB_GROUP gem" &

The gemhost script and the host.tcl scripts setup the following message system functionality by default.  First, the gemhost process will receive from the mailbox gemhost_SQL.  Messages that are received in this mailbox will be treated as SQL commands just as if the gemhost application is a datahub.  You can use the hubclient application with the target of this mailbox and the DMH group to remotely inspect the data tables of the application.  For example if the gem server was running on the host, cimdev:

$ hubclient gemhost_SQL@cimdev:gem &

$ inspect gemhost_RPC@gem &

secs_DMH_reply spname sfr {tsn {}} {replybox @defaulted@}

The GEM host application will also open the gemhost_VFEI mailbox to receive VFEI commands.  When your factory system software sends a command, it can optionally specify a mailbox name where the reply message is to be sent.  Look at the documentation for the mbx putr Tcl command or commands such as mbx_do_xact that build upon the mbx command..  Sending the INITIALIZE command from your factory system software might look something like this:
 

       mid_vfei_init gemhost

       # initialize the specified machine
       proc mid_vfei_init {mid} {
           global transaction_id
           incr transaction_id
           set cmd "CMD/A=\"INITIALIZE\" MID/A=\"$mid\" MTY/A=\"C\" TID/U4=$transaction_id"
           return [do_vfei_cmd $mid $cmd $transaction_id]
          }

       # perform the requested VFEI command hiding the details from the caller
       proc do_vfei_cmd {mid cmd tid {TIMEOUT 120000} {MB_REPLY CELLMGR_XACT} } {
           set reply [lindex [mbx_do_xact ${mid}_VFEI $cmd $MB_REPLY $TIMEOUT] 0]
           if { $reply == "TIMEOUT" } {
               # no response received
               # make it look like VFEI COMM_TIMEOUT
               catch { mbx put TRACE "TIMEOUT on ${mid}_VFEI $cmd" }
               return "CMD/A=\"CMD_ACK\" MID/A=\"$mid\" MTY/A=\"R\"\
                 TID/U4=$tid ECD/U4=40028 ETX/A=\"COMM_TIMEOUT\""
               }
            # the normal reply
            return $reply
            }

VFEI does make for awkward text constructions because it fails to escape the drudgery of specifying data item types.  However, it is a standard, and the vfei_2_array command can be used to efficiently extract the data item values.  Maybe we shouldn't tell you this but the vfei_2_array command, and the gemhost software allow you to get away without specifying the data item types.  Also the quotation marks around the value field are optional if the text does not contain white space.  In other words, the INITIALIZE command example above could have been simplified to the non-standard form:

set cmd "CMD=INITIALIZE MID=$mid MTY=C TID=$transaction_ID"

Understanding the Gemhost Application

The gemhost application is layered so that all of the SECS functionality can be used without VFEI.  The VFEI logic is in separate files, and not inter-mixed with the SECS interface logic.  Synchronous procedures are provided to perform a specific SECS transaction, and return the acknowledgment code of the reply message.  These procedures typically use the secs_xact procedure that is found in ../gem/lib/secs_xact.tcl.  Usually the literal string TIMEOUT is returned if there is no reply, if the transaction was aborted, if a stream 9 error reply was obtained, or if the connection was down.  Your application code can determine the underlying reason for the last TIMEOUT by calling secs_xact_failure.

Here is an alphabetical list of the files in the gem/host directory, with a description of each file's contribution to the application.  Important procedures that you can use in your custom code are mentioned.  We expect you to look at the source code of a procedure and the comments in the source code to see the details of how to use it.  The data item names and return code values are called out by the SECS-II standard.
 

alarms.tcl	Contains code to deal with Alarm Reports. The ei_alarms_init procedure is called early in the application to setup the ei_alarm table, and to synchronize with current alarm status.   The procedure ei_alarm_enable is called to enable specified or all alarm messages.  The procedure ei_alarm_setup is called to setup the reporting of alarms according to the configuration information that is in table ei_alarm.  When the equipment reports an alarm, the ei_alarm_report procedure in this file gets called to process it.  The gemhost application tries to deduce the type code used for alarm identifiers and can usually succeed.  The logic for this is in the ei_ALID_type procedure.
display.tcl	This file contains the ei_terminal_display procedure which is called to display a message and return the acknowledgment code (ACKC10) or TIMEOUT.   An empty message is the usual way to clear the display.
ei_DATAID.tcl	When the code needs to generate a new DATAID (data item identifier) the procedure ei_dataid in this file is called.  The type code used for DATAID's is configured in the ei_variable table, value_TSN field where the varID is 'DATAID'.
ei_RPTID.tcl	The ei_RPTID_new procedure is called to create a report ID (RPTID) when setting up a VFEI event report.  If choosing the CEID of the event does not work for your situation, you need to copy this file and create your own version in the custom directory.  The ei_RPTID_TSN procedure is also defined to provide the type code used for RPTID's.  The type code for RPTID's is configured in the ei_variable table, value_TSN field, where the varID is 'RPTID'.
ei_defaults.tcl	The ei_defaults procedure is used to provide default values for miscellaneous data items, including the alarm, event, and variable tables.
ei_dvval.tcl	The ei_discrete_data procedure in this file is called to process a S6F3 discrete data report.
ei_multiblock_check.tcl	The procedure ei_multiblock_check in this file is called when sending a S2F39 or a S6F5.  If the message would require more than one SECS-I block to transmit, the call obtains permission to send it.
ei_recipes.tcl	Process program manipulation.  The ei_recipe_dir procedure sends S7F19 to obtain the current recipe directory.  The ei_recipe_delete procedure is used to delete specified recipes or all recipes.  The ei_recipe_get procedure uses S7F5 to upload a recipe, and the ei_recipe_put uses S7F3 to download a recipe.
events.tcl	Code for setting up event reports and processing them when they come in.  The following procedures are used to setup event reporting: ei_event_enable, ei_event_disable, ei_report_define, ei_report_link, and ei_reports_setup.  The procedure ei_driver_event is called by the driver software to synthesize an event such as COM_DISABLE.  When the equipment event reports are received, they are processed by the ei_event_ann_rpt or the ei_event_report procedures.
gemhost  gemhost.cmd	The gemhost script processes the command line and defaults, and gets the application started.
gemsystem  gemsystem.cmd	The gemsystem script is an example invocation of the gemhost application as a client of a DMH message server.
host.tcl	The core host side control and communication state logic is in this file.  When you write your own startup scripts similar to gemhost, you can call the ei_init procedure in this file to start your interfaces.
host_ui.tcl	This file contains the logic to draw and manage the Host Equipment Interface window.  You call the ei_ui procedure to create an instance of this window for your equipment interface.
initialize.tcl	This ei_initialize procedure in this file performs a sequence of transactions with the equipment to:  establish communications, obtain the online control state, query the status of alarms and variables, synchronize the equipment clock, set any configured equipment constants, setup event reporting as you have configured it, and setup alarm reporting as you have configured it.
Makefile	This file is used with make or nmake to make sure the tclIndex file is up-to-date.
rcmd.tcl	The ei_rcmd procedure in this file is used to execute remote commands such as START or STOP.  The format used for the remote commands has to be configured in the ei_variable table and is described with the table schema.
tclIndex	This is used by the Tcl interpreter auto_load mechanism so that procedures in this directory can be automatically found when used.
trace.tcl	The procedure ei_trace_setup is used to setup and start trace data reports or to disable them.  When the reports are received, the procedure ei_trace_data processes them and creates corresponding event reports with the CEID of TRACE_REPORT.  This lets you use the same software to process trace data and event reports.  The data item types used to setup trace data reports cannot be detected automatically.  You may need to configure the TRID, TOTSMP, and REPGSZ items in the ei_variable table to indicate the proper value_TSN type code.
vfei.tcl  vfei_mach_cmd.tcl  vfei_move.tcl  vfei_resource.tcl	The procedure ei_vfei_cmd in the vfei.tcl file is used to execute VFEI command strings.   The return value of the procedure is the VFEI formatted reply.  Other procedures in this file, and the files that start with vfei_ support executing the different VFEI commands.  Users of VFEI should call the ei_vfei_cmd procedure to execute VFEI commands from the driver process.  VFEI commands from other processes should be directed to the DMH VFEI input mailbox for the particular equipment connection as described above.
vfei_output.tcl	The logic for managing asynchronous VFEI output, namely alarm reports, and event reports, is in this file.  A VFEI message is added to the output by calling the ei_vfei_output procedure.  The usual VFEI initialization sets up subscriptions to the ei_alarm_log and ei_event_log tables to create VFEI output messages for these events.  The VFEI output gets staged in the ei_vfei_output table.  The ei_vfei_send procedure gets activated by subscription, and after the VFEI output message is transferred to its DMH mailbox destination, it is deleted from the ei_vfei_output table.  The VFEI output mailbox is configured by the value of the VFEI_OUTPUT_MAILBOX record in the ei_variable table.

 

The GEM Supervisor Application

The supervisor application accepts the same command line arguments as the gemhost application.  If connection specific items such as PORT, HSMS, PASSIVE, and DEVID are specified, they are used if you only have a single equipment startup configured.  As you configure the startup of your own interfaces, you supply all of the connection parameters in a dialog, and the command line arguments are not needed.  As discussed with the gemhost application, you can optionally specify MB_GROUP on the command line to indicate a DMH message system connection.
 

The GEM Supervisor User Interface

The row of buttons labeled "Startup Configuration" includes the following:

New...

This button is used to create a startup configuration for a new interface.  The configuration dialog is discussed under Edit... below.  Once you have created a startup configuration, you can Start it.  As discussed with the gemhost application, most of the important configuration data such as the variables supported by the equipment, will be discovered dynamically.

Edit...

This button supports revising the startup record.  The "EI Startup Configuration" dialog is presented.  This dialog is used to configure the basic information needed to connect to SECS equipment, including the SECS Device ID, and the connection type. Additionally, there are checkboxes to disable the queries that normally occur during initialization.

 

First, consider the connection type. If you choose a SECS-I serial connection type, you need to supply  a serial device name such "COM1" or "/dev/ttya".  If the BAUD field is left blank, the default value of  9600 is used.  Other connection types are TCP/IP based.  For these cases, you need to supply a TCP/IP port value, sometimes called a socket.  You optionally specify a hostname or IP address for the equipment or terminal server.  If the hostname field is left blank or set to localhost, the software will attempt to connect on the host where it runs. HSMS connection types can be passive or active. Usually the passive checkbox is left unchecked, and the host side plays the active role.

Now consider the options to customize the usual initialization logic. The default choice is for all of the custom initialization checkboxes to be selected and this works fine in most situations. You may have equipment that has a very large number of status variables, equipment constants, or alarm types. If you are connecting to this equipment through a slow SECS-I link, you may want to disable querying for the definitions of these items, or querying for their values during the initialization because it takes too much time. In these situations, we recommend that you have all of the queries enabled once, that you capture and save the table information, and thereafter startup with the queries disabled.

Modern GEM equipment uses S1F13 to initiate communications. Most of the equipment that does not use S1F13 will reject the message using Stream 9. In this case, the logic of this application will gracefully substitute using S1F1 instead. The option to disable S1F13 completely is for defective equipment that does not use S1F13 to initiate communications, and furthermore has problems if it receives S1F13.

Copy...

Use this button to copy (clone) an interface configuration to a new name.  You will need to Edit... the startup configuration to point to another connection.  The copied data is not saved by this action - it only exists in memory.  Use the "Save Tables" button to save the data.

Delete...

After confirmation, the selected interface configurations are deleted from the in-memory database.

The buttons in the row labeled "Equipment Interface Actions" are:
 

Start

This action starts the interface running.  You will see the Trace and UI windows appear.

Stop

This action does a shutdown of the equipment interface.  The associated windows are destroyed.

GUI

This action raises or creates the User Interface window of the selected interface.  Unlike the Start button, this action does not enable or change the state of communication.  So this button can be used to obtain the User window without enabling communication.

SECS Trace

This action is used to raise or create the Trace window.

Last, the row of buttons labeled "Supervisor Actions" includes:
 

Refresh

This button is used to refresh the status information in the list of equipment interfaces.  You are able to determine which equipment connections are running and what their communication state is.

Save Tables

If you have not started any equipment interfaces, pressing this button causes your current startup configurations to be saved to the file system in the file ei_startup.tab.   If you have started an interface, then the application logic has loaded any previously saved application data so you are offered a choice of whether to save all of the in-memory application table data, or to just save the startup table. 

Host Tables

This button brings up the Datahub user interface.  You can browse and work directly with your application SQL table data.

Tcl Console

This button brings up a command prompt to interactively work with Tcl code.  It is equivalent to the Tcl Command... menu item on the Datahub File menu.

Exit

After confirmation this action stops all the equipment interfaces and terminates the program.

 

Building Equipment Interfaces

First, give each equipment interface a unique, memorable name instead of the default  name gemhost that we have been using.  If you have already been configuring the interface using the gemhost name, use the supervisor application to copy the interface to a new name of your choice.  You can then delete the gemhost interface.  Use the supervisor application to configure the startup of as many equipment interfaces as you want.  Start them with the names of your choice, and do the configuration effort.  When you have multiple machines of the same type, configure the first one, and then copy the configuration to different names for the others.

You can run dozens of equipment interfaces from a single process on a Unix workstation without any performance problems.  You can run multiple interfaces on Windows as well, although other things being equal, Windows is not as efficient with context switching or exec'ing child processes.  You will probably want to distribute your equipment interfaces across different processes and different computer systems from the standpoint of risk management.

You may wish to develop your own custom startup script based on the gemhost or supervisor scripts.  If you choose to do so, copy the gemhost or supervisor script to the gem/custom directory.  You can execute your modified startup script from the gem/custom directory, or from another directory that is a subdirectory of the gem directory.  The logic that sets up the auto_path variable in the stock gemhost or supervisor script was written to accomodate these variations.  You may want to create specific directories underneath gem that start sets of related interfaces, and contain the custom code for the particular set(s).   One of the key ideas of having your own directories, or using the custom directory, is that you keep your custom code, and custom file versions separate from the files distributed by Hume Integration.  It is easier for you to synchronize with newer versions of the GEM-EI - you can install the latest version in its normal place without the installation overwriting any customization that you have done.  The auto_path mechanism works well with the custom directory scheme.  The auto_path variable is set so that procedures which are defined in the custom directory or the startup directory are found and used instead of the stock versions supplied by Hume Integration.  When you need to customize a procedure, you copy the whole file that it is defined in to your custom directory.  You can then edit it to your liking.  You type "make" or otherwise insure that the tclIndex file in your custom directory is up-to-date with respect to the Tcl files contained in the directory.  If you fail to copy the whole file, the stock version may be sourced when one of the other procedures in the file is used.

It is common to want to customize the initialization of the equipment that the host performs. Here we are primarily referring to the logic found in the file host/initialize.tcl and in the procedure ei_initialize. Most of the behavior is controlled by the configuration data held in the SQL tables; for example setting equipment parameters, defining dynamic reports, or selectively enabling various alarms. The data-driven configuration logic is satisfactory for most circumstances. There also is a call made to the procedure name ei_custom_init occuring at the end of initialization. This is a procedure that does not exist unless you provide your own procedure definition, so the procedure call is done in a catch statement. The procedure is called with a single argument, the name of the equipment connection. If you write this custom procedure, your code should return 0 to indicate success, or any other positive integer to signify an error result. The intention of providing this call is to make it easy for you to add custom initialization and setup logic. The default configuration executes the initialization logic every time the equipment transitions into an online control state.

In general, you want to run development applications in foreground with all of the windows usable (like we have been doing), and you want to run production applications disconnected from the window system, so they are not stopped by user logouts or window system problems. On Windows NT you can install the production equipment interface logic to run as a service.  This means that the interface will be started when the system reboots, and no one has to login.  You can do this using the SRVANY program that comes with the Microsoft Windows Resource kit.  On Unix, you can edit your startup scripts to run the equipment interfaces upon reboot.  The -notk option should be specified on the command line to tell the dmh_wish interpreter not to use X-windows.

Here are the steps in constructing your custom interface(s).

1. Start your interface with your chosen connection name and connection parameters.
2. Hopefully your equipment is standard enough to report most of its variables.  If not, you need to manually add the ones you'll work with to the ei_variable table.  Use the gemhost/gemsim data as examples.  You can use the Datahub UI or edit the SQL statements in the saved .tab file.
3. Use the application UI to characterize the useful data and event notifications that come from the equipment.   Update the parameters in ei_variable table as needed.  Use the "Event Discovery" button or the "Enable Events" button, collect events, and update the event descriptions as needed.  Whenever you change the configuration tables, be sure to save them.
4. Enable/Disable alarm reporting to your liking.
5. Create and Edit the event reports to your liking.
6. Discover your need for customization and deploy your changes.

You can replace an equipment variable or supplement the equipment variables by supplying your own logic.  Suppose you do not like the SECS standard format of the CLOCK variable.  You can update the CLOCK row in ei_variable and change the varclass field from "EQ" to "SECS_DRVR".  This tells the software that the value is not obtained from the equipment, it is obtained from the SECS driver software.  Update the varmethod field to "localtime 9" and whenever the CLOCK value is used in events, the value will be formatted as "YYYY-MM-DD HH:MM:SS".

You may find that a few stock application procedures need changes.  Copy the affected files into your custom directory, make your changes, and then rebuild your tclIndex.

We suggest that you limit driver software functionality to forwarding VFEI event and alarm messages to higher level software, and accepting VFEI commands from higher level software.  This gives you maximum re-use of your equipment drivers.  In the higher level software you can build elaborate state machine configuration tools, utilization tracking, MTTA, MTBF reporting, business rule engines, and the like.  Your drivers can be "plugged" and "unplugged" as supported by attaching or unattaching to the DMH message system.  Because of the way you have partitioned the driver level, the higher level tools can easily be applied across all of your equipment.
 

SQL Table Schema

Most of the tables are loaded from the file system during the application startup.  As the application runs, new rows may be added, or rows may be updated.  By default, there is no logic to save the table data before shutting down.  Typically, if you make changes, you need to explicitly press a save button on the configuration user interface to preserve your changes for next time.  You can also save the data tables programmatically by using the SQL write command.
 

Table Directory

ei_alarm  ............. Alarm Configuration and Status Data

ei_alarm_log .......... Alarm Instance Data (Host Only)

ei_dataset_xfer ....... Data Set Transfer Data

ei_equipment .......... Equipment Startup Data (Equipment Only)

ei_event .............. Event Configuration Data

ei_event_log .......... Event Report Instance Data (Host Only)

ei_event_report ....... In-use Event Report Associations

ei_event_report_cfg ... Configured Event Report Associations (Host Only)


ei_ppid ............... Upload Process Program Descriptions (Host Only)


ei_report ............. In-use Report Definitions

ei_report_cfg ......... Configured Report Definitions (Host Only)

ei_spool_data ......... Messages Spooled for Host Retrieval (Equipment Only)

ei_startup ............ Configuration of Equipment Interface Startups (Host Only)

ei_trace_active ....... Active Trace Data Collection (Equipment Only)

ei_trace_setup ........ Trace Data Collection Configuration (Host Only)

ei_variable ........... Data Item Configuration and Status

ei_vfei_output ........ VFEI Output Message Data (Host Only)
 

Schema Notes

Boolean Values

Boolean values are usually stored as integers (also referred to as int).  In this convention, 0 indicates false and 1 is the preferred value of true.  However it is usually the case that any non-zero value is acceptable as true.

Key column

Under Key the abbreviation PK indicates that the field is a primary key of the table.

The abbreviation PCK indicates that the field is part of a primary composite key for the table.  In other words, the field and one or more other fields, taken together, are the primary key for the table.  There can not be multiple rows in a table that have the same value of the primary key.

The host populates this table by asking the equipment which alarms are enabled using S5F7, and what the alarms are using S5F5.  This happens in the procedure ei_alarms_init in the file .../host/alarms.tcl.  The host is able to find out all of the alarm information by asking, or by saving each alarm when it is reported if S5F5 and S5F7 are not supported.  You can supply your own alarm descriptions in the field ALTX for equipment that reports blank alarm descriptions.

The equipment GEM software uses this table to manage alarm reporting. The data in the table can be loaded at startup from a file of SQL statements such as created by the SQL write command. A convenience procedure, eq_alarm_add, defined in file gem/equip/eq_alarms.tcl, is also available to add new alarms using Tcl code. Equipment software reports alarm set or clear conditions by updating the is_set field for the particular alarm using the SQL update statement. The GEM equipment software is then triggered by a table subscription, and it takes care of sending the alarm report and the associated GEM data collection event to the host. The reporting logic allows for the possibility that the alarm or event are possibly disabled, or that the communication may be broken and the reports need to be spooled. The reporting logic is also found in the gem/equip/eq_alarms.tcl file.
 

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
ALID	PCK	varchar(20)	A unique identifier for the alarm defined by the equipment.  It is usually an integer, but it is saved and manipulated as a text string.
ID_TSN		varchar(8)	The Tcl SECS Notation type code for the ALID data item when passed in a SECS-II message.  The host discovers the ID_TSN from equipment originated messages.  An example would be I4, signifying a signed 4 byte integer.  See the TSN reference documentation.
category		int	Alarm category.  The value 0 means category is not used.  The GEM standard does not use the encoding of category in alarm reports.
is_enabled		int	This field is used to store the current alarm setup state; whether the alarm is enabled for reporting or disabled.
is_set		int	This field is used to store the current status of the alarm - whether it is set (1) or clear (0).
ALTX		varchar(40)	This is the alarm description which is usually reported by the equipment when reporting an alarm.  If the equipment does not report the ALTX (the reported value is blank),  the host GEM-EI software will check this table for a possible description.
host_managed		int	Host usage only. If this field is non-zero, it means that the host should either enable or disable the alarm when performing the equipment initizalization.
host_wants_enabled		int	Host usage only. The value in this field indicates whether the alarm should be enabled (1) or disabled (0) if the host_managed field is non-zero.
set_CEID		int	Equipment usage only. Per GEM, the setting of an alarm causes a data collection event. This field holds the CEID, collection event ID, which is fired when the alarm is set.
clear_CEID		int	Equipment usage only. Per GEM, the clearing of an alarm causes a data collection event. This field holds the CEID, collection event ID, which is fired when the alarm is cleared.

The host inserts a new row into this table every time an alarm report is received.  The is_set value represents whether the alarm was reported as set or clear.

If you are using VFEI, the data in this table is deleted after the VFEI message representing the alarm report is successfully forwarded to your VFEI output mailbox, or is inserted into the ei_vfei_output table.  The VFEI logic is activated by subscription to the ei_alarm_log table.  The ei_vfei_outsub procedure is called which is coded in  .../host/vfei_output.tcl.

If you are not using VFEI, you need to supply your own logic to prune the rows in this table.  You will typically want to delete a row after successfully passing it on to the higher level software, or code a limit to the number of rows, or age of rows kept in memory.  If you do not limit the memory use, the application will eventually crash.
 
 

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
clock	PCK	varchar(16)	The time of the alarm report formatted as YYYYMMDDHHMMSScc.  This value will be unique for the particular spname.
ALID	PCK	varchar(20)	A unique identifier for the alarm defined by the equipment.  It is usually an integer, but it is saved and manipulated as a text string.
is_set		int	The reported status of the alarm - whether it is set (1) or clear (0).
ALTX		varchar(40)	The alarm description provided by the equipment with the report, or the text from the ei_alarm record.

The data in this table is used to manage Stream 13 data set transfers.  There is status information in the table which is useful for monitoring Stream 13 transfers or diagnosing problems.  The data set transfer logic is in the files gem/lib/dataset_xfer.tcl and gem/lib/ei_ppid.tcl.  The transfer logic uses a subdirectory of the recipe directory for large file transfers so that replacement files do not overwrite their destinations until they are received completely, and so that process program files do not appear in directory listings until they can be verified.
 

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
HANDLE	PCK	varchar(16)	The type code and handle value used by the opposite party in the dataset open message, S13F3.
is_send	PCK	int	Used as a boolean to indicate whether the data set is being sent (1) or received (0).
dsname		varchar(200)	The data set name which is also a Process Program ID (PPID).
pathname		varchar(500)	A full pathname to the file being transfered.  When sending from equipment, this will be a temporary copy of the file in the transfer directory.  When sending from the host, this is a file in the recipe directory.  When receiving, this is a file in the transfer directory.
channel		varchar(20)	When sending, an open file is used.  This field value is the channel identifier from the Tcl open command.
timer_handle		varchar(20)	This field holds handle values returned from the Tcl after command for timers that are used to check whether the opposite party has been timely with sending expected messages.
pid		varchar(12)	The process identifier of the process which opened a file for sending.  In the scenario of making this table peristent and resuming incomplete transfers, you would want to check for your own process ID before closing a channel.
ts_begin		varchar(26)	A high resolution timestamp in the local timezone (localtime format 15) when the row was created.
ts_close		varchar(26)	A high resolution timestamp in the local timezone (localtime format 15) when the transfer became inactive either by completing successfully, or by being cancelled.  Cancellation occurs by the opposite side closing the HANDLE using S13F7 or S13F9.  Cancellation can also occur during initialization or upon re-starting a dataset transfer which ended with error.
readln		int	This is the read size either provided by the requestor in S13F5 or figured out by the receiver when handling S13F4.
reclen		int	This value is the maximum read size returned by the sender in S13F4.
rtype		int	This value is the <rtype> value returned by the sender in S13F4.
ckpnt		int	This value is the checkpoint value received in the latest S13F6 reply.
status_code		int	This value is 0 if the transfer is proceeding without error.   A non-zero status_code usually indicates that the transfer has ended without success.  However, status codes indicating transfer conversation timouts do not indicate a failure end - the transfer can still succeed if the opposite party continues.  The following codes are used: 0 - normal error free progress 1 - cannot resume receive (no partial file, or no partial results) 2 - open attempt failed 3 - read attempt failed 4 - open reply had improper data 5 - open reply had ACKC13 error code 6 - open reply had a changed HANDLE value 7 - open reply had a changed DSNAME 8 - open reply had an unknown RTYPE 9 - open reply had discrete records with record length of 1 meg or larger 10 - read reply had improper data 11 - read reply had ACKC13 error code (not EOF) 12 - read reply had changed HANDLE value 13 - read reply, transfer table record missing 14 - read reply, partial file missing 15 - read reply, file open error 16 - read reply, data was not type B or A 17 - read reply, file writing error 20 - file error when preparing read reply 21 - S13F1R offer attempt failed 22 - S13F1R offer reply data error 23 - S13F1R offer reply error code reply 24 - cannot create transfer directory 25 - timeout waiting for S13F1 offer 26 - timeout waiting for S13F3 open 27 - timeout waiting for S13F5 read 28 - timeout waiting for S13F7 close 29 - cannot delete old file to receive replacement 30 - verification attempt failed 31 - downloaded dataset failed length verification
status		varchar(80)	A brief description of the status code or the latest success state.

The gemsim Tcl application uses this table to save and restore its startup configuration.  During startup of the gemsim application, if there is a saved .tab file for this table in the default directory, and there is a row in the table for an inteface named gemsim, then the data of the row is used to set the properties of the interface.   The included data items meet the requirements of SECS and GEM for properties that are enduser configurable and persistent.  In addition, there are fields to make the preferred settings of tracing and logging persistent.

Timer values are stored as milliseconds.
 

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
port		varchar(200)	The rs232 device name for serial connections or the [hostname:]port for HSMS connections.
auto_start		int	Whether the interface should be started when the program is started.
BAUD		int	The baud rate for serial communication.
DEVID		int	The SECS device ID.
MULT		int	Set to 1 to indicate when using SECS-I whether the host can handle more than one active message conversation at a time.
RTY		int	The SECS-I retry count. This count establish the maximum number of send retry attempts for block transmission.
T1		int	SECS-I Receive intercharacter timeout.
T2		int	SECS-I Protocol timeout for block transfer.
T3		int	Reply timeout.
T4		int	SECS-I Inter-block timeout.
T5		int	HSMS Connect Separation timeout. Specifies the delay between connection attempts.
T6		int	HSMS Control Transaction Timeout.
T7		int	HSMS Not Selected Timeout. If a TCP/IP connection does not transition to an HSMS Selected connection within this interval, the TCP/IP connection is broken off.
T8		int	HSMS Network Intercharacter Timeout. Not used in this implementation.
TRACE		int	Used as a bitfield to control diagnostic output.
comm_enabled		int	A boolean field to indicate whether communication is enabled at startup.
controlIntentOnline		int	A boolean field to indicate whether the equipment should seek being online.
controlModeRemote		int	A boolean field to indicate whether remote control is preferred to local control when online.
controlStateStartup		int	An enumerated value to set the desired GEM control state at startup.  Possible values are 0 for Offline Equipment, 1 for Offline and seeking to be online, 2 for Offline Host, 3 for Online local control, and 4 for Online remote control.
hsms_passive		int	For an HSMS connection, whether the equipment plays the passive, TCP/IP server role.
hsms_protocol		int	Set to 1995 for a standard HSMS connection type.
traceMax		int	When file logging of trace data is enabled, the maximum number of day files allowed.  Range 1..366.
traceZipCmd		varchar(80)	This field has the configured value of the log file compression command which is used when file logging of trace data is enabled and compression of log files is enabled.
traceDir		varchar(200)	This field holds the configured value of the file logging output directory.

The host populates this table as it encounters new event reports from S6F11 or S6F13.  In general there is no way for the host to deduce meaningful names or descriptions for the equipment originated events.  In the case of Hume-based equipment interfaces, the status variable EventDescriptions may exist in which case the host will use the provided  list of all the events and their descriptions.  Otherwise, event descriptions are created by manually updating this table using information provided by the equipment vendor.  When descriptions are available, the creation and maintenance of event reports is made easier.   The integrator may also wish to provide virtual names for events by manually editing the table.

Some event records such as COMM_DISABLE represent events that are created by the host driver software instead of the equipment.  So they can be received even when your equipment does not support event reports.

The following events are currently defined by the host GEM-EI software:

AUTO_VIRT_INIT

When the host interface is started, or it is seen that the equipment has transitioned from an offline to online state, the host interface software will attempt an initialization sequence, if the AUTO_VIRT_INIT parameter stored in the ei_variable table is configured true.  When the initialization sequence is completed, the event is signalled.  The success or failure of the initialization can be determined using the AUTO_INIT_RESULT variable.  Typically an event report is defined so that the CLOCK and AUTO_INIT_RESULT are reported with the AUTO_VIRT_INIT event.

COM_DISABLE

This event is reported when communication with the equipment is lost.  The latter is detected by a broken TCP/IP connection, or a broken SECS-I transaction.

COM_ENABLE

This event is reported when communication with the equipment is successfully established.

TRACE_REPORT

This event is reported when a S6F1 Trace Report message is received.  You can define event reports based on the TRACE_REPORT event to pass the trace data into the same software that is used for event reports.

When an event report is received, the included data values are used to update corresponding fields in the ei_variable table.  Then a new row is added to the ei_event_log table.

If you are using VFEI, a subscription to the ei_event_log table sees that the event has occurred and pulls together the configured VFEI report.  The VFEI report may use different data items than the set provided in the event report.  In any case, after the VFEI message is created, the original ei_event_log record is deleted.

If you are not using VFEI, you need to supply your own logic to limit the number of rows stored in this table. 
 
 

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
clock	PCK	varchar(16)	The time of the event report formatted as YYYYMMDDHHMMSScc.  This value will be unique for the particular spname.
CEID	PCK	varchar(32)	The identifier for the event.
data		varchar(20000)	A proper Tcl list containing {name value} pairs for the variable values received in the event report.

This table is used to store the actual, in-use association of events and data reports.  It is used to help implement procedures that configure reports, and link them to data collection events.
 

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
CEID	PCK	varchar(32)	The identifier for the event.
RPTID	PCK	varchar(32)	An identifier for a SECS level report - A report is an ordered set of variables whose values can be reported in association with an event.

This table is used to store the configured association of events and data reports.  The GEM configuration user interface simplifies the configuration of event reports by hiding the existence of low-level reports and the possibility of linking multiple reports to data collection events.  The interface creates only a single report with the RPTID equal to the CEID.  The RPTID is configured to have the equipment supported variables (class EQ) that are desired for the specific event.
 

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
CEID	PCK	varchar(32)	The identifier for the event.
RPTID	PCK	varchar(32)	An identifier for a SECS level report.

This table is used by the host software to save the Process Program identifiers and datatypes for uploaded files.  In general, a Process Program Identifier, PPID,  used on the equipment may not be a valid filename.  During transfer of process programs to the host, the PPID is mapped to a valid filename.  A row in this table is created to save the mapped value of the PPID and the SECS datatype used to transfer the process program data.  The data of the table is made persistent by saving a refreshed version after a process program upload, and loading the saved table data for each interface before adding new data.   The table is saved as a file of SQL statements, name ei_ppid.tab,  in each host instance's recipe sub-directory.  Only the table rows that pertain to a particular host instance are saved in that instance's recipe directory.  In order to use uploaded  process program files, the ei_ppid.tab file should be preserved with the uploaded files.

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
filename	PCK	varchar(250)	The filename of the uploaded process program without the directory path.
ppid		varchar(250)	The PPID, process program identifier, as specified by the equipment

This table is used to store the actual report definitions that are currently setup on the equipment or that are currently in use for VFEI event reports created by the driver software. The rows in this table are usually added after the successful initialization of configured event reports.  Basically a report is an ordered set of variables.  The reports are linked to data collection events, and when those events occur, the current values of the report variables are obtained.

The VFEI report definitions have RPTID values that start with the character sequence "vfei_" as a prefix to the actual CEID used by the equipment or created by the driver software.  For example, a RPTID value of vfei_4050  is used to represent a VFEI event report that is reported in the wake of an equipment event with the CEID of 4050.  A VFEI report that is tied to COMM_DISABLE is given a CEID of vfei_COM_DISABLE.

Report definitions that are not like 'vfei_%' represent actual reports that are setup or have been received from the equipment.
 
 

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
RPTID	PCK	varchar(32)	An identifier for the report.
VIDs		varchar(1000)	An ordered list of the varID's from table ei_variable for equipment based reports.  An ordered list of VFEIname's from table ei_variable for VFEI reports.

This table is used to store the configured report definitions that are typically defined using the configuration user interface.  The rows in this table are used during the initialization of the equipment.  The initization logic attempts to make the actual, in-use configuration of reports mirror the data in this configuration table.  If the initialization logic is not performed, the configured event reports are not setup, and the specified reports are not obtained.  Also, if this table, and related configuration tables are not saved after configuration changes are made, the configuration changes are not present during the next session.

The VFEI report definitions have RPTID values that start with the character sequence "vfei_" as a prefix to the actual CEID used by the equipment or created by the driver software.  For example, a RPTID value of vfei_4050  is used to represent a VFEI event report that is reported in the wake of an equipment event with the CEID of 4050.  A VFEI report that is tied to COMM_DISABLE is given a CEID of vfei_COM_DISABLE.

Report definitions that are not like 'vfei_%' represent actual reports that can be setup on the equipment.  The configuration logic creates reports that have the same RPTID as the CEID that the report is tied to.  The user's simplified configuration model is that he directly associates a set of variables to be collected for a given event.  The existence of reports as a separate entity is hidden.
 
 

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
RPTID	PCK	varchar(32)	An identifier for the report.
VIDs		varchar(1000)	An ordered list of the varID's from table ei_variable for equipment based reports.  An ordered list of VFEIname's from table ei_variable for VFEI reports.

This table is used  by the equipment  for the purpose of spooling messages.

This table should not be edited directly by software or by manual actions.  Doing so risks breaking the spooling logic.  The procedure eq_spool_purge may be called to purge the spool.

The spooling logic attempts to keep the contents of this table saved on the file system in the subdirectory "spooldata", using the filename "spooldata.sql".  This file is read during startup so the state of spooling is persistent from one session to the next.

Spooling can be enabled by the host using S2F43, or using the User Interface.  Once spooling is enabled, the host needs to purge or unload the spool everytime communication is established in order for the SECS interface to behave normally.  If the spool is not purged or unloaded, and it is active when the host is communicating with the equipment, the host does not receive any primary messages originated by the equipment except for Stream 1.
 
 

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
ts	PCK	varchar(26)	The "localtime 15" timestamp when the message was spooled.  This information is not required by GEM, and not used by the software.  It is stored to help decide when purging the spool is appropriate.  The presence of the field as a key also insures that views of the table data are ordered as expected.
sequence		int	The spooling logic uses this field as an index to determine the ordering of spooled messages.
sfr		varchar(10)	The stream, function, and optional reply flag of the spooled message, such as "S5F1R"
data		varchar(100000)	The SECS-II data of the message in TSN notation.

This table is created and used when you run the Tcl/Tk host supervisor application.  The supervisor also provides a user interface to configure the records in this table.  The table is also used for the SECS server host applications which supports .NET, Java, and other platform clients.  The SECS server host applications use fields in this table that are not used by the Tcl/Tk host supervisor application.  This table does have fields that could be used to configure the startup of equipment role interfaces which are not used.  The Hume provided equipment applications use the separate table ei_equipment for their startup configuration in order to avoid inadvertant overwriting of another application's startup configuration.
 

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
parent		varchar(32)	not used - defined to manage sub-equipment
status		varchar(60)	Used to indicate the EI connection status on the supervisor display list.
EQUIP		int	Used as a boolean by the SECS Server to indicate the equipment or host role.
por