The GEM Equipment Interface Applications


Contents


(C)Copyright 2001, 2008 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 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.

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

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

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

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 software components 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 gem.zip archive into a set of directories underneath /usr/local/gem if your chosen installation path is /usr/local.  On Windows NT, program items are created to invoke the GEM Equipment Simulator,  the GEM Supervisor, and the GEM Host Interface 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 gem.zip archive in a directory of your own choice.   Here are the directories that are created, and their contents:
 
 
Directory Description
.../gem/host This directory contains the gemhost  application, and other files that support the host side of the SECS protocol.  The gemhost application can be started on the command line.  By default it 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.  You can also use the gemsystem command to start  the gemhost application as a client of a DMH message group server. 

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

.../gem/equip This directory contains the gemsim GEM compliant equipment simulator.  This application is used as a suitable target for the gemhost 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 will by default offer an HSMS connection on port 5555, with device ID 0.  By providing command line arguments, or configuring startup options, other connection types are possible.
.../gem/lib This directory contains Tcl files that are shared between both the host and equipment applications.  You may be interested in the secs_xact.tcl file that provides for synchronous style SECS transactions.
.../gem/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!
.../gem/custom This directory is a place for you to develop and deploy your own equipment interfaces or custom versions of the provided application code.  This directory is added to the auto_path variable of the gemhost or 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 GEM 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. 

.../gem/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.
.../gem/CVS, .../gem/*/CVS HIS uses the freely available cvs version management system to track changes to the GEM package files.  The CVS subdirectories are created by this tool to hold version information about the files.
.../gem/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 gemhost software by setting the array element DEVID.  You can set this on the command line, or in your custom version of the gemhost script as explained later.  Newer versions of the Hume GEM Host software have logic to automatically correct the DEVID value, if the equipment implements standard error messages.

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

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


Using the Gemhost and Gemsim Applications

For demonstration and learning, you can immediately begin running the gemhost 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 gemhost or supervisor application to communicate with your own equipment.  You can use the graphical user interface to specify the collection of data in event reports, to manage the reporting of alarms, to upload and download recipes, etc.  The example gemhost script starts a single equipment interface with the name "gemhost".  The supervisor application can start multiple equipment interfaces using custom connection specifications.  If you have more than one piece of equipment,  you should use the supervisor application to create the interfaces that you need.  You will want to give your interfaces names of your own choosing.  We will discuss customization at this level in the next section.

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

The Gemsim Command Line

In your factory, the equipment is usually powered up and running, and available for SECS interface connections.  We will parallel your 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/gem/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.  If you have not licensed the HSMS software features of the Hume products, you will need to 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 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" &
will start the gemsim application connected to the system /dev/tty01 serial port.  You probably do not want to mess around with serial ports and a crossover cable just to run the demo applications.  If you cannot use HSMS, start the application on Windows NT with:
C:\usr\local\gem\equip> gemsim "set PORT :5556,S"
or on UNIX with:
$  gemsim "set PORT :5556,S" &
With this command line, the gemsim application will offer a TCP/IP server connection on port 5556.  The secsport command documentation explains the possible types of connections that we are assigning to the global variable PORT. The gemsim script assumes that an HSMS connection is intended if a simple integer is used for the PORT value and it calls the hsms Tcl command during initialization. If the PORT value is not a simple integer, the secport command is called.

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

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

The Gemsim User Interface

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 each of which controls different aspects of the equipment.
 
The Communications panel gives you two push buttons to enable or disable communications.  The current communication state is shown.  Upon startup, before the host connects, the state will be "ENABLED {NOT COMMUNICATING}".  On this panel, there is a button labelled "Edit Startup...".  Use this button to bring up a configuration dialog that lets you set the desired connection, communication, and control properties for the next time the program is started.
 
The Control panel provides switches that conform to the GEM control model.  With GEM, the Communications state indicates the ability for the host and the equipment to communicate, but the Control state characterizes the equipment's responsibility to act upon the received messages.   The operator can choose for the Control state to be Off-line or On-line.  In the Off-line control state, the use of messaging for automation purposes is severely restricted.   If the operator choose to go online, the gemsim application will not respond to further presses of the On-line/Off-line radio buttons until the communication attempt to the host has succeeded or failed.  With HSMS, the button can seem stuck on Off-line because the communication attempt fails immediately if the host is not connected.  The local and remote pushbuttons affect the On-line control state.  With real equipment, the local and remote choices affect the degree to which the operator or the host interface is in charge of processing.
 
The Alarms panel provides buttons to Enable, Disable, Set, Clear, or Add alarms.  Alarms will be reported when they transition from Set to Clear, or from Clear to Set, if they are Enabled for reporting.  The panel shows which alarms have been defined, and what their current Enable/Disable and their current Set/Clear states are.
 
The Processing panel allows the operator to select a PPExecName (a Process Program Name or "recipe"), and then choose to Start running it.  While the process program is running, other buttons can be used to Pause, Stop, or Abort.  A Paused process run can be Resumed using another button.
 
The Terminal Services panel allows the equipment operator to send a message to the host, and to view and acknowledge a message that the host has sent the equipment.
 
The Spooling panel shows you the status of SECS message spooling.  The "Spooled Msg Types" indicates the SECS streams or streams and functions that have been configured to be spooled and corresponds to the status variable SpoolStreamFns.  The host configures this value using S2F43.  The operator can clear this value using the "Stop Spooling" button, or choose specific streams using the "Configure..." button.   The "In Spool" count corresponds to the status variable "SpoolCountActual" which is a measure of the number of messages currently spooled.  The "Max In Spool" count corresponds to the equipment parameter "SpoolMax" which is the limit on the number of messages that can be spooled.  The "Input Total" count corresponds to the status variable "SpoolCountTotal' which is the count of messages handled by the spooling logic since spooling last began.  If this value is bigger than "Max In Spool" it indicates that the spool was filled and data was lost.  The "Purge Spool" button empties the spool.
 
gemsim Trace window
This window is the usual trace window that can be displayed for any secsport or hsms communication connection.  The window is used to display the messages that the gemsim application sends and receives.  Also, trouble-shooting information such as displaying communication attempts and low level protocol state changes are available, if you check the corresponding item choices under the Tracing menu button.  The Send menu can also be handy - you can cause the binary echo message to be sent, or the S1F1 "Are you online?" query to be sent.  The items under the Object menu let you Reset the state of the connection.  The Reset action causes the interface to stop expecting any outstanding replies, and to discard any messages that have become queued for sending.  Also under the Object menu, the Show action will display the data items stored in the gemsim array.   Under the Replay menu there are actions to re-send or re-receive SECS messages. There is also the Window... action to bring up a separate Replay Window. The replay actions are extremely useful during development; you can update your Tcl logic on the fly, and artificially cause a previous message to be re-received or re-sent. The Replay window has actions to save and restore message conversations as well as re-send or re-receive selected displayed messages. Under the Window menu button, there are actions to save the current window data to a file, to append the current data to a file, to clear the current data from the window display, to dismiss the window, or to Exit the program.  If you dismiss the window and later want to recreate it, you need to have the gemsim Tcl interpreter execute the command "gemsim tracewin".  You can get a Tcl command prompt using the window described next, or by attaching to the gemsim interpreter using the inspect application.
 
gemsim Data Tables
The Data Table window is the same user interface obtained by running the Datahub application.  The gemsim application uses in-memory SQL tables to manage its data.  You can use this windowing interface to interactively examine or modify any of the table data.  Under the File menu button, select the Refresh action to see the list of tables that are currently in use, and the number of data rows in each table.  Also under the File button, there are actions that provide additional windows for the execution of SQL statements or Tcl commands.  Other menu items are available to execute files that contain Tcl statements or SQL statements, or to Exit the program.  The Table menu has action items to display the schema or data of the tables that are selected in the list on the Data Table window.

Understanding the Gemsim Application

Most of the communication and control state logic is in the file .../gem/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 .../gem/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.

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

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

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

The Gemhost Command Line

In the above section we discussed starting the gemsim application.  When the gemhost application starts, if the communication parameters are properly matched, you will see a lot of activity in the Trace windows of both applications within a minute or so.  If you are licensed to use HSMS software, you may start the gemhost application by activating the Windows program item, or executing gemhost on the command line from the /usr/local/gem/host directory.  By default, the gemhost will attempt a client HSMS connection on port 5555 of the computer on which it runs.  If you are not licensed for HSMS, start the gemhost application by indicating a SECS-I, TCP/IP client connection that matches the server connection you used above.  So for Windows, you enter:
c:\usr\local\gem\host> gemhost "set PORT :5556"
and for UNIX your invocation looks like:
$ gemhost "set PORT :5556" &
If you are running the simulator or other equipment on a different host, you specify the hostname or IP address on the command line as well.  If you set a value for the PORT variable on the command line, the program assumes that HSMS will not be used.  So, it you want to use HSMS, with a custom value for PORT, you need to also use the statement, "set HSMS 1".  Note that the use of the PORT value is slightly different from the gemsim application script. Here is an example of starting an HSMS connection to an equipment at a specified IP address and port:
$ gemhost "set PORT 192.168.2.4:5555" "set HSMS 1" &
Equipment expects to see its own device ID in the messages that the gemhost sends to it.  The default value is 0.  You can specify a device ID on the gemhost command line by assigning it to the global data item DEVID:
$ gemhost "set PORT 192.168.2.4:5555" "set HSMS 1" "set DEVID 5" &
If you use an incorrect device ID, you may see an  S9F1 "Unknown Device ID" message in the Trace Window.  Newer gemhost versions respond to this message by extractng the correct device ID value from the error message, and carrying on with the corrected device ID value.  You can use the Trace window to display the detailed header information and see the actual device ID in use.

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

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

The Gemhost User Interface

When the gemhost application is started, three toplevel windows are created.  The window titles are Host Equipment Interface - "gemhost", gemhost Trace, and EI Data Tables.  These windows are similar to the three windows that the gemsim application creates.
Host Equipment Interface - "gemhost"
The Host Equipment Interface window is divided into five panels; Communications & Control, Alarms, VFEI Reports, Processing & Process Programs, and Terminal Services.
 
The Communications & Control panel shows the current communication and control states.  When you start the application, the communication state will be "ENABLED {NOT COMMUNICATING}".  When the gemhost connects successfully to the equipment you see "COMMUNICATING".  The control state of the equipment, ON-LINE or OFF-LINE is also displayed.  There are two buttons to request that the equipment go ON-LINE or go OFF-LINE.  These buttons cause the S1F17 or S1F15 request messages to be sent.  The button labeled "Trace Window" is used to raise or create the Trace window.  The button labeled "Comm Enable/Disable" is used to toggle the state of communication; enable if it is disabled, or disable it if it is enabled.
 
The Alarms panel has a list of the alarm types that are known to the host interface, and whether they are enabled or disabled for reporting, and whether they are currently Set or Clear.  Buttons are provided to enable or disable selected alarms.  There is also a Save button that records which alarms you have enabled or disabled in a file.  When you perform an initialization, the interface enables or disables the alarms according to what you have configured.
 
The Processing & Process Programs displays the current Process State, and the current PPExecName (Process Program Name or "recipe") .  The Refresh button is used to query the equipment for these items as well as for the resident process programs which are then displayed in a list.
 
If the Refresh button does not show this information for your equipment, your equipment may not support it, or you may need customize the pertinent queries.  The code driving the window is in the file .../gem/host/host_ui.tcl.  The Process State and PPExecName items are displayed by subscribing to variable items in the ei_variable table where the VFEIname is PP_EXEC_NAME or PROCESS_STATE.  You can fix the display of these items by assigning these VFEIname values to the rows in the ei_variable table that have the corresponding data items but were named differently by your equipment manufacturer.  In other words, update just the VFEIname fields of the data items that represent the process state and the PPExecName to the standard VFEI names PROCESS_STATE and PP_EXEC_NAME.
 
The Select button is used to change the current PPExecName to the one selected in the Process Programs list.  Ordinarily you cannot do this unless the equipment is idle.  The Upload and Download buttons are used to upload and download Process Programs using the Tcl procedures defined in file ei_recipes.tcl.  Finally there is a row of buttons named Start, Pause, Resume, Stop, and Abort.  These buttons cause the corresponding remote commands to be issued to your equipment.  The configuration of the remote commands is represented as corresponding rows in the ei_variable table.  It is likely that you will need to update the varvalue fields for these commands to make them correspond to the SECS commands used by your equipment.
 
The Terminal Services panel is used to send a text message for display at the machine, and to display messages that are sent by the equipment to the host.  If the equipment supports the operator acknowledging the message, per GEM it comes up as an event report.  The gemsim application sends acknowledgments with the event ID (CEID) of 4100.
 
The VFEI Reports panel is used to create, edit, and save report definitions as well as perform related online actions.  The "Initialize" button causes the configured event reports and alarm configuration to be setup at the equipment.  The "Enable Events" button requests that the equipment enable and report all of its events.  The "Data Refresh" button is used to query the equipment about the variables that it supports.  Usually this action occurs automatically when the gemhost software first obtains an online control state with the equipment.  The "Event Discovery" button attempts to determine which events the equipment reports by enabling all of them, and then querying for the value of the "EventsEnabled" variable.  GEM equipment is supposed to support this Status Variable, but the equipment manufacturer is free to use a different name.  If the equipment uses a different name, update the variable's entry in the ei_variable table, and give it the VFEIname EVENTS_ENABLED before using the "Event Discovery" button.   You only need to execute "Event Discovery" once to determine the events.  If your equipment does not support the "EventsEnabled" variable, use the "Enable Events" button to make sure the reports are enabled, then you work with the equipment to cause it to create events and send them.  The gemhost software receives the events, and stores the event identifiers in the ei_event table.  Using the manufacturer's documentation, you can then update the ei_event table to provide descriptions of the reported events.  These descriptions are seen when you configure event reports, so the time it takes is well spent.  After you have updated the event descriptions, you should press the Save button on this panel to save your work.
 
To setup a VFEI report, you press the Create button and choose the event that you wish to base the report on.  Some of the events are created by the gemhost software, such as the COM_DISABLE event which is signaled whenever communication with the equipment is lost.  The Create button creates an empty event report - one with no variables attached.  You select the Event Report from the list, and press the Edit button to attach variables to the report.  After configuring your reports, you will want to press the Save button to preserve your work for future sessions.  Next, press the Initialize button to have the reports that you have configured be setup at the equipment.  From this point forward, you should get the event reports that you have configured, created as VFEI messages in the ei_vfei_output table.  If you are running as part of a DMH message group, the VFEI event report messages will be deleted from this table after they have been transferred to the VFEI_OUTPUT_MAILBOX, a configurable parameter that is specified in the ei_variable table.
 
gemhost Trace Window
This window is the same type as in the gemsim application, described above.
 
EI Data Tables Window
As with the gemsim application, the gemhost provides the user interface of the datahub application for your convenience in managing the SQL tables that are used by the equipment interface logic.  See the description above.

Gemhost Message System Integration

If you specify a DMH message group name on the command line by assigning it to the global variable MB_GROUP, the gemhost will connect to the message system during startup.  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:
$  dmh_server gem &
$  gemhost "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.

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

$ hubclient gemhost_SQL@cimdev:gem &
Next, the gemhost 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.  The usual success result is to receive the SECS reply message in Tcl Secs Notation.  The procedure has the logic needed to handle the failure cases of not being able to send the primary message, receiving an abort message, receiving a Stream 9 reply, or having a T3 timeout occur.  The failure cases cause an appropriate message to be sent to the DMH reply mailbox, namely "TIMEOUT BAD_SEND", "TIMEOUT ABORTED", "TIMEOUT REJECTED", or "TIMEOUT NO_REPLY".  The calling signature of the secs_dmh_reply procedure is:
secs_DMH_reply spname sfr {tsn {}} {replybox @defaulted@}
where spname is the interface name, sfr indicates a stream and function such as S1F1R, tsn is the optional body of a message in Tcl Secs Notation, and replybox is the DMH reply mailbox which defaults to the reply mailbox of the latest received DMH message.  You may review the logic and details of the secs_dmh_reply procedure by examing its source code in the gem/lib directory.  This procedure and the DMH integration techniques are also useable for the Hume provided GEM Equipment software.

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

       mid_vfei_init gemhost

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

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

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

The original VFEI specification was closer to this format - a simple but standard means of expressing equipment integration commands in text.
 

Understanding the Gemhost Application

The gemhost script processes the command line and defaults, and gets the application started.  This file is probably a starting point for you to review the application code.  The communication and control state logic is mostly in host.tcl.  The logic that drives the Host Equipment UI is in host_ui.tcl.

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

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

 

The GEM Supervisor Application

The supervisor application is used to configure and manage the startup of multiple equipment interfaces.  When the application is first executed, a default configuration exists that will start the gemhost equipment interface.  Using the supervisor, you can create new equipment interfaces with names of your own choice.  You can specify whether the equipment interfaces should be started automatically when the supervisor script is started.  The custom connection information that the gemhost application accepts on its command line, can be defined and saved.  When the supervisor starts an equipment interface, the same windows that the gemhost application creates are created - the Trace window and the Host Equipment Interface Window.

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

The GEM Supervisor User Interface

When the supervisor application is started in foreground, a single 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.  As discussed with the gemhost application, most of the important configuration data such as the variables supported by the equipment, will be discovered dynamically.
Edit...
This button supports revising the startup record.  The "EI Startup Configuration" dialog is presented.  This dialog is used to configure the basic information needed to connect to SECS equipment, including the SECS Device ID, and the connection type. Additionally, there are checkboxes to disable the queries that normally occur during initialization.

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

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

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

Copy...
Use this button to copy (clone) an interface configuration to a new name.  You will need to Edit... the startup configuration to point to another connection.  The copied data is not saved by this action - it only exists in memory.  Use the "Save Tables" button to save the data.
Delete...
After confirmation, the selected interface configurations are deleted from the in-memory database.


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

Start
This action starts the interface running.  You will see the Trace and UI windows appear.
Stop
This action does a shutdown of the equipment interface.  The associated windows are destroyed.
GUI
This action raises or creates the User Interface window of the selected interface.  Unlike the Start button, this action does not enable or change the state of communication.  So this button can be used to obtain the User window without enabling communication.
SECS Trace
This action is used to raise or create the Trace window.


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

Refresh
This button is used to refresh the status information in the list of equipment interfaces.  You are able to determine which equipment connections are running and what their communication state is.
Save Tables
If you have not started any equipment interfaces, pressing this button causes your current startup configurations to be saved to the file system in the file ei_startup.tab.   If you have started an interface, then the application logic has loaded any previously saved application data so you are offered a choice of whether to save all of the in-memory application table data, or to just save the startup table. 
Host Tables
This button brings up the Datahub user interface.  You can browse and work directly with your application SQL table data.
Tcl Console
This button brings up a command prompt to interactively work with Tcl code.  It is equivalent to the Tcl Command... menu item on the Datahub File menu.
Exit
After confirmation this action stops all the equipment interfaces and terminates the program.
 

Building Equipment Interfaces

 In the description of the gemhost application, we described how to customize to the connection parameters on the command line and how to create and save event report and alarm configurations.  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.  If you use the approach described in the gemhost application discussion,  your interface is named gemhost.  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.

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

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

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

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

  1. Start your interface with your chosen connection name and connection parameters.
  2. Hopefully your equipment is standard enough to report most of its variables.  If not, you need to manually add the ones you'll work with to the ei_variable table.  Use the gemhost/gemsim data as examples.  You can use the Datahub UI or edit the SQL statements in the saved .tab file.
  3. Use the application UI to characterize the useful data and event notifications that come from the equipment.   Update the parameters in ei_variable table as needed.  Use the "Event Discovery" button or the "Enable Events" button, collect events, and update the event descriptions as needed.  Whenever you change the configuration tables, be sure to save them.
  4. Enable/Disable alarm reporting to your liking.
  5. Create and Edit the event reports to your liking.
  6. Discover your need for customization and deploy your changes.
You may discover that the equipment does not give you the events that you want, or that certain alarms should be event reports or vice versa.  Your driver software can map alarms to events or vice-versa by opening a subscription to the ei_alarm_log or ei_event_log table, and when your procedure subscription is activated upon the insert of a new row, you can call ei_driver_event or insert a row into the 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 driver software functionality to forwarding VFEI event and alarm messages to higher level software, and accepting VFEI commands from higher level software.  This gives you maximum re-use of your equipment drivers.  In the higher level software you can build elaborate state machine configuration tools, utilization tracking, MTTA, MTBF reporting, business rule engines, and the like.  Your drivers can be "plugged" and "unplugged" as supported by attaching or unattaching to the DMH message system.  Because of the way you have partitioned the driver level, the higher level tools can easily be applied across all of your equipment.
 


SQL Table Schema

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 gem/equip/eq_alarms.tcl, is also available to add new alarms using Tcl code. Equipment software reports alarm set or clear conditions by updating the is_set field for the particular alarm using the SQL update statement. The GEM equipment software is then triggered by a table subscription, and it takes care of sending the alarm report and the associated GEM data collection event to the host. The reporting logic allows for the possibility that the alarm or event are possibly disabled, or that the communication may be broken and the reports need to be spooled. The reporting logic is also found in the gem/equip/eq_alarms.tcl file.
 
Column Name Key Type Description
spname PCK varchar(32) The secsport or hsms connection name that a particular row is associated with.
ALID PCK varchar(20) A unique identifier for the alarm defined by the equipment.  It is usually an integer, but it is saved and manipulated as a text string.
ID_TSN   varchar(8) The Tcl SECS Notation type code for the ALID data item when passed in a SECS-II message.  The host discovers the ID_TSN from equipment originated messages.  An example would be I4, signifying a signed 4 byte integer.  See the TSN reference documentation.
category   int Alarm category.  The value 0 means category is not used.  The GEM standard does not use the encoding of category in alarm reports.
is_enabled   int This field is used to store the current alarm setup state; whether the alarm is enabled for reporting or disabled.
is_set   int This field is used to store the current status of the alarm - whether it is set (1) or clear (0).
ALTX   varchar(40) This is the alarm description which is usually reported by the equipment when reporting an alarm.  If the equipment does not report the ALTX (the reported value is blank),  the host GEM-EI software will check this table for a possible description. 
host_managed   int Host usage only. If this field is non-zero, it means that the host should either enable or disable the alarm when performing the equipment initizalization.
host_wants_enabled   int Host usage only. The value in this field indicates whether the alarm should be enabled (1) or disabled (0) if the host_managed field is non-zero.
set_CEID   int Equipment usage only. Per GEM, the setting of an alarm causes a data collection event. This field holds the CEID, collection event ID, which is fired when the alarm is set. 
clear_CEID   int Equipment usage only. Per GEM, the clearing of an alarm causes a data collection event. This field holds the CEID, collection event ID, which is fired when the alarm is cleared.



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.

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

If you are not using VFEI, you need to supply your own logic to prune the rows in this table.  You will typically want to delete a row after successfully passing it on to the higher level software, or code a limit to the number of rows, or age of rows kept in memory.  If you do not limit the memory use, the application will eventually crash.
 
 
Column Name Key Type Description
spname PCK varchar(32) The secsport or hsms connection name that a particular row is associated with.
clock PCK varchar(16) The time of the alarm report formatted as YYYYMMDDHHMMSScc.  This value will be unique for the particular spname.
ALID PCK varchar(20) A unique identifier for the alarm defined by the equipment.  It is usually an integer, but it is saved and manipulated as a text string.
is_set   int The reported status of the alarm - whether it is set (1) or clear (0).
ALTX   varchar(40) The alarm description provided by the equipment with the report, or the text from the ei_alarm record.



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 gem/lib/dataset_xfer.tcl and gem/lib/ei_ppid.tcl.  The transfer logic uses a subdirectory of the recipe directory for large file transfers so that replacement files do not overwrite their destinations until they are received completely, and so that process program files do not appear in directory listings until they can be verified.
 
Column Name Key Type Description
spname PCK varchar(32) The secsport or hsms connection name that a particular row is associated with.
HANDLE
PCK varchar(16) The type code and handle value used by the opposite party in the dataset open message, S13F3. 
is_send PCK
int Used as a boolean to indicate whether the data set is being sent (1) or received (0).
dsname

varchar(200)
The data set name which is also a Process Program ID (PPID).
pathname

varchar(500)
A full pathname to the file being transfered.  When sending from equipment, this will be a temporary copy of the file in the transfer directory.  When sending from the host, this is a file in the recipe directory.  When receiving, this is a file in the transfer directory.
channel

varchar(20)
When sending, an open file is used.  This field value is the channel identifier from the Tcl open command.
timer_handle

varchar(20)
This field holds handle values returned from the Tcl after command for timers that are used to check whether the opposite party has been timely with sending expected messages.
pid

varchar(12)
The process identifier of the process which opened a file for sending.  In the scenario of making this table peristent and resuming incomplete transfers, you would want to check for your own process ID before closing a channel.
ts_begin

varchar(26)
A high resolution timestamp in the local timezone (localtime format 15) when the row was created. 
ts_close

varchar(26)
A high resolution timestamp in the local timezone (localtime format 15) when the transfer became inactive either by completing successfully, or by being cancelled.  Cancellation occurs by the opposite side closing the HANDLE using S13F7 or S13F9.  Cancellation can also occur during initialization or upon re-starting a dataset transfer which ended with error.
readln

int
This is the read size either provided by the requestor in S13F5 or figured out by the receiver when handling S13F4.
reclen

int
This value is the maximum read size returned by the sender in S13F4.
rtype

int
This value is the <rtype> value returned by the sender in S13F4.
ckpnt

int
This value is the checkpoint value received in the latest S13F6 reply.
status_code

int
This value is 0 if the transfer is proceeding without error.   A non-zero status_code usually indicates that the transfer has ended without success.  However, status codes indicating transfer conversation timouts do not indicate a failure end - the transfer can still succeed if the opposite party continues.  The following codes are used:
0 - normal error free progress
1 - cannot resume receive (no partial file, or no partial results)
2 - open attempt failed
3 - read attempt failed
4 - open reply had improper data
5 - open reply had ACKC13 error code
6 - open reply had a changed HANDLE value
7 - open reply had a changed DSNAME
8 - open reply had an unknown RTYPE
9 - open reply had discrete records with record length of 1 meg or larger
10 - read reply had improper data
11 - read reply had ACKC13 error code (not EOF)
12 - read reply had changed HANDLE value
13 - read reply, transfer table record missing
14 - read reply, partial file missing
15 - read reply, file open error
16 - read reply, data was not type B or A
17 - read reply, file writing error
20 - file error when preparing read reply
21 - S13F1R offer attempt failed
22 - S13F1R offer reply data error
23 - S13F1R offer reply error code reply
24 - cannot create transfer directory
25 - timeout waiting for S13F1 offer
26 - timeout waiting for S13F3 open
27 - timeout waiting for S13F5 read
28 - timeout waiting for S13F7 close
29 - cannot delete old file to receive replacement
30 - verification attempt failed
31 - downloaded dataset failed length verification
status

varchar(80)
A brief description of the status code or the latest success state. 



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.
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 COMM_DISABLE represent events that are created by the host driver software instead of the equipment.  So they can be received even when your equipment does not support event reports.

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

AUTO_VIRT_INIT
When the host interface is started, or it is seen that the equipment has transitioned from an offline to online state, the host interface software will attempt an initialization sequence, if the AUTO_VIRT_INIT parameter stored in the ei_variable table is configured true.  When the initialization sequence is completed, the event is signalled.  The success or failure of the initialization can be determined using the AUTO_INIT_RESULT variable.  Typically an event report is defined so that the CLOCK and AUTO_INIT_RESULT are reported with the AUTO_VIRT_INIT event.
COM_DISABLE
This event is reported when communication with the equipment is lost.  The latter is detected by a broken TCP/IP connection, or a broken SECS-I transaction.
COM_ENABLE
This event is reported when communication with the equipment is successfully established.
TRACE_REPORT
This event is reported when a S6F1 Trace Report message is received.  You can define event reports based on the TRACE_REPORT event to pass the trace data into the same software that is used for event reports.
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 gem/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 COMM_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_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.

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

If you are not using VFEI, you need to supply your own logic to limit the number of rows stored in this table. 
 
 
Column Name Key Type Description
spname PCK varchar(32) The secsport or hsms connection name that a particular row is associated with.
clock PCK varchar(16) The time of the event report formatted as YYYYMMDDHHMMSScc.  This value will be unique for the particular spname.
CEID PCK varchar(32) The identifier for the event. 
data   varchar(20000) A proper Tcl list containing {name value} pairs for the variable values received in the event report.



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


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 COMM_DISABLE is given a CEID of vfei_COM_DISABLE.

Report definitions that are not like 'vfei_%' represent actual reports that are setup or have been received from the equipment.
 
 
Column Name Key Type Description
spname PCK varchar(32) The secsport or hsms connection name that a particular row is associated with.
RPTID PCK varchar(32) An identifier for the report.
VIDs   varchar(1000) An ordered list of the varID's from table ei_variable for equipment based reports.  An ordered list of VFEIname's from table ei_variable for VFEI reports.



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 COMM_DISABLE is given a CEID of vfei_COM_DISABLE.

Report definitions that are not like 'vfei_%' represent actual reports that can be setup on the equipment.  The configuration logic creates reports that have the same RPTID as the CEID that the report is tied to.  The user's simplified configuration model is that he directly associates a set of variables to be collected for a given event.  The existence of reports as a separate entity is hidden.
 
 
Column Name Key Type Description
spname PCK varchar(32) The secsport or hsms connection name that a particular row is associated with.
RPTID PCK varchar(32) An identifier for the report.
VIDs   varchar(1000) An ordered list of the varID's from table ei_variable for equipment based reports.  An ordered list of VFEIname's from table ei_variable for VFEI reports.



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.
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 constant 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 constants that are used by the equipment. The default value is 1. Since the set of constants 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 .../gem/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 Constant 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. The value is read once early in the initialization logic so it is typical to need to stop and restart the host interface to use an updated value.

<>Similarly, the RCMD remote commands are not standardized, and the following data item varvalue fields may need to be updated in the host's records for your equipment: RCMD_ABORT, RCMD_PAUSE, RCMD_PP-SELECT, RCMD_RESUME, and RCMD_STOP.

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 Constants, 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 Constants, 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 Constant Variable.  These are parameters maintained by the equipment whose values can be set by the host. 
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 Constant Variable.
ECMAX   varchar(32) The maximum value of an Equipment Constant Variable.
ECDEF   varchar(32) The default value of an Equipment Constant 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)

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: 2008/08/21 14:26:28 $

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.4/Tk 8.4 versions for UNIX and Windows NT.  There are newer improved versions of the SECS/GEM applications available for Tcl/Tk 8.5 in the DMH85 version of the Datahub SDK.


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