The Hume Tcl/Tk SECS/GEM Applications

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 libraries  for different programming environments using this technique.  These libraries include the .NET SecsPort Component which can be used from any of the .NET languages including C#, Visual Basic, C++, and Java.   In addition there is  the Java SecsEquipLibrary, the Visual Basic Active-X SecsEquip Control and the C++ SecsEquip library for the Java 2 platform or the established Visual platforms.  The C++ library is also available for POSIX platforms such as Linux in addition to Windows.

The Tcl/Tk supervisor host application is 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 managed 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 supervisor application is also designed to accommodate non-GEM equipment, often with little or no custom 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 similar host supervisor applications 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

• 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 messages such as alarm and event reports can be sent to mailbox destinations.  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.  There is also built-in support to subscribe to changes in SQL table data and to distribute or replicate these changes as they occur. 
  

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.
• Using the Tcl httpd package to provide a web server interface to the SECS/GEM software.
  
• 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 host software using the startup configuration dialog, or dynamically by setting the array element DEVID.  The Hume host software has 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 application should readily accommodate this, by not being fussy about the type codes in received messages.  You can work with received data values in your application logic, mostly ignoring the data type, and then supply the proper type code when you format messages to send.

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.   You can add your own messages to the SECS trace and take advantage of the built-in file logging and saving features.  Any messages you write to the connection array element (trace) are added to the SECS trace.

Using the Supervisor and Gemsim Applications

Factory developers 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 supervisor and 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 feature can be used to source a revised version of the Tcl application code.
• The pertinent SEMI and SEMATECH standards.
  
• The Hume SECS Code Generation Tool online.  This tool is able to show you example parsing code for the standard message data formats of SEMI E5.
  

The Gemsim Startup

$ gemsim "set PORT /dev/tty01" &

or 

c:\usr\local\gem2\equip> gemsim "set PORT COM1"

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 and tabbed notebook panes each of which controls different aspects of the equipment.

 

The Communications panel provides a checkbox to enable or disable communications.  The current communication state is shown.  On this panel, there is a button labeled 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 use a checkbox to indicate whether On-line Control is enabled.  In the Off-line control state, the use of messaging for automation purposes is severely restricted.  If the operator chooses to go online, the gemsim application will not respond to further presses of the checkbox until the communication attempt to the host has succeeded or failed.  The local and remote radio pushbuttons affect the On-line control mode.  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 tabbed notebook 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 Process notebook 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 notebook 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 notebook 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 SECS trace window that can be displayed for any secsport or hsms communication connection.  The window is used to display the SECS 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. 

 

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 using Tcl programming, 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.   There is a procedure, eq_alarm_add, in file eq_alarms.tcl to simplify adding new alarm definitions.  To add new event definitions, create your own procedure similar to eq_eventtab_init in file eq_events.tcl. 

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" which you may think of as Equipment Configuration Variables.  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 parameters such as communication timeout values or processing options.  The equipment logic uses the class type PPV to categorize the subset of ECV Parameters that affect processing.  The logic does not allow the host to set values of the PPV items unless there is an online, remote control state.  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. 

The Host Supervisor Startup

The Host User Interface

Host Equipment Interface - "gemhost"

The Host Equipment Interface window is divided into twelve panels; SECS Communication, Control, Reports, Parameters, Variables, PP Transfer, Processing, Alarms, Spooling, Terminal, Conversations, and Status Information.

 

The SECS Communication panel shows the current communication state.  The button labeled Trace Window is used to raise or create the Trace window.  The checkbox labeled Enabled is used to enable or disable SECS communication. 

The Control panel displays whether the equipment is in an offline or online control state.  If the Control State is online, the logic attempts to display the current online substate, whether it is LOCAL or REMOTE.  The button labeled Request Online is used to send S1F17 and the button labeled Request Offline is used to send S1F15.  Proper GEM equipment posts event reports for the control state transitions and these events are monitored to deduce the current control state.  You may need to press the Configure... button on this panel to bring up a dialog which helps you discover and configure which event reports your equipment posts for the control state transitions.  When you are communicating with the equipment, press the Discovery button to deduce what events your equipment reports for these control state transitions.  The dialog can also create example event reports for the transition events if you press the Create Event Reports & Save button. 

The Reports tabbed notebook panel is used to manage report definitions as well as perform related online actions.  The Create, Edit, Delete, and Save buttons are used to change the report definitions and to save them on the file system for the next session.  You are able to assign your own names and descriptions to the various data collection events if you wish.  This virtual naming feature can be used to map similar events from different equipment to the same identifier.  Also, it makes the report definitions easy to understand and maintain; an important consideration in a large factory deployment.  The Initialize button causes the configured event reports and alarm configuration to be setup at the equipment.  With the default startup configuration the Initialize action is performed automatically whenever the host software sees an offline to online control state transition.  Another configurable default behavior is not to delete the existing dynamic report definitions at the equipment when the Initialize logic sets up your desired reports.  The button labeled S2F33 Reset sends a message to delete all of the existing dynamic equipment reports.  You may wish to do this to clear out report definitions that were established in an earlier session or from a different host program.  The button labeled S6F17 Request asks the equipment to send the report defined for a selected event type.  The button labeled Example Reports looks at the variables in use and tries to define some useful event reports.  Use this action after you have communicated with the equipment.  On the right side of the panel there is a scrolling display of recently received event reports.  Use the Clear button to empty this list.  The button labeled Event Discovery 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 All Events" checkbox to make sure that all event reports are enabled, then work with the equipment to cause it to create events and send them.  The host software receives the event reports, 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 it is worth doing for notable events.  After you have updated the event descriptions, you should press the Save button on this panel to save your work.

The Alarms tabbed notebook 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 to a file.  When you perform an initialization, the interface enables or disables the alarms according to what you have configured.

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.

gemhost Trace Window

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

 

Host Tables Window

As with the gemsim application, the supervisor 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.

Supervisor Message System Integration

$  dmh85_server gem &

$  supervisor "set MB_GROUP gem" &

When used with the DMH, the supervisor application and the host.tcl scripts integrate with the message system as follows.  First, when starting the SECS interface of the name gemhost, the process receives using the mailbox named gemhost_SQL.  Messages that are received in this mailbox will be treated as SQL commands just as if the host 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 &

Understanding the Supervisor Application

The new Conversations feature greatly simplifies adding custom message handling to your application.  The framework uses asynchronous callback mechanisms that avoid complex problems of nesting, sequencing, and re-entrant execution  that occur when synchronous send-and-reply code is deployed in this asynchronous domain.   There are times however, when the simpler programming model of the synchronous send-and-reply are desirable.  In the Tcl source code you will find some useful synchronous procedures to perform specific SECS transactions such as querying a variable value.  These procedures typically use the secs_xact procedure that is found in ../gem2/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.  The design of secs_xact allows for the receiving of new primary messages from the equipment such as event reports while waiting for a reply message.

Here is an alphabetical list of the files in the gem2/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.  Many of 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_clock.tcl	Procedures to work with clock (time) values.  There are other procedures dealing with clock values in ../lib/secs_clock.tcl
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_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.
ei_RPTID.tcl	The ei_RPTID_new procedure is called to create a report ID (RPTID) when defining an 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'.
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 single SECS interface 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 SECS User 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 ECV's, 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 which is how unknown procedures are located.
rcmd.tcl	This file supports legacy applications.  New applications can define and customize conversation items to perform Remote Commands.
SecsHost.tcl	This file has procedures that were originally created for use of the Tcl/Tk host SECS features from .NET and Java.  Some of the procedures are useful for Tcl/Tk developers such as ei_send, ei_pp_upload, and ei_pp_download.
supervisor supervisor.cmd supervisor.tcl superwin.tcl	The supervisor application.
*.tab	SQL table save files that are created only when you perform Save actions.
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.
variables.tcl	This file has procedures related to working with variables including the creation of configuration records in the ei_variable table.  The procedure ei_var_query is useful for obtaining the current values of a list of variables.  You can see examples of using ei_var_query in the host_ui.tcl file.
vfei.tcl  vfei_mach_cmd.tcl  vfei_move.tcl  vfei_output.tcl vfei_resource.tcl	The use of the SEMATECH VFEI command strings is not encouraged for new applications.   Our host applications feature the virtual naming concepts of VFEI because it is useful to make different equipment appear alike to the factory.  Using VFEI as a command language however is cumbersome and complex compared with using Tcl language commands. 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 can be directed to the DMH VFEI input mailbox for the particular equipment connection. The logic for managing asynchronous VFEI output, namely alarm reports, and event reports, is in file vfei_output.tcl.  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 Host 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.  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/tty01".  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 almost 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 configuration variables, 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

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 - the performance will be more than adequate.

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 gem2/custom directory.  You can execute your modified startup script from the gem2/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.

Don't go creating a lot of custom SECS logic without understanding what the Conversations feature can do for you.  You can configure Send items so that they execute whenever there is a transition to an online control state.  Similarly, when you define your custom Receive items, the Hume application takes case of having your message handling code registered to receive messages without you explicitly adding initialization code.  When you save your Conversation items, the interface name is not saved with the items.  Therefore, you are able to load Conversation items that you have created and saved for any other interface.  There is also intelligent handling of merging, or replacing Conversation items as you load additional items from files.

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.  The -notk option also works on Windows where it causes the windows to be hidden from the desktop user.

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

1. Find out or configure the connection properties of the equipment.   You probably need help to be able to login to the equipment and make sure that the SECS communication is enabled, and to determine what the connection properties are.   Getting tool time without access to the tool system menues can be an exercise in frustration.   The factory priorities are likely to interface with heavily used tools first.  However, as a practical matter, your access to these tools is limited.  If you are a newbie, do your learning with a brand new tool before it is turned over to production and while the vendor installation rep is present.  You will have plenty of access and knowledgeable help to get the connection established.  Any issues such as having the proper SECS/GEM documentation are promptly addressed by the installer and vendor.  Once you have some experience, you will be able to make the most of your limited access to the high priority production tools. Your rollout plans for the factory should include interfacing to all new tools before they are turned over to production - this is the smart way to proceed for the long term in contrast to competing for tool time on production systems.
   
2. Establish the physical connection with the proper SECS-I cable or network gear.   Typically an HSMS tool interface is configured from the factory to have a static IP address.  For characterization you can configure a laptop computer with an IP address on the same network and plug the tool and your laptop into a small network switch.  In a production scenario your host computer and the tool are on a more permanent network.  Prove that your network connection is functional by using the ping command with the tool's IP address.
   
3. Start your interface with your chosen connection name and connection parameters.   Communication should occur within seconds if all of the preconditions are met.  Get the tool into an online control state using the Request Online button or by working with the tool's SECS communication menu.
   
4. 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.
5. 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 All Events checkbox, collect events, and update the event descriptions as needed.  Whenever you change the configuration tables, be sure to save them.
6. Visit the Control state Configuration... dialog and see if the Discovery feature is successful in determining which event reports your equipment uses to report control state transitions.  The Create Event Reports & Save is intended to quickly create reports so that you can monitor the control state.
   
7. Enable/Disable alarm reporting to your liking.
8. Create and Edit the event reports to your liking.
9. 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 host driver software functionality to forwarding event and alarm messages to higher level software, and accepting 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_dvvals ....... Event and DVVAL Variable Associations (Equipment Only)


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 gem2/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 gem2/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(120)	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.

There is a requirement for stable operation that data rows in this table are deleted at some point, otherwise memory use will be unlimited.  The supervisor program has logic in the user interface that deletes rows that are a day old after enough event reports have been received to trigger  truncation of the displayed event report history.  There is also a Conversation item that is automatically loaded if the interface is named gemhost, and which causes periodic trimming of this table and the ei_event_log table.   For your own interfaces, you may want to delete rows in this table just after using them, or perhaps setup a Conversation item similar to the gemhost example but with a shorter time period.

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 gem2/lib/dataset_xfer.tcl and gem2/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.
traceLogMaxWidth		int	When file logging of trace data is enabled, this value sets the approximate maximum number of characters allowed per line of text in the log files.  Lines that are longer are trimmed to the maximum and a short explanation is appended.  The value is used to reduce the size of log files when large messages are routinely used.  The value of 0 can be set to specify no trimming.  Otherwise, a value of 1000 or greater may be set.
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 COM_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.

There is a requirement for stable operation that data rows in this table are deleted at some point, otherwise memory use will be unlimited.  The supervisor program has logic in the user interface that deletes rows that are a day old after enough event reports have been received to trigger  truncation of the displayed event report history.  There is also a Conversation item that is automatically loaded if the interface is named gemhost, and which causes periodic trimming of this table and the ei_alarm_log table.   For your own interfaces, you may want to delete rows in this table just after using them, or perhaps setup a Conversation item similar to the gemhost example but with a shorter time period.

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
datatype		varchar(2)	The TSN format type code that is used to transfer the process program data.

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 COM_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(60000)	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 COM_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(60000)	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.
port		varchar(200)	rs232 device name for serial connections or the [hostname:]port for terminal server or HSMS connections
auto_init		int	Used by the SECS server to indicate whether a host interface should automatically attempt a configurable initialization sequence when a transition from offline to online is observed.  See the description of the AUTO_VIRT_INIT event  with the ei_event table description above.
auto_start		int	If true, the interface is started when the supervisor application starts.
DEVID		int	The SECS-I Device ID of the equipment..
ALIDmap		varchar(2000)	not used - defined to manage sub-equipment
CEIDmap		varchar(2000)	not used - defined to manage sub-equipment
varIDmap		varchar(2000)	not used - defined to manage sub-equipment
varNamemap		varchar(2000)	not used - defined to manage sub-equipment
varNameunmap		varchar(2000)	not used - defined to manage sub-equipment
recipemap		varchar(2000)	not used - defined to manage sub-equipment
recipe_unmap		varchar(2000)	not used - defined to manage sub-equipment
hsms_passive		int	Set to 1 if the passive mode for HSMS communications should be used when initializing the hsms connection. Usually the equipment plays the passive role, and the host plays the active role. It can be useful to reverse the usual situation if the equipment is often offline, so the host does not waste time trying to connect. The default value is 0.
hsms_PROTOCOL		int	Set to 0 for non-HSMS connections, set to 1995 for standard HSMS, or to1993 for non-standard "1993 Draft" interfaces.
BAUD		int	For serial connections set to the desired baud rate.  The value 9600 is typical.
CEID_OFFLINE		varchar(32)	Used by the SECS Server to configure which event CEID means that the equipment is transitioning to an offline control state.
MULT		int	Set to 1 if the equipment can handle more than one reply at a time.
recipe_dir		varchar(200)	Used to configure the directory used for uploading process programs.
reports_clear		int	Used as a boolean whether to delete all existing event reports during initialization before defining new ones.  When this value is false, the report definition logic deletes reports one at a time as each new report is defined to make sure the report ID is not in use  The value can be set true to eliminate possible undesired event reports, or to have only a single deletion message sent when setting up new reports.
reports_enable		int	Used as a boolean property to insure that all equipment based events are enabled for reporting during initialization.  If the value is set false, only the events that are specifically configured with data reports or for being enabled are enabled.  However, if there are no event reports configured, then all equipment based event reports are enabled irrespective of this property setting.  So, the false value is not used for disabling event reports.
RTY		int	The SECS Server uses this field for the startup value of the SECS-I retry parameter.
SPOOL_INIT		varchar(8)	The SECS Server uses this field to hold the chosen value of PURGE, UNLOAD, or IGNORE specifying the use of S6F43 during initialization.
TRACE		int	Used as a bitfield to configure the desired diagnostic tracing for the connection at startup.
traceDir		varchar(200)	Used to configure the directory for logging of tracing.
traceLogMaxWidth		int	When file logging of trace data is enabled, this value sets the approximate maximum number of characters allowed per line of text in the log files.  Lines that are longer are trimmed to the maximum and a short explanation is appended.  The value is used to reduce the size of log files when large messages are routinely used.  The value of 0 can be set to specify no trimming.  Otherwise, a value of 1000 or greater may be set.
traceMax		int	Used to configure the maximum number of day files for the logging of tracing.
traceZipCmd		varchar(80)	Used to configure the compression command for logging day files.
T1		int	The SECS Server uses this field for the desired startup value of the corresponding timeout interval.
T2		int	The SECS Server uses this field for the desired startup value of the corresponding timeout interval.
T3		int	The SECS Server uses this field for the desired startup value of the corresponding timeout interval.
T4		int	The SECS Server uses this field for the desired startup value of the corresponding timeout interval.
T5		int	The SECS Server uses this field for the desired startup value of the corresponding timeout interval.
T6		int	The SECS Server uses this field for the desired startup value of the corresponding timeout interval.
T7		int	The SECS Server uses this field for the desired startup value of the corresponding timeout interval.
T8		int	The SECS Server uses this field for the desired startup value of the corresponding timeout interval.
tDATAID		varchar(6)	The SECS Server uses this field for the corresponding SECS TSN type code.
tDATALENGTH		varchar(6)	The SECS Server uses this field for the corresponding SECS TSN type code.
tLENGTH		varchar(6)	The SECS Server uses this field for the corresponding SECS TSN type code.
tPPID		varchar(6)	The SECS Server uses this field for the corresponding SECS TSN type code.
tREPGSZ		varchar(6)	The SECS Server uses this field for the corresponding SECS TSN type code.
tRPTID		varchar(6)	The SECS Server uses this field for the corresponding SECS TSN type code.
tTOPSMP		varchar(6)	The SECS Server uses this field for the corresponding SECS TSN type code.
tTRID		varchar(6)	The SECS Server uses this field for the corresponding SECS TSN type code.
use_s1f3		int	Set to 1 if the initialization logic should use S1F3 to query current Status Variable values. After initialization, subsequent value changes are ordinarily known to the host by being received in event reports. The default value is 1.
use_s1f11		int	Set to 1 if the initialization logic should use S1F11 to determine the Status Variables that are used by the equipment. The default value is 1. Since the set of variables does not ordinarily change, and can be loaded from saved table images, the initialization query can be disabled if it is timeconsuming.
use_s1f13		int	Set to 1 if the initialization logic should use S1F13 to initiate communications. The default value is 1, and is almost always appropriate since the logic will use S1F1 if S1F13 is rejected. However, there is some defective equipment in use that gets confused if it receives S1F13.
use_s1f17		int	Set to 1 if the initialization logic should use S1F17 to request that the equipment transition to an Online control state.
use_s2f13		int	Set to 1 if the initialization logic should use S2F13 to query equipment configuration variable values during initialization. The default value is 1.
use_s2f29		int	Set to 1 if the initialization logic should use S2F29 to determine the equipment configuration variables that are used by the equipment. The default value is 1. Since the set of parameters does not ordinarily change, and can be loaded from saved table images, the initialization query can be disabled if it is timeconsuming.
use_s2f31		int	Set to 1 if the initialization logic should attempt to synchronize the equipment's clock to the host's value using S2F31.
use_s5f5		int	Set to 1 if the initialization logic should use S5F5 to determine the alarm types. The default value is 1. This query is not used during every initialization. It is only used if the logic sees an enabled alarm type that it does not already know about.
use_s5f7		int	Set to 1 if the initialization logic should use S5F7 to query which alarm types are enabled for reporting. The default value is 1.
use_s13		int	Set to 1 if the use of Stream 13 large process program transfers should be enabled.  In addition to the Stream 13 messages, this property also enables or disables using S7F27, S7F29, S7F37, S7F38, S7F41, and S7F42 which are used with Stream 13 for transferring large unformatted, process programs.  The default value is true which causes an S13F9 reset message to be sent during initialization.  Stream 13 message types are preferred for transferring large data sets because the data is split into multiple smaller messages which require less memory use.
post_startup_code		varchar(2000)	Tcl code which is evaluated by the supervisor application just after starting an interface.  You can set timeout parameters, etc.  For example "set gemhost(T3) 80000".
comm_enabled		int	not used - could be used to configure startup of an equipment role interface
controlIntentOnline		int	not used - could be used to configure startup of an equipment role interface
controlModeRemote		int	not used - could be used to configure startup of an equipment role interface
controlStateStartup		int	not used - could be used to configure startup of an equipment role interface

The records in this table are used to manage time based Trace Data Collection. The implementation logic is in file .../gem2/trace.tcl. A row is inserted in the table at the time trace data collection is initiated by the receiving of a S2F23 message from the host. When the last S6F1 Trace Data Report message is sent, the corresponding row is deleted.
 

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
trace_id	PCK	varchar(32)	The TSN type code and identifier assigned by the host in the S2F23 initialization message. The equipment software does not care what type code is used.
period_mecs		int	The sampling period in milliseconds. The default logic accepts a minimum period of 1000 milliseconds. The value is computed from the S2F23 DSPER data item.
sample_n		int	A count of the number of trace reports sent. The value is updated every sampling period.
sample_n_max		int	The total number of samples to be captured (TOTSMP).
report_ct		int	A count of the number of samples taken without a report being sent.
report_ct_max		int	The number of samples to be reported in each trace report, also known as the report group size (REPGSZ).
timer_handle		varchar(12)	The handle value returned by the Tcl after command which is used if the trace is cancelled.
SVIDs		varchar(1000)	A list of the Status Variable IDs (varID in table ei_variable) desired in the trace data report.
data		varchar(32000)	The TSN formatted list of Status Variable values which is appended to with every sampling, sent in the trace report message, and then reset for the next report. The Tcl SQL command only uses as much memory as is actually needed so the large varchar size is not an issue.

This table is created dynamically to manage Trace Reports if the Host Tcl procedure, ei_trace_setup, in file .../host/trace.tcl is used successfully. The rows are used to correlate the data received in S6F1 Trace Reports with the requested items.
 

Column Name	Key	Type	Description
spname	PCK	varchar(32)	The secsport or hsms connection name that a particular row is associated with.
trace_id	PCK	varchar(32)	An identifier such as "1" assigned by the host and passed in the S2F23 initialization message.
period_secs		float	The sample period in seconds for the trace data.
SVIDs		varchar(1000)	A list of the Status Variable IDs whose values are requested in the trace data reports

This table holds configuration and value information on data items that are used by the host driver software and on variables that are supported by the equipment.  For GEM compliant equipment, the driver can populate this table with all of the Status Variables and Equipment Configuration Variables by querying the equipment.  Unfortunately, there is no way to determine Data Value Variables, but fortunately their use is not as common in modern equipment.

Certain data items used by the host driver cannot be detected, and must be configured if the default values are not appropriate.  The following data items are used by the host software to configure TSN data item format codes in the value_TSN field for the SECS-II data items of the same name:  PPID, RPTID,  DATAID,  TRID, TOTSMP, REPGSZ , DATALENGTH, and LENGTH. The default value of PPID is A, and the rest of the items default to U4.

A variable named CEID_OFFLINE also exists in the Tcl host's records for the purpose of configuring which event report CEID means that the equipment is transitioning to an offline control state. If the varvalue field has the correct CEID value for the equipment, the logic is able to keep the host's knowledge of the control state accurate.  Similarly the variables named CEID_LOCAL_CONTROL and CEID_REMOTE_CONTROL are defined to configure which event report CEID values imply transitions to online LOCAL or REMOTE control.  The host user interface has a dialog to discover and configure the control state events.  If you edit the table rows yourself, you may need to stop and re-start the interface to have your revised values put to use.

Using VFEI messages and commands is no longer the default behavior of the host applications.  This table is not created and not used unless your application is explicitly configured to use VFEI.

When using VFEI, VFEI output messages that are not command replies such as ALARM_REPORT's or EVENT_REPORT's are inserted into this table.  If the GEM-EI software is made part of a DMH message group, the output message record is deleted after the message is successfully transferred to the VFEI_OUTPUT_MAILBOX as configured in the ei_variable table.  If the message system is disconnected, the output messages will continue to be inserted into this table.  If the message system is reconnected, having the driver perform a VFEI initialization will transfer the queued output messages to the VFEI_OUTPUT_MAILBOX and restore the usual forward and delete behavior.
 

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 output message formatted as YYYYMMDDHHMMSScc.  This value may be used to correlate the record with the event_log or alarm_log record that was its precursor.
vfei_msg		varchar(20000)	A VFEI 2.2 formatted text message representing the asynchronous EVENT_REPORT or ALARM_REPORT (see SEMATECH 95113016A-TR)

Document Version

This document describes the configurable GEM Equipment Interface Applications provided by Hume Integration Software as part of its Datahub SDK.  The document is current for the Tcl 8.5/Tk 8.5 versions for UNIX and Windows NT.