The Hume Tcl/Tk SECS/GEM Applications


This document is best viewed from the Hume Datahub SDK documentation which provides a hyperlinked table of contents document in the frame immediately to the left of a larger frame where this document is displayed.


(C) Copyright 2013, Hume Integration Software, All Rights Reserved
This document may not be reproduced or redistributed without prior written permission of Hume Integration Software.  Licensed users of HIS provided software have permission to reproduce or electronically distribute this document to support their usage of the HIS software.

Introduction

This document describes the configurable Tcl/Tk SECS/GEM Equipment Interface Applications provided by Hume Integration as part of its Datahub SDK product.  "GEM" refers to Generic Equipment Model, a standard model for the communication interface to Semiconductor and Electronics manufacturing equipment.  GEM describes usage of a subset of the SECS-II protocol - the Semiconductor Equipment Communication Standard that deals with message content.  Applications for both the host and equipment roles of SECS are provided.  Tcl/Tk is a delightfully productive high-level language environment that is available for many platforms including Windows, Linux, Solaris, and HP-UX.  The SECS/GEM applications described here underwent a major redesign of the User Interfaces and features in August 2008.  The first versions of the  SECS/GEM applications were released in 1997.

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:

The Host GEM-EI software is easily integrated into a factory system using the DMH message system.  This enables the Host GEM-EI software to communicate equipment events to higher level software, to receive equipment control commands, or to respond to remote inspection using the inspect tool.  When the Host software is started as a member of a DMH message group,  the following mailboxes are used where name represents the name given to the particular equipment interface.
The Host software can be tied into other factory systems using any of the facilities provided with Tcl, or available from third parties.  Hume Integration also provides libraries to use the DMH message system from non-Tcl programming environments such as .NET, POSIX C/C++, Visual Basic, Visual C++, or Java.

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:


Installation

 The GEM-EI application files are usually installed using the SETUP program that comes with the Datahub SDK.  The SETUP program unpacks the gem2.zip archive into a set of directories underneath /usr/local/gem2 if your chosen installation path is /usr/local.  On Windows NT, program items are created to invoke the GEM Equipment Simulator,  and the Host Supervisor from the Start Menu.  The directories do not need to be located in the same installation directory as the DMH package.  You may choose to manually unzip the gem2.zip archive in a directory of your own choice.   Here are the directories that are created, and their contents:
 
 
Directory Description
.../gem2/host This directory contains Tcl source code files to support the host role of SECS.

The host directory contains the supervisor application, which is used to configure and manage the startup of one or more equipment interfaces.  The supervisor application has the ability to copy interface configurations.  This makes it simple to integrate multiple instances of similar equipment. 

The directory also contains the gemhost  application which by default will use the HSMS protocol and connect to the gemsim application running on the same computer.  You can use command line arguments to have the gemhost connect to different equipment, but the supervisor application is more easily configured.   The gemsystem command is an example of starting the gemhost application as a client of a DMH message group server. 
.../gem2/equip This directory contains Tcl source code files to support the equipment role of SECS.

The equip directory contains the gemsim GEM compliant equipment simulator.  This application is used as a suitable target for the supervisor application for demonstration, learning, testing, and development.  The application is also designed to be used as a starting point for an equipment manufacturer.  The gemsim application by default offers an HSMS connection on port 5555, with device ID 0.  By providing command line arguments, or configuring startup options, other connection types are possible.
.../gem2/lib This directory contains Tcl files that are shared between both the host and equipment applications. 
.../gem2/client In this directory you will find the ei_client application.  This application uses the DMH message system to communicate with equipment drivers that are running in background, or running on remote computers.  The target application must be listening for Tcl commands in a DMH mailbox.  The ei_client application is able to create local trace windows for secsport, hsms, or comm equipment interfaces.  Also, the utility can launch the inspect or hubclient programs attached to the same target application.  In combination, these utilities let you debug and control your equipment interfaces from any seat on your local area network!
.../gem2/custom This directory is a place for you to develop and deploy your own equipment interfaces or custom versions of the provided application code.  The Conversations feature is able to save and automatically load custom SECS conversation data from this directory.

The custom directory is added to the auto_path variable of the supervisor application Tcl interpreter before the directories that contain the HIS distributed files.  If you create custom procedures in this directory, they will be found and used instead of the HIS distributed procedures of the same name. 

If you are getting started with the supervisor application, and are creating a small number of equipment interfaces, this directory will be adequate to hold your custom software.  If you are deploying many equipment interfaces, you will probably wish to create multiple directories similar to this one.  You may wish to create your own directories for specific types of equipment interfaces.  You can put your shared procedures in this directory, and put your equipment specific code in a separate directory that you create for each kind of equipment.  You either need to keep the equipment specific code in separate directories, or give the equipment specific code unique procedure names.  Look at the ../host/gemhost script for an example startup script that sets up the auto_path.  You will want to use the auto_path variable to control which directories the Tcl interpreter uses to find procedures. 

If you will be using the custom directory to develop new interfaces, you need to make sure that the security permissions allow you and your co-developers to create and modify new files in this directory. 

.../gem2/server
This directory has files such as SecsServer.tcl which are used to run a Tcl/Tk process as a SECS server and interface to it using the DMH message system.  The files and this directory are used by the Hume Java, .NET, and other platform host and equipment SECS libraries.
.../gem2/CVS, .../gem2/*/CVS HIS uses the freely available cvs version management system to track changes.  The CVS subdirectories are created by this tool to hold version information about the files.
.../gem2/tests This directory is used for HIS or customer developed regression tests.  The core Tcl/Tk distributions come with regression tests to verify proper operation of the Tcl/Tk features.  This directory contains the files needed to run similar regression tests on the GEM application software. 

The SEMI Standards

The Semiconductor Equipment and Materials International  organization (SEMI) has developed the following standards for equipment communication upon which this software is based. The SEMI standards are available through http://www.semi.org.  The E5 standard is the most important one - it describes the use of SECS messages.  The GEM model is described in E30.  The lower level protocols are described in E4 (SECS-I) and E37.1 (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

Here is a mix of facts and advice to help get you started with SECS equipment.  This is no substitute for reading the standards.

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

For demonstration and learning, you can immediately begin running the supervisor and gemsim applications as an example host interface and equipment, respectively.  The information in this section will coach you on starting the applications, on using them, and on understanding them.  Also, you can successfully use the supervisor application to communicate with your own equipment.  You can use the graphical user interface to specify the set of variables in dynamic event reports, to manage the reporting of alarms, to upload and download recipes, as well as other functions such as querying and setting variable data.  The supervisor application can start multiple equipment interfaces using custom connection specifications.  If the supervisor is started without any connections defined, it creates a connection definition with the name gemhost which is configured for connecting to the gemsim running on the same computer.

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 Gemsim Startup

In the factory, the equipment is usually powered up and running, and available for SECS interface connections.  We will parallel the factory equipment by starting the gemsim equipment simulator first.   On Windows NT, the usual SETUP installation results in a program item named "Gem Equipment" which you can activate to start the gemsim application.  On UNIX systems, you need to navigate to the /usr/local/gem2/equip directory.  With X-Windows running, you should invoke "gemsim &" to run the gemsim application as a background process that is not attached to your console window.  The default startup of gemsim creates the equipment as an HSMS server ("a passive listener") on port 5555. 

The gemsim application recognizes certain command line arguments to configure its startup,  but the easiest way to change the startup is to run the program and press the Edit Startup... button on the User Interface window.  This brings up the Startup Configuration dialog.  The settings you save are used the next time the gemsim application is started.  End the program and restart it to make your new settings immediately effective.

Optionally, you may specify information on the command line to tell the gemsim application to use a serial communication port, or to offer a TCP/IP server connection that uses SECS-I.  The latter possibility may seem non-standard, but in fact it simulates the common situation of connecting SECS-I equipment to a terminal server, and then connecting directly to the terminal server using TCP/IP.  The direct use of TCP/IP terminal servers is a standard feature of the secsport command, and it is widely used by HIS Fab customers.  The gemsim application will execute command line arguments as Tcl statements.  Also, if the global variable PORT specifies a different connection, the gemsim application will use it instead of its default HSMS port.  Putting these facts together, an example command line such as:
$ gemsim "set PORT /dev/tty01" &

or

c:\usr\local\gem2\equip> gemsim "set PORT COM1"
will start the gemsim application connected to the system /dev/tty01 or COM1 serial port.  

The Gemsim User Interface

With the gemsim application started, you will see three windows; the GEM Equipment User Interface, the gemsim Trace window, and the gemsim Data Tables window.  The last window is probably iconified.  Here is a brief overview of the menues and features of these windows.
 
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.
The Parameters notebook panel shows the names and values of the Equipment Configuration Variables (ECV) in use.  These are settable parameters.   There is a button provided to Edit the value of a selected parameter.  There is also a button provided to set all of the parameters to their default values.

The Variables notebook panel displays the Status Value and Data Value variables in use.  The button labeled Value... is used to display the current value of a selected variable.

The Conversations notebook panel lets you create and configure sending messages, or receiving messages.  A Conversation sending item can involve sending static or computed SECS message data,  asking for a reply, managing the reply or failure with custom code, and then possibly continuing with  a Conversation sending item after a configurable delay.  A Conversation receiving item can involve executing custom code in response to a received SECS message, sending a reply. and possible continuation with a Conversation sending item after a configurable delay.  The Conversation feature is unique to the Tcl/Tk versions of the Hume SECS/GEM software products.  It is ideal for creating complex testing and characterization scenarios, or for the rapid deployment of SECS conversation logic.  Files of conversation item definitions can be saved and loaded dynamically.

The Status Information panel provides a scrolling list of status information such as changes to the communication and control states.  The Clear button deletes the existing data.  The Add to SECS Trace checkbox lets you have the displayed Status Information copied to the SECS conversation tracing so you can save it in context to daily logging files or to interactively initiated Save files.  On the right side of this panel there are buttons to bring up other application windows.  The button labeled SECS Trace raises or creates the SECS Trace Window.  The button labelled Tcl console brings up a Tcl console for interactive command line use.  The button labeled Hub Tables raises the Data Tables window.  
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

Most of the communication and control state logic is in the file .../gem2/equip/equip.tcl.  You will see logic in this file that uses the secsport or hsms whenmsg or whenever commands dynamically to setup or change the handling of received messages.  The .../gem2/equip/eq_ui.tcl file contains the code that creates the "GEM Equipment User Interface" window, and supports its actions.  After you get the host side started (directions below) you can use the Trace window to see what SECS messages and data are being communicated.  The inspect application is probably the most convenient way to view the data items in the gemsim application while it runs.  You can inspect the global array gemsim to get an inside look at the status of the communication connection.  The Data Table window lets you look at the table data used to manage alarms, reports,  events, and variables.  The table schema used by the gemsim and host applications is explained in detail towards the end of this document.

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. 

To create your own variable definitions, take a look at the eq_var_init procedure in file eq_variables.tcl and use it as a model.  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 Host Supervisor Startup

In the above section we discussed starting the gemsim application.  When the supervisor application starts, you see two windows one titled "Host Supervisor" and the other "Host Tables".   The Host Supervisor window displays a list of the defined SECS interface definitions and has button actions to act upon the items in the list.  If no interface definitions have been saved, a default interface definition is created with the name of gemhost and with the connection properties matched to the gemsim startup defaults.  Use the supervisor Start button to startup the gemhost interface.  If the communication parameters with the gemsim are properly matched, you will see a lot of activity in the Trace windows of both applications within a few seconds. 

If you are running the simulator or other equipment on a different computer, use the supervisor Edit... button to change the  Host or IP Address from the default before pressing Start.  You may need to change the TCP/IP port to match your equipment also.   Press Ok to save your startup configuration changes, and then press Start.  

The Host User Interface

When the gemhost SECS interface connection is started by the supervisor, two new windows are created.  The window titles are Host SECS User  Interface - "gemhost", and gemhost Trace.  These windows are similar to the windows that the gemsim application creates.
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 Parameters tabbed notebook panel displays the ECV's supported by the equipment.  Use the Refresh button to query the current values.  Use the Edit button to edit and send a revised parameter value to the equipment.

The Variables tabbed notebook panel displays the Status Variables supported by the equipment.  Use the Query button to request the current value of a selected variable.  Use the Refresh button to request the current values of all of the variables.  Use the button labeled Hub Variable Table to display the rows of the ei_variable table that are keyed for this particular SECS interface. 

The PP Transfer panel displays the process programs at the equipment, and process programs that have been uploaded.  Use the Refresh button to obtain a current list of process programs from the equipment.  The Upload button requests a Stream 7 transfer of the selected process program from the equipment to the host.  The Large Request button is similar except that it used Stream 13 messages which are designed for large file transfers and are less commonly supported.  Be careful when using the Delete button - it asks the equipment to delete the selected process program.  On the right side of the panel you see sizes and modification times of the process programs that you have uploaded.  Use the Download button to initiate a Stream 7 transfer of the process program from your uploaded file to the equipment.  Use the Large Send button to perform the same transfer using Stream 13 messages.  You can transfer a large file, for example 3 megabytes using Stream 7 messages, but it causes a large amount of memory to be allocated to your program.   The Delete button on the right side of this panel deletes the selected uploaded program.

The Processing panel displays the same list of equipment resident process programs as the PP Transfer panel.  If the Refresh button is used on either panel, both of the lists are refreshed.   The row of buttons labeled Select, Start, Pause, Resume, Stop, and Abort invoke Conversation send items of the name RCMD_XXXX where Xxxx is the button label.   For example, the Start button corresponds to the Conversation send item RCMD_START. 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.   You can configure the corresponding Conversation send items to send the specific Remote Command message types that your equipment supports.  You can also selectively disable particular Conversation send items.  A Conversation send item is able to chain the successful send-and-reply of a message to another send item.  Therefore you are able to configure conversation sequences consisting of sending more than one message.  For example, you can chain the successful sending of a process program selection message to a start command message.  

The Processing panel displays the current Process State, and the current PPExecName (Process Program Name or "recipe").  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.   As new values are received from event reports, the displayed values update.   You can tailor the display of these items for your equipment 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 SEMATECH standard virtual names PROCESS_STATE and PP_EXEC_NAME.
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 Spooling tabbed notebook panel is used to configure which message stream types are to be saved in a queue when the host is down.  There are also button actions to Purge or Unload the spool.  The GEM standard specifications for spooling are poorly designed and have caused far more problems than they solve.  We suggest you do not use spooling, or you limit spooling to only Stream 5 - Alarms, and Stream 6 - Data Collection.  
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 Conversations notebook panel lets you create and configure sending messages, or receiving messages.  A Conversation sending item can involve sending static or computed SECS message data,  asking for a reply, managing the reply or failure with custom code, and then possibly continuing with  a Conversation sending item after a configurable delay.  A Conversation receiving item can involve executing custom code in response to a received SECS message, sending a reply. and possible continuation with a Conversation sending item after a configurable delay.  

You should explore the Conversation feature and visit each Help button on the Edit dialogs separately - they convey different messages depending on the context.  With the use of the break statement, a sending item does not need to actually send a SECS message.  Thus, you can use the continue after delay feature to periodically execute custom code.  We demonstrate this with a periodic item to manage the size of the log tables.   There are also button actions to let you interactively Validate your SECS message expressions or to Send them from the edit dialog.   The Send button saves the edited conversation item and then executes it, without dismissing the edit dialog.  You can interactively revise and test your item repeatedly before dismissing the dialog. 

We have also created a means to simplify expressing SECS messages using Tcl Secs Notation (TSN) for Conversation items.  Commands with the same uppercase names as the TSN data types such as L, A, B, TF, I2, F4, and U4 have been created that format their arguments as TSN message elements.  You can use these abbreviated commands to simplify your message data expressions since they will build proper TSN list values for you and they accommodate more variation in your data arguments than using TSN directly.  For example [A hello world] represents an ASCII item that is equivalent to [list A {hello world}].  A more complex example,  [L [A PP-SELECT] [L [L [A PPExecName] [A my PP name]]]] is the message data for a S2F41 remote command that selects process program "my PP name".

You may use $sp to refer to the SECS connection in your conversation item expressions, for example [set ${sp}(lastrmsg)] is the last message received. The example [B [$sp lastheader]] specifies the header of the last received message as a binary vector.  Notice that using the B command is simpler than specifying [concat B [$sp lastheader]].

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.  Conversation items that are saved in the application working directory or the custom directory with the filename auto_xxxx.cvt where xxxx is the name of the SECS connection are loaded automatically at startup.  If a file of conversation items is not found for the specific named interface, and the user interface is being displayed, then the logic attempts to load the file auto_host.cvt for host interfaces or auto_equip.cvt for equipment interfaces.   The logic for loading generic host or equipment conversation items also attempts to use the gem2/host and gem2/equip directories after checking the working directory and the ../custom directory.  For the default situation of a host interface startup, the Hume provided file gem2/host/auto_host.cvt is loaded.  For the default startup of the equipment simulator gemsim, the Hume provided file gem2/custom/auto_gemsim.cvt is found and loaded.
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

If you specify a DMH message group name on the command line by assigning it to the global variable MB_GROUP, the supervisor will connect to the message system as a client during the startup of a SECS interface.  When the software is used with the message system, you can use the inspect application to debug it from any seat on your network.  Also, other software in your factory system can send command messages to the equipment interface, or receive alarm and event reports from the equipment interface.  In general, you want to start the message group server first, before starting processes that will connect to it.  For example, to start a message server with the group name "gem" and to connect to it:
$  dmh85_server gem &
$  supervisor "set MB_GROUP gem" &
In general, you do not need to have an external DMH server process.  The same Tcl/Tk process that executes the SECS logic for one or more interfaces, either host or equipment or both, can also serve as a DMH server, and have multiple attached DMH clients.

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 &
Next, the supervisor application will open the mailbox gemhost_RPC to process received commands as Tcl statements.  This mailbox lets you use inspect for remote debugging, as in:
$ inspect gemhost_RPC@gem &
The _RPC mailbox also makes it possible for an external process to control the GEM host process using DMH messages that are Tcl commands.  Since DMH client software is available for many programming environments, this is a common scenario for the customer who is integrating with external applications.  The GEM host logic uses the mbx_RPC command to send reply messages that contain the return code and result of executing the received Tcl code messages.  There is also a Tcl procedure, secs_dmh_reply, that can be called to send a SECS primary message, and have the SECS reply forwarded as the DMH reply message.  You may review the logic and details of the secs_dmh_reply procedure by examing its source code in the gem2/lib directory.  This procedure and the DMH integration techniques are also useable for the Hume provided GEM Equipment software.

The Java and .NET SECS/GEM applications do not directly use the Tcl/Tk supervisor program.  They start a Tcl/Tk process running as a background demon using the SecsServer.tcl script in the gem2/server directory.  These other applications are a different example of integrating the Tcl/Tk SECS software capabilities with an external process using the DMH message system.
 

Understanding the Supervisor Application

The supervisor script sets up the auto_path variable to find Tcl procedures and then executes the procedure ei_supervisor found in file supervisor.tcl.   The communication and control state logic is mostly in host.tcl.  The logic for the Host Equipment UI is in host_ui.tcl.  There is another application script, gemhost, which starts only a single host interface named gemhost.  You may find this script to be a more useful example than the supervisor for deploying a single custom interface.

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

When the supervisor application is started in foreground, the window entitled Host Supervisor is created.   The main portion of the window shows a list of equipment interfaces.  For each interface, the associated network connection or serial device is shown, and the status information indicates whether the interface is running.  There are three rows of action buttons.

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

 In the description of the supervisor application, we described how to customize the connection startup and how to create and save event report configurations and similar uses of the UI.  In some of the detailed descriptions, and in the description of the ei_variable table, we indicated data parameters that you can update for your particular equipment.  In this section we go deeper - we will consider how to create and start multiple equipment connections, and how to customize the Tcl logic to work around non-standard equipment or special requirements. 

The supervisor application provides you with a convenient way to start interfaces of your own name, and run them all from the same directory.  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 - 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 integrate your custom code for event reports by opening a subscription to the ei_event_log table.  The host UI does this to capture event reports for the display.   The UI subscription is more complex than is typically needed by an integrator since it is designed to work for multiple interfaces without any explicit coding of interface or window names.  Similarly, you can respond to alarm reports by opening a subscription to the ei_alarm_log table.

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

The following database tables are used by the GEM-EI application.  As of August 2008, the schema was modified so that the tables which are used by both host and equipment logic are created with all of the fields used for either the host or equipment roles of SECS.   This permits the same application process to run multiple host or equipment interfaces.  The schema also has additional fields defined for the management of sub-equipment, although these fields are not used by any current Hume product.  In the past we have demonstrated the feasibilty of an application functioning as the host to multiple sub-equipments and providing a unified equipment connection to a factory host. 

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

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.


ei_alarm    Alarm Configuration and Status Data

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.



ei_alarm_log    Alarm Instance Data (Host Only)

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.

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.

 
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(120) The alarm description provided by the equipment with the report, or the text from the ei_alarm record.


ei_dataset_xfer    Data Set Transfer Data

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. 



ei_equipment    Equipment Startup Data (Equipment Only)

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.



ei_event   Event Configuration Data

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.
The GEM equipment software uses this table to manage the configuration and reporting of data collection events. The developer of equipment software creates a new type of event by adding a record to this table. Per GEM, the CEIDs should be unsigned 4 byte integers (ID_TSN='U4'). It is suggested to use values from 5000-9999 but the requirement is to not conflict with the CEID's that are associated with the setting and clearing of alarms. At startup, the event definitions are usually loaded from the a file of SQL statements. At runtime, an event is reported by calling the Tcl procedure eq_gem_event with the connection name and the CEID as arguments.  It is also possible to use eq_gem_event and report events by name, and this is the approach of the built-in logic which allows for customizing the CEID values without changing the source code.   The Hume provided software takes care of creating and sending the event reports that have been configured by the host. See file gem2/equip/eq_events.tcl.

Column Name Key Type Description
spname PCK varchar(32) The secsport or hsms connection name that a particular row is associated with.
eventname PCK varchar(32) Equipment usage only.  A revision to the toolset in January 2007 added this column to provide a means of identifying events independent of the CEID value.  This change allows customization of the CEID values used by the interface.without changes to the source code. 
CEID (*) varchar(32) The identifier for the event. For equipment events the CEID is defined by the equipment, and almost always integers are used.  Events that are created in the driver software can be given more descriptive identifiers such as COM_ENABLE.   The host software uses this column as part of the primary composite key for the table but the equipment does not.  When a merged schema is created for both equipment and host use, this column can be declared part of the primary composite key instead of the eventname column, and the equipment logic will continue to operate properly.
VFEIname   varchar(32) Host usage only.  A virtual name for the event which is used for VFEI event report and event setup messages.  When an event record is inserted, the VFEIname defaults to the CEID.  The integrator can update the record and provide a more descriptive name.
host_managed   int Host usage only.  If true, the reporting of this event is enabled or disabled during the initialization sequence.
host_wants_enabled   int Host usage only.  This field indicates whether the reporting of this event should be enabled or disabled if the host_managed value is true.
event_class   varchar(10) Host usage only.  The class that the event belongs to.  Events that are reported by the equipment are given the event_class EQ. Events that are created by the GEM-EI and could be used without VFEI are given the class, SECS_DRVR.  Events that are created and used by the VFEI level software are given the class, VFEI_DRVR.
ID_TSN   varchar(4) This is the TSN data type code for the CEID value.  It is not necessarily the same for all of the events of a particular spname.
is_reported   int This field is set to reflect whether the equipment event is actually enabled for reporting.  For events that are created in the Host logic, using the ei_driver_event procedure, this field determines whether the event is actually reported to higher level software by being inserted into the ei_event_log table.
description   varchar(120) If the integrator supplies a description for the event, it is seen when creating event reports using the configuration user interface.  There is no GEM or SECS mechanism for the host to determine event descriptions.
eqname
 
varchar(32)
not used - defined to manage sub-equipment
eqCEID
 
varchar(32)
not used - defined to manage sub-equipment


ei_event_dvvals    Event and DVVAL Variable Associations (Equipment Only)

This table is used by the built-in equipment logic to compute the S1F24 reply message that describes event types and their associated DVVAL variables.  The S1F23, S1F24 message types are newly proposed additions to the standards as of October 2011.

The data in this table may describe events that are not implemented by the equipment.  This is not seen by the host and causes no harm.  There is no need for the application to remove data from this table.  Instead, the application controls the content of the S1F24 reply message by limiting the rows in the ei_event table to only implemented events, and by using the eq_event_dvvals procedure defined in equip/eq_events.tcl to add records to this table for the event types and DVVAL variables that are added by the application.

The equipment logic implements the idea of macros which are symbols that imply the association of sets of variables.  For example, the macro name *carrier can be defined to specify the DVVAL variables that are associated with E87 Carrier objects.  Then the event types that are used for Carrier state transitions include the *carrier macro in their varnames value as a shorthand way of including all of the carrier related DVVALS.
 
Column Name Key Type Description
spname PCK varchar(32) The secsport or hsms connection name that a particular row is associated with.
eventname
PCK varchar(32) The eventname  value of an event type as listed in the ei_event table or a macro name that defines a set of variables which are associated with multiple events.  

A macro name starts with an asterisk.  The macro name * is used to specify the variables such as EventName that are associated with every event.  The macro name * is handled exceptionally and does not need to be included in the varnames value. The macro name *alarm is used to specify the variables such as AlarmID, AlarmCode and AlarmText that are associated with every alarm event type.

There is no need to include events that are for the setting or clearing of an alarm - these event types are known from the ei_alarm table.  However, it is possible to include alarm related events for the purpose of specifying associated DVVAL variables that are in addition to those specified using the *alarm macro.
varnames   varchar(60000) A list of DVVAL variable names or macro names that are associated with an event.  If the eventname is a macro name then the varnames value can only contain variable names.   Associated variables can only be Data Value Variables (varclass DVVAL) or an error occurs when the S1F24 reply is computed.


ei_event_log    Event Report Instance Data (Host Only)

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.

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.
 
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.


ei_event_report    In-use Event Report Associations

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.



ei_event_report_cfg     Configured Event Report Associations (Host Only)

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. 


ei_ppid    Uploaded Process Program Descriptions (Host Only)

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.


ei_report    In-use Report Definitions

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.



ei_report_cfg     Configured Report Definitions (Host Only)

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.



ei_spool_data     Messages Spooled for Host Retrieval (Equipment Only)

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.



ei_startup    Configuration of Equipment Interface Startups (Host Only)

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



ei_trace_active     Active Trace Data Collection (Equipment Only)

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.



ei_trace_setup    Trace Data Collection Configuration (Host Only)

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



ei_variable    Data Item Configuration and Status

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.


Column Name Key Type Description
spname PCK varchar(32) The secsport or hsms connection name that a particular row is associated with.
varID   varchar(32) An identifier for the data item.  The SVID, ECID, or DVNAME for Status Variables, Equipment Configuration Variables, or Data Value Variables.
ID_TSN   varchar(8) The TSN format type code for the varID as used by the equipment. 
varname   varchar(256) A name for the data  item.  The SVNAME, ECNAME, or DVNAME for Status Variables, Equipment Configuration Variables, or Data Value Variables.
VFEIname   varchar(256) A virtual name for the variable.
description   varchar(200) Usage notes and/or a description of the data item.
varclass   varchar(10) The class of the data item. 
SV = Status Variable.  These are variables maintained by the equipment whose values can be queried by the host. 
ECV = Equipment Configuration Variable.  These are parameters maintained by the equipment whose values can be set by the host.   You may hear the misnomer "Equipment Constant Variable" used for these parameters.
PPV = The Hume equipment applications use the varclass value PPV to specify the subset of ECV items whose value affects processing.  PPV is an acronym for Process Parameter Variable.  The equipment logic prevents the host from changing PPV values when the control state is in LOCAL mode.
DVVAL = Data Value Variable.  These are variables maintained by the equipment whose values may be reported in certain fixed format event reports. 
SECS_DRVR = SECS Driver Variables.  These are variables or parameters that are created and maintained by the host interface driver software. 
VFEI_DRVR = VFEI Driver Variables.  These are variables or parameters that are created and maintained by the VFEI host interface driver software.  They are similar to the SECS_DRVR items, except they are only used if you are using VFEI.. 
VFEI_MCMD=VFEI Machine Commands.  The VFEIname field is used to specify the CMD_TYPE of a machine command (MACH_CMD) supported by the driver.  The driver developer usually sets the varname and varID to the same value and supplies a description for the upper level software.  The varID field can be set to some other value if needed in order to create a unique row entry.
value_TSN   varchar(8) The TSN format type code for the variable value used by equipment.  A VFEI_DRVR value can be VFEI_NTV which indicates that the varvalue is one or more name/type=value items.
varmethod   varchar(2000) Tcl code to compute the current value of the data item.  If blank or equal to "return $varvalue" the value in the varvalue field is used.
varvalue   varchar(60000) The latest value of the variable, possibly updated from receiving a SECS message such as an event report, or a status query reply. The host has logic to save and use status variable values that are actually larger than the varvalue fieldsize; in this situation, a varmethod entry is created to access the value from the global $spname array.
host_setval   varchar(200) The desired value of an ECV variable. 
host_managed   int If true, the ECV value is set to the host_setval value during initialization.
t_latest   varchar(16) The YYYYMMDDhhmmsscc timestamp when varvalue was last updated.
units   varchar(10) The default of an empty string means a pure number without units.  Reference E5-9.
ECMIN   varchar(32) The minimum value of an Equipment Configuration Variable.
ECMAX   varchar(32) The maximum value of an Equipment Configuration Variable.
ECDEF   varchar(32) The default value of an Equipment Configuration Variable.
eqname
 
varchar(32)
not used - defined to manage sub-equipment
eqvarID
 
varchar(32)
not used - defined to manage sub-equipment


ei_vfei_output     VFEI Output Message Data (Host Only)

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

Date of last revision: $Date: 2022/11/30 20:53:02 $

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. 


Leave this document and go to the Tcl/Tk Resource Index