SecsHost - A Java Library for Host SECS Interfaces


The SecsHost class library provides a high-level start when deploying Host SECS Interface software using the Java 2 Platform. Without any code development, the software is able to communicate with GEM standard equipment, manage dynamic Event Reports, upload and download process programs, and manage automatic online initialization.  The library also imbeds extensive fallback logic that accommodates working with non-standard and non-GEM compliant equipment.  A supervisory application is provided with source code that enables you to interactively configure and manage multiple Host interfaces.  Application source code is also provided for a Host Graphical User Interface (GUI), and related dialogs such as property editing, and a window to display detail on the data that is being exchanged over the SECS interface.  The SecsHost software operates with or without these windows being present - it is a component that can be imbedded and deployed in an application of your own design.  An application developer registers callback interfaces to receive asynchronous inputs such as Event Reports, Alarm Reports, or specified SECS message types.  The example application code demonstrates using these techniques without undue complexity.  You can readily understand how to use the software and get on with building your own application, or you can customize the application we provide to meet your own requirements.

Feature Summary


User Guide

To get started, the Java host developer downloads three archive files from the Hume download site:
  1. JavaHostApp.zip (JavaHostApp6.zip for JDK 6)
  2. humeDocs.zip
  3. DMH85_NT.zip for Windows (or DMH_Linux.zip or a similar platform specific DMH85 archive)
The JavaHostApp.zip archive contains the SecsHost.jar, Java source code, and the example SEC/GEM host supervisor application.

The humeDocs.zip contains the javadoc files for the SecsHost library and related classes.  This is an essential download for Java developers.  You need to associate the documentation in this archive with the SecsHost.jar in order to have in-context API prompting while using Eclipse or similar IDE's.  The javadocs material contains API reference documentation without the introduction and guidance found in this document.  The content is browseable on the Hume website at http://www.hume.com/java.

The DMH85_NT.zip archive is the Hume Datahub SDK.  It includes this documentation, along with SECS/GEM software which is used by the Java library as an intelligent SECS server process.  The SDK archive also includes equipment applications for you to communicate with your host interface in order to exercise and test it during development.

Lets get the files installed and ready for use, and then review the files contained in the JavaHostApp.zip archive.

Installation

For a new development setup, extract the DMH85 SDK .zip archive to a temporary location.  Go into the directory where the files are, either in a command window or using a file explorer.  Run the setup.cmd program on Windows or SETUP for POSIX systems.  Use the Install.htm installation help file in this directory for more detail than this summary.  Accept the default installation choices of (1) including the core Datahub SDK files, (2) including HTML files, (3) including SECS/GEM programs, (4) creating a Program Manager group, (5) registering PATH and environment variables, and (6) installing a license file.  Other choices, including the Installation Path are up to you.  On POSIX platforms such as Linux, HP-UX, and Solaris we recommend you stay with the default Installation Path to avoid needing to configure a runtime shared library path.

If you install the Datahub SDK on Windows, then you get a Program Group that includes the Program item "Gem Equipment".  This is a convenient equipment program to run for testing your Java host application.  

Turning our attention to the Java software, you want to use an IDE such as Eclipse or NetBeans.  Eclipse may be downloaded from http://eclipse.org and it is our recommendation for new users.   Make sure you are using a 1.6 or newer version such as 1.8 of the JRE or JDK with your Java IDE.

Extract the files in the JavaHostApp.zip archive to a directory of your choice such as c:\java\hume\host.  Do not extract the files into any of the subdirectories created by Datahub SDK installation. 

The humeDocs.zip archive does not need to be unpacked to be used by Eclipse.  However, you probably want to extract the files in humeDocs.zip to make it convenient to browse them when not running Eclipse.  The humeDocs.zip archive contains some of the same directory paths used by the Java source code.   We recommend you keep the documentation and code separate by extracting to a different directory such as c:\java\hume\doc.   This enables you to share the same javadoc install with a Hume java equipment or java Datahub installation too.  After extracting the files, create a Bookmark in your web browser to the javadocs index.html file, and similarly to the Hume SDK documentation index.html file in the html85 SDK subdirectory.  The SDK installation creates a Program Item for the SDK documentation which you can load and bookmark.

The directory you chose to extract the JavaHostApp.zip files becomes the base of your java CLASSPATH when executing the provided application.  There is a .classpath file included in the .zip file which is installed in the directory base to help Eclipse and similar IDE programs add the SecsHost.jar file to the classpath. 

Here is a summary of how to create an Eclipse project for the host supervisor application.  
  1. Use the menu item File/New/Java Project
  2. Fill in the Project Name - for example,  hostSECS
  3. In the Contents frame,
    1. Uncheck the "Use default location" box, and navigate to the source code directory using the "Browse..." button.
    2. Fill in the Directory field by browsing to the directory you extracted the java files such as "c:\java\hume\host"
  4. Press the "Next >" button at the bottom to move to the next dialog.
  5. See the tabbed notebook panels at the top.  Click on Libraries.
  6. The first item in the Libraries is the SecsHost.jar.  Click on the (+) sign to expand the item.
  7. Click on the "Javadoc location: (None)" line to select it and press the Edit... button on the right.
  8. Associate either the humeDocs.zip extracted files or the .zip file.  In either case press the Validate... button and then the OK button when done.
    1. For extracted files, use the first radio button choice "Javadoc URL" and Browse... to the directory where the javadocs were extracted such as "c:\java\hume\doc"
    2. For the .zip archive, use the second radio button choice "Javadoc in archive", choose "External file" and browse to the humeDocs.zip file.  For "Path within archive" enter "/".
  9. The .classpath file we provide should have already associated the Source attachment directory, com, with the SecsHost.jar file.  However, If you see under the SecsHost.jar libary item, Source attachment: (None)", select it and press the Edit... button on the right.  Then in the "Source Attachment Configuration" dialog, browse and select the "Workspace..." directory com.  The selection is shown as "/hostSECS/com".  Press OK.
  10. Press the Finish button (or the OK button if you are revisiting the Project/Configure Build Path dialog).
Now you are ready to browse the demonstration application.  In the left Package Explorer pane, expand JavaHostApp and double-click on SuperGUI.java to load it into the editor. 

Here is how you can verify that you have properly installed and created an Eclipse project.   In the open file SuperGUI.java, type control L (ctrl-L) and enter line number 154 to go to line 154 of the file.    A source line near that location is similar to "nh = new SecsHost(newname, SecsConn.getDmhGroupName())".   Move your mouse over the SecsHost class name and you should see API help appear for the SecsHost class.  If you hover over SecsHost, you see help for the constructor.  Now click the mouse on the SecsHost term and press the F3 button to display the source code.  The SecsHost.java file should be loaded into the editor, and you should be located at the constructor declaration.

If you installed the Hume SDK with the default paths, you should be able to run or debug the application right now.  If you installed the Datahub SDK in a non-default directory, you may need to close and restart Eclipse so that it sees the new system environment variable DMH_BIN.

To see how the SecsHost class is used, review the application source code.  The host connection initialization is driven by the property data configuration which you edit using a SecsHostEditor window.  There are explicit actions and method invocations in response to button actions that you see in the SuperGUI.java and HostGui.java files.

Using Eclipse you can easily browse the Java source and API documentation.  Here are the more noteworthy items in the distribution:
Our distribution is tested on recent Windows Professional versions such as Windows XP Pro, Vista Pro, or Windows 7 Pro.  The software is designed for portability to other platforms, and is also been tested on up-to-date Linux systems.  Customers who intend on using other platforms should contact Hume Integration so that their compatibility and testing requirements are known.

To deploy a runtime system, combine your application with the SecsHost.jar file from the JavaHostApp.zip.  A development setup uses the SECS/GEM application files provided in the Hume Datahub SDK product.  For a runtime system instead of installing the Datahub SDK, you can choose to deploy a single file executable, SecsServer.exe which is extracted from the SecsServer85.zip download for Windows.  For Linux, the SecsServer executable is extracted from the SecsServer85Linux30.zip archive.   We encourage you to use the full SDK during development so that you have the toolset documentation, and our easy-to-use, and feature-rich Tcl/Tk Gem Equipment simulator application installed as a Program Item.

Environment Variable DMH_JAVA_TCLDIR

When the SecsHost software is initialized, it needs to find the Datahub SDK files or the SecsServer executable.  The startup logic first searches for the SecsServer executable in (1)  the directory pointed to by the environment variable, DMH_JAVA_TCLDIR  and then (2) the current working directory.  If the SecsServer executable is not found, then the startup logic looks for the SecsServer.tcl application script and the supporting files that are part of the Datahub SDK.  The search order for the SecsServer.tcl file is (1) the directory pointed to by the environment variable, DMH_JAVA_TCLDIR,   (2)  the gem2/server directory of the Datahub SDK installation found using the environment variable DMH_BIN or by checking the default installation path, and (3) the gem/server directory of the Datahub SDK installation found using the environment variable DMH_BIN or by checking the default installation path.

We recommend you set the environment variable DMH_JAVA_TCLDIR to the directory path containing the SecsServer.tcl file or the SecsServer executable to establish a well defined startup.  Use slash directory separators.  On Windows environment variables are set by navigating from the Start menu - Start/Settings/Control Panel/System/Advanced/Environment Variables.  An example value is:
DMH_JAVA_TCLDIR=C:/usr/local/gem2/server
In a runtime deployment, the SecsServer executeable file is placed in a directory of your choice as specified by the DMH_JAVA_TCLDIR environment variable.  The default directories used for process program transfer and trace logging are subdirectories of where the SecsServer or SecsServer.tcl file is found.

Development

To start using the SecsHost class with an existing project, you add the SecsHost.jar file to your CLASSPATH.

Coding is easier if you add the statement import com.hume.SECS.*; to the import statements of your application source code.  By doing this, the package name, com.hume.SECS, can be omitted from name references.  You will typically want to add the statements:

import com.hume.SECS.*;
import com.hume.DMH.*;

to make it convenient to use the SECS software and work with String text that is structured as lists.

Your primary focus as a developer is using the class SecsHost.  This class implements public methods to send and receive SECS messages, and manage a host SECS interface.

Here is the general flow of using and configuring the SecsHost:

  1. Run the supervisor application and take a look at the SecsHostEditor dialog in action.  You probably want to have this dialog in your application to let your users easily configure Host interfaces.  Run the application against real equipment, explore the example GUI,  and develop confidence that the core logic will work well in your custom application.
  2. Make a decision as to whether you will modify the provided files for your own requirements, or create your own application, and include selected features of the Hume application by adding selected files to your project.  If you move a Java file to your own directory, you typically edit the package JavaHostApp; statement near the top of the file to indicate your own directory/package name.
  3. You can use the SecsHost class with or without user interface windows being present.  You can code setting the event callbacks to your application object(s) late in your constructor code, and remove these event handlers in a finalize method.
  4. Construct a SecsHost instance.   At runtime, constructing the instance causes the child SECS server process to be started.  The Supervisor application uses a constructor that passes many of the configurable property values as String array arguments.  There are also simpler constructors where you create your instance, and subsequently use property assignment statements to configure the instance.
  5. Code your callbacks.  The reception of Event Reports and Alarm Reports are dispatched into your application using callbacks.  In general the callbacks come into your application from different threads than the thread that created your window controls.  In general, the window controls are not designed to be used by different threads than the main GUI thread of your application.  It is proper and documented that the JComponent.setText() and JTextArea.append() methods are callable by different threads.  For other methods that affect the GUI, use the SwingUtilities.InvokeLater() method as the example application does to pass work to the main GUI thread.  Use threadsafe techniques such as the synchronized statement to lock data structures before reading or writing to them from different threads.  Here is an example statement to execute the GuiXXXUpdate() method in the main GUI thread:
  6. SwingUtilities.invokeLater(new Runnable() {public void run() { GuiXXXUpdate(); }})
  7. Use the messageTypeAdd method to register callbacks for SECS message types that you desire to handle in your application.  Getting communication established and capturing alarms and event reports is already provided for.
  8. Change property values to your liking.  This includes setting the connection items such as the serial port or HSMS port and hostname to the desired values.  Call connectTypeSet or one of the connectType<Type> methods at this stage to fully initialize the instance data prior to configuring event reports or manually adding event and variables for equipment that does not support discovery features.  If your application has called the SuperSave method in a previous session, the known data items and the report configuration data from the previous session is loaded by initializing the connection type.
  9. At this stage, your application logic can edit the configuration of event reports.  GEM equipment supports letting the host discover status variables and parameters,  so interactive report configuration is usually done after being online and discovering the data items, or after restoring the data items known in a previous session.  If your equipment lacks support for discovery, at this point you can call the manual configuration methods such as variableAdd and eventAdd.  Proper GEM equipment may lack features for the discovery of events and DVVAL variables.  The Hume equipment software features description variables to provide the host with this configuration information so that manual configuration of these items is not necessary.
  10. Now, with your desired configuration in place, call commEnable to enable communication with the equipment.  The establishment of communication takes place some time after the call returns.  If you want to exchange SECS messages with the equipment, you can trigger your custom logic from receiving a COM_ENABLE event report, an AUTO_VIRT_INIT event report, or some other event report.  See the eventReportDefine method, the list of Built-in events, and the EventReport callback.  Or, you can receive status indications from the StateChange event, and use those to know when online communication is possible.
  11. If you update any of the connection properties after communication is enabled, call connectTypeSet or one of the connectType<Type> methods.  The method call will disable communication so you will need to call commEnable again.  Connection properties include the ConnectionType, BAUD, HSMS_Host, HSMS_Passive, HSMS_Port, and Serial_Port.
  12. Non-connection properties such as the Device ID, timer values, data types, etc. can be updated at any time without disrupting communication.  The Hume software does feature adaptive logic to automatically correct the Device ID, and to learn the data types used by the equipment.  Your configuration effort is substantially reduced compared to other products.
  13. Automatic initialization occurs by default whenever the equipment transitions to an online control state.  The default behavior is to attempt to discover the equipment's alarms, variables, and events, and setup the configured event reports, managed alarms, managed equipment constants, and synchronize the clock.  This behavior is controlled by setting the appropriate property values and/or configuring the managed reports, alarms, or constants.
  14. Call commDisable to disable host communications.  It is called automatically by the SecsHost delete and finalize methods.

Tcl Secs Notation, TSN

SECS messages are passed into and out of the application as formatted strings.  The format is similar to the notation in the SEMI documents except that the list formatting conventions of the Tcl programming language are followed.  The TclList class provides methods to parse and construct lists.  In general, curly braces, { }, are used to surround list elements which contain white space.  By using the API calls to append list elements or join strings as list elements, you can be sure that your strings are properly formatted, and you do not need to manually balance opening and closing curly braces.  Developers who have worked with both XML and TSN list notation have found that the TSN notation is more compact, closer to the SEMI documentation, and easier for a human to scan and validate when reviewing diagnostic output.

As general guidance, when you expect a string value, you will get a two element list, of the form "A:n {this is n chars of text}".  If a string value does not have imbedded white space, it may be formatted without braces, such as "A:8 OneToken".  When you use the TclList.listElement or split methods to parse the text, they take care of parsing and removing surrounding braces for you.  If an empty string is sent, you will see a one element list, A:0. 

For parsing lists or extracting items from TSN text, use the TclList class or the StringList class.  The StringList class is easier to use than the TclList because it does not throw exceptions, but it does not have the static parsing methods that TclList offers.  To construct TSN text, the ListBuilder class is more efficient and has more options than TclList or StringList.  Use your context sensitive help to display the API reference material for these classes.  The API reference is also online at the Hume website java directory.

SECS has the notion of array data - 0 or more values of a given type.  When you expect to receive a single numeric value, you receive a two element list, with the type code as the first element, such as "U4:1 290".  You can also receive an empty array "U4:0" or an array with more than one value as in "U4:3 0 1 2".  Binary data values are formatted using C-language hexadecimal integer notation, for example, "B:3 0x00 0x01 0x02".  You can use the binToInt method to convert these values to integer values.  With received data, the type code has a length value appended to it after a colon.  With data that you format for sending, the length information is optional, the data is parsed to determine the length.  See the TSN.html document for more details.
 
Semi Octal type code TSN type code Meaning & Examples
00 L List,  L, L:0,   "L {A {atc 100}} {A 1.0.0}", "L:2 {L:2 {U4 200} {U4 210}} {B 0}"
10 B binary - unsigned 8 bit data, "B 0", "B 1 2 3"
11 TF  boolean data, TSN type codes BL or BOOLEAN are also accepted as input, "TF 1"
20 A Character string data.  Traditionally this has meant printable ASCII characters but some implementations are sending any 8 bit characters including nulls using this type.
"A {hello world}", "A hello"
21 J Japan International Standard (JIS-8) encoded text.  This format is not commonly used or supported because in the past the SEMI standards have failed to identify specific reference documents.
22 V1..VE Variant data, also known as Localized Character Strings.  Your unicode text is automatically converted into the chosen encoding.  V1 is for Unicode 2.0, V2 is for UTF-8 encoding.  See the TSN.html document for more details. "V1 {sent as Unicode}"
30 I8 8-byte signed integer, use hex notation for the value, "I8 0x123456789abcdf01"
31 I1 1-byte signed integer, "I1 -3"
32 I2 2-byte signed integer, "I2 99",  "I2 15 -7 99"
34 I4 4-byte integer signed, "I4 -5"
40 F8 8-byte floating point, "F8 6.02e23", "F8 0.1"
44 F4 4-byte floating point, "F4 1.0"
50 U8 8-byte unsigned integer, use hex notation for the value, "U8 0x7fffffffffffffff"
51 U1 1-byte unsigned integer, "U1 0"
52 U2 2-byte unsigned integer, "U2 512"
54 U4 4-byte unsigned integer, "U2 979"

 

Built-in SECS Data, Message Handling, Events

The SecsHost class has built-in logic to handle many of the standard SECS message types.  You do not have to code or provide for complex GEM capabilities such as configuring and receiving dynamic event reports, or managing the equipment communication and state models. See the table at the end of this document for more detail on the built-in message types.  If you are not familiar with the Hume host SECS software, you may wonder if the API is missing methods, for example to add variable definitions or event definitions.  In most cases, the software automatically determines the Status Variables and Equipment Constants by querying the equipment.  The SECS standards lack support for directly determining types of events.  The software listens to the events reported by the equipment, and adds them to its table of known event types.  If new Status Variables are seen in an Event Report, the software automatically saves configuration records for the newly discovered variables.  So instead of laboriously configuring event and variables from some inaccurate manual, you simply deploy the software, and run the equipment to accumulate configuration information.  Discrete Variable Event Reports (S6F3) and Discrete Variables are another area where the standards are deficient, and do not provide for programmatic introspection.  The built-in logic saves configuration information on the format of Discrete Event Reports and their included variables as they are encountered.  The Supervisor application has the ability to copy the accumulated configuration information determined from an equipment interface to new names.  This provides the ability to clone working interfaces for use with multiple instances of similar equipment in your factory.  In the rare circumstances where you want to manually make configuration changes, you can use the debugTableWindow method to bring up a GUI that enables you to interactively examine, edit, and save the SECS Server configuration tables.
 

Custom SECS Message Handling

Use the method messageTypeAdd to have SECS messages routed to your callback code for custom handling.  You can use this method to provide handling logic for new message types, and you can also use this method to replace the built-in handling of selected message types.  Your callback executes in a different thread than your main Windows event dispatching thread so use thread safe techniques for accessing application data or GUI controls.  The positive side of using a different thread is that your handling logic can be coded to use simple synchronous wait-for-reply SECS conversations without locking up your GUI.  For example, your callback can use sendReply to respond to the inbound message, and then initiate a synchronous conversation using sendSecsMsg and specifying that the logic should wait for the reply message.  While your handling code is progressing through the synchronous conversation, other software in your application can be handling event reports, or alarms or managing other interfaces.  Because of the internal design of the SecsHost, these other method calls are not blocked or delayed because your handler is busy with a conversation.

Logic in your application can send SECS messages or initiate conversations using the sendSecsMsg method.  For HSMS communication,  if you are sending a message and not waiting for the reply, sendSecsMsg can be used from your GUI code without fear of making your GUI unresponsive.  In some cases you need to wait for a SECS reply message.  If you are using HSMS, under most circumstances, the reply or failure to reply will be resolved within a few seconds.   The unusual circumstance is that you still have a TCP/IP connection so your send is successful, but then there is no reply, and you wait the full T3 period.  If the risk of this delay is not acceptable, you can create a new thread, and use the new thread to perform the SECS conversation where you need to wait for the reply message.

For SECS-I serial communication, timing is somewhat different.  With SECS-I there is no underlying TCP/IP connection that can signal the application when it is broken.  So there is a higher risk of your sending thread being in an unresponsive wait to determine if a send is successful, and then in a longer wait to obtain the reply.  So you may want to use a separate thread than your GUI thread to send SECS messages or conduct send-and-reply conversations.

Miscellaneous Notes

You can use multiple instances of the SecsHost class to provide more than one SECS interface.  Each interface can have its own custom handling of message types.


SecsHost API Reference


 SecsHost Properties
Property Access Description
boolean isAutoInit()
void setAutoInit(boolean autoInit)
Configures whether the interface should execute initialization logic automatically when an online control state is established or re-established.  Since the actions performed during initialization are configurable using other properties, most application will configure the individual actions, and leave this overall flag at its default value of true.
boolean isAutoStart()
void setAutoStart(boolean autoStart)
Configures whether the interface should be started automatically with communication enabled.  This property is used if the interface is created using the constructor method that accepts the property values as string array arguments.  The default value is false.
int getBAUD()
void setBAUD(int baudrate)
If you are using the SECS-I, RS-232 connection type, this property sets the baudrate of the serial port.  The default value is 9600.  If communication is already enabled, you have to make a connectTypeSerial() or connectTypeSet() call to use a changed value.
String getCeidOffline() 
void setCeidOffline(String ceid)
The event report identifier (CEID) that signifies that the equipment is transitioning to an off-line control state.  This value is used by the logic that tracks the equipment control state.  The default value is "4000".
public Object clientData The SecsHost class has a public clientData value that the example HostGui class uses.  If you replace the HostGui class, you can use this as a pointer to your own application object. 
String getCommState() Read-only value of your GEM Communication State.  Possible values are DISABLED, ENABLED {NOT COMMUNICATING}, and COMMUNICATING.   The StateChange event is used to obtain asynchronous notification of this property value change.
int getConnectionType() 
void setConnectionType(int v) throws Exception
Configures the basic choice of connection type.   The value 0 means SECS-I RS-232, 1 means SECS-I terminal server, 1993 is for non-standard Draft HSMS, 1995 is for standard HSMS.  The default is 1995.  We suggest you use the connectType* methods to set the connection type rather than manipulating the properties directly.  An exception is thrown if an inappropriate value is set.
String getControlState() A read-only value of the GEM Control State.  Possible values are OFF-LINE and ON-LINE.
int getDEVID()
void setDEVID(int DEVID) throws Exception
The SECS Device ID.  An identifier imbedded in SECS header data usually left at the default of 0.  The SecsHost software has adaptive logic to correct an improper value.  Settable range is 0..32767.
static DMHClientItf SecsConn.getDmh() SecsHost instances use a shared connection to the DMH message system in order to communicate with the SECS server process.  The connection instance is available in case you want to access it in your application.
static String SecsConn.getDmhGroupName() The DMH message system groupname used by the SECS server.  The same groupname should be specified to the constructor of every SecsHost instance in the application in order to share the same SECS server process.
String getHsmsHost() 
void setHsmsHost(String hostOrIpAddr)
For an active HSMS connection, specifies the TCP/IP hostname or IP address of the equipment computer.  The default value is "localhost".
boolean getHsmsPassive() 
void setHsmsPassive(boolean passive)
For an HSMS connection, whether the SecsHost plays the passive, TCP/IP server role.  The default value is false since the usual role for the host is non-passive. 
int getHsmsPort() 
void setHsmsPort(int p)
For an HSMS connection, the TCP/IP socket port number.  Defaults to 5555.
public static java.util.Hashtable<String,SecsHost> instances There is a hashtable SecsHost.instances which is used to keep track of the existing SecsHost instances.  The key values are the Name properties.
boolean isMult() 
void setMult(boolean multipleReplies)
A flag used only for SECS-I to specify whether the equipment can handle owing more than one reply at a time.  The default value is true.
String getName() The SecsHost name passed to the constructor and used in the SECS server process as a Tcl command name, a global array name, and an identifier in SQL table records.

boolean isPPbodyFileMode()

void setPPbodyFileMode(boolean isFileMode)
This boolean property controls whether S7F3 and S7F6 process program transfer messages are handled by direct data transfers to and from files bypassing handling the messages in memory.  This avoids possibly large memory allocations and enables transferring process programs that are as large as the 16 meg limit of Stream 7.   Setting the option also reduces the data that is seen by tracing and logging - only summary information can be seen in the diagnostics.  The default value is false.  It is recommended to set the option true if process programs sizes are as large as 1 meg.  The mode is transparent to the Java application; the processProgramDownload and Upload methods work the same and the built-in SECS Server Stream 7 receiving with ValueChange notifications work the same irrespective of the PPbodyFileMode setting.
String getProcessProgramDir()
void setProcessProgramDir(String path)
A pathname to the file system directory where Process Program files are located.  The default value is the relative subdirectory  "<Name>_recipes" of the directory where the SECS server is executing.  Note that by default, each interface has its own directory for Process Program files.  Reading this property returns the absolute directory path to the process program directory.  The value can be set using a relative or absolute pathname.

boolean areReportsCleared()
void setReportsClear(boolean Clear)
This boolean property controls 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. The default is false. 

boolean areReportsEnabled()
void setReportsEnable()
Setting this boolean property true insures 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 meaning of the property is to  insure that all equipment based events are enabled, and the false value is not used for disabling event reports.  The default value is true.
int getRTY()
void setRTY(int v) throws Exception
SECS-I maximum send retry, range 0..31, default 3
String getSerialPort() 
void setSerialPort(String SerialPort)
For a SECS-I connection, the serial port device such as "COM1".  The default value is "COM1" on all platforms.  POSIX platforms typically need a device name such as "/dev/ttyS0". 
String getSpoolInit()
void setSpoolInit(String v) throws Exception
Controls initialization of the equipment spooling of messages.  The allowed values are PURGE, UNLOAD, or IGNORE.  The default value is IGNORE.
String getState() A read-only value of the low-level connection state.  Possible values include OFFLINE, LISTENING, and COMMUNICATING.  You will see the OFFLINE state if the connection to the host is broken, or in the case of SECS-I implicitly broken by a conversation timeout.  The StateChange event is used to obtain asynchronous notification of this property value change.
int getT1()
void setT1(int v) throws Exception
SECS-I Inter-Character Timeout in milliseconds, range 100..10000, default 500
int getT2()
void setT2(int v) throws Exception
SECS-I Protocol Timeout in milliseconds, range 200..25000, default 10000
int getT3()
void setT3(int v) throws Exception
SECS Reply Timeout in milliseconds, range 1000..120000, default 45000
int getT4()
void setT4(int v) throws Exception
SECS-I Inter-Block Timeout in milliseconds, range 1000..120000, default 45000
int getT5()
void setT5(int v) throws Exception
HSMS Connect Separation Timeout - the delay between re-connection attempts in milliseconds, range 1000..240000, default 10000.  The T5 timer value is also used for SECS-I host logic as a retry timer for communication attempts.
int getT6()
void setT6(int v) throws Exception
HSMS Control Transaction Timeout in milliseconds, range 1000..240000, default 5000
int getT7()
void setT7(int v) throws Exception
HSMS Not Selected Timeout in milliseconds, range 1000..24000, default 10000
int getT8()
void setT8(int v)
HSMS Network Intercharacter Timeout, default value 5000.  This value is not used.
 int getTraceBits() 
void setTraceBits(int traceBits)
Used as a bitfield to control diagnostic trace information for SECS port activity which is passed to the application in the SecsTrace event.  By setting specific bits, the corresponding output is turned on. 

General Tracing: (TraceType = trace) 
Bit        Output Description 
0x0001     Read and write calls
0x0002     state changes including connection attempts 

Receive Tracing: (TraceType = rtrace) 
Bit        Description for Received Messages 
0x0100     Header binary dump 
0x0200     Header interpretation 
0x0400     Stream and Function description
0x0800     Message data binary dump 
0x0004     The Message as TSN 

Send Tracing: (TraceType = strace) 
Bit        Description for Sent Messages 
0x1000     Header binary dump
0x2000     Header interpretation
0x4000     Stream and Function description
0x8000     Message data binary dump
0x0008     The Message as TSN

int getTraceLogMaxWidth()
void setTraceLogMaxWidth(int ctChars) throws Exception
This property allows setting an approximate maximum number of characters in text lines when saving Trace data to log files.  Lines that are longer than the maximum are trimmed and a short explanation message is appended.  The property helps you reduce the size of the log files when large Process Programs are transferred or other long data messages are logged.  The value may be configured as 0 for no limit, or a value greater than or equal to 1000; the default is 4000.
RcResult setTraceSaving(boolean save, boolean compress, int maxDayFiles, String saveDir, String zipCmd)

public class RcResult {
   int rc;   // return code
   String result;
   }

boolean isTraceDataSaved()

boolean isTraceDataCompressed()

String getTraceSaveDir()

int getTraceSaveMaxDayFiles()

String getTraceSaveZipCmd()

The toolset software has the configurable feature of continuously saving the SECS communication trace data to files - one file per day, up to a maximum number per year, and optionally compressing the closed file from the previous day shortly after midnight.  The setTraceSaving method is used to reconfigure the logging feature with the various properties being set atomically in one call. The saving logic writes each day's output to a distinct file, in the directory named by the saveDir argument.  The maxDayFiles argument controls how many day files are saved per year.  It can be configured between 1 and 366.  When file saving is initiated, the output filename is set to traceNNN.txt where the NNN value is the current day of the year, 0 to 365, modulo the maxDayFiles value.  If this file already exists and has been written to earlier in the same day, then the output is appended to it, otherwise the file is created as a new file. Note that if the maxDayFiles value is set to 1, each day's output is saved to the same filename, trace000.txt.  The default values provide for saving the data from each connection in a separate directory.  Separate directories are required for each connection.  When trace data is being written, the compress argument controls whether the logic attempts to compress the output file when it is closed at the end of the day (midnight).  For compression to occur, the maxDayFiles value must be greater than 1 and a non-blank compression command must exist as the zipCmd argument.  The default assignment of zipCmd is similar to zip -m tracetxt.zip. This command causes the data file from the previous day to be moved into the tracetxt.zip archive, creating the archive if it does not exist.   The compression logic appends the day file name to the configured command before execution.  Only trusted persons should be allowed to configure the compression command because of the security considerations. 

The RcResult return value is used as follows.  If the rc value is less than 0 the setTraceSaving() arguments were not acceptable and an error message is provided as the result String.  If the rc value is 0, the call succeeded.  If the rc value is greater than 0, the call succeeded with an advisory message as the result String.  For example, a message occurs if compression is set true but there is a maximum of only 1 file, so there is no distinct file for the previous day to compress.

int getTracewinMaxWidth()
void setTracewinMaxWidth(int ctChars) throws Exception
The approximate maximum number of characters to display in a single line of the trace window.  This value guards against excessive data use when long messages such as recipe transfer occur and the trace window is displaying connection activity.  Range 1000..120000, default 4000.
String gettDATAID() 
void settDATAID(String tsntype) throws Exception
The SECS TSN type code for DATAID items.  Defaults to U4.
String gettDATALENGTH()
void settDATALENGTH(String t) throws Exception
The SECS TSN type code for DATALENGTH items.  Defaults to U4.
String gettLENGTH() 
void settLENGTH(String tsntype) throws Exception
The SECS TSN type code for LENGTH items.  Defaults to U4.
String gettPPID() 
void settPPID(String tsntype) throws Exception 
The SECS TSN type code for PPID items.  Defaults to A.
String gettREPGSZ() 
void settREPGSZ(String tsntype) throws Exception
The SECS TSN type code for REPGSZ items.  Defaults to U4.
String gettRPTID() 
void settRPTID(String tsntype) throws Exception
The SECS TSN type code for RPTID items.  Defaults to U4.
String gettTOTSMP() 
void settTOTSMP(String tsntype) throws Exception
The SECS TSN type code for TOTSMP items.  Defaults to U4.
String gettTRID() 
void settTRID(String tsntype) throws Exception
The SECS TSN type code for TRID items.  Defaults to A.
boolean isS1F3InUse() 
void setS1F3InUse(boolean b)
Whether to use the Stream 1, Function 13 (S1F3) message type during initialization to query Status Variable values. After initialization, subsequent value changes are ordinarily known to the host by being received in event reports. The default value is true.
boolean isS1F11InUse() 
void setS1F11InUse(boolean b)
Whether to use S1F11 during initialization to determine Status Variables.  Since the set of variables does not ordinarily change, and can be loaded from saved data, the initialization query can be disabled if it is time consuming.  The default value is true.
boolean isS1F13InUse() 
void setS1F13InUse(boolean b)
Whether to use S1F13 during initialization to establish communications.  The default value is true, 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.
boolean isS1F17InUse() 
void setS1F17InUse(boolean b)
Whether to use S1F17 during initialization to request the Online Control State.  The default value is true.
boolean isS2F13InUse() 
void setS2F13InUse(boolean b)
Whether to use S2F13 during initialization to query Equipment Constant values.  The default value is true.
boolean isS2F29InUse() 
void setS2F29InUse(boolean b)
Whether to use S2F29 during initialization to determine Equipment Constants.  The default value is true.  Since the set of constants does not ordinarily change, and can be loaded from saved data, the initialization query can be disabled if it is time consuming.
boolean isS2F31InUse()
void setS2F31InUse(boolean b)
Whether to use S2F31 during initialization to synchronize the equipment clock.  The default value is true.
boolean isS5F5InUse() 
void setS5F5InUse(boolean b)
Whether to use S5F5 during initialization to determine Alarm types.  The default value is true.  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.
boolean isS5F7InUse() 
void setS5F7InUse(boolean b)
Whether to use S5F7 during initialization to determine enabled Alarms.  The default value is true.
boolean isS13InUse() 
void setS13InUse(boolean b)
This boolean property chooses whether to enable using Stream 13 large process program transfer message types.  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.


 
SecsHost Events
Event Handler and Argument Data  Description


All event handlers - NOTES
 
 
 
 
 

 

Java supports callback functions through the use of interface declarations.  You declare a class as implementing a particular interface type.  Then you are able to pass references to instances as arguments to indicate the object which should be notified by the callback.  If this is new to you, take a close look at our example application code.

The Interfaces we use are declared in separate java files, each named for the Interface type name, in the com.hume.SECS directory.  We have adopted the convention of appending Itf to interface type names to make it easy to identify which files contain interface declarations. 

Unless noted otherwise, you should assume that the callback method is executed by a different thread than the main GUI thread of your application.  See the notes on threading in the Development section above. 

When the event happens, your callback interface method is called. 


public interface AlarmReportItf {
   public void alarmReport(SecsHost sh, String alid, boolean is_set, String altx, String clock);
   }

public AlarmReportItf AlarmReportHandler;

 

Set the AlarmReportHandler variable value to your application object to receive Alarm Reports.

This event is raised upon receiving an S5F1 alarm report message.  Modern GEM equipment posts events for alarm set and alarm clear conditions so the idea of alarms as distinct from events is becoming obsolete.

public interface EventReportItf {
   public void eventReport(SecsHost sh, String CEID, String EventID, java.util.HashMap<String,String> dataItems);
   }

public EventReportItf EventReportHandler=null;

Set the EventReportHandler variable value to your application object to receive Event Reports based on SECS messages S6F11, S6F13, Trace Reports (S6F1), and various events synthesized by the software such as COM_DISABLE.

Use the eventReportDefine method to create data collection event reports.  Your application needs to call the initialize method after defining the desired event reports to setup and enable the desired event reports with the equipment. 

Events can be given meaningful names and descriptions using the eventUpdate method.  In the event report data, you receive both the underlying event identifier sent by the equipment, the CEID value, and the identifier for the event you have optionally customized, the EventID.  If you have not provided a custom name for an event type, the EventID default value is the same as the CEID value.   The data of the event report is passed as a HashMap instance which contains variable name and value pairs.  The variable names are from the VFEIname column of the SECS server ei_variable table.  You are able to assign your own variable names using the variableUpdate method.  Using host specified names for variables allows the logic to ensure that each name is unique, and provides for uniform naming across equipment instances.  If you do not provide your own name values for variables, the default variable names are assigned using the naming conventions of the Sematech Virtual Factory Equipment Interface (VFEI) standard.  The ability to rename events and variables is referred to as Virtual Reporting.

The default names for variables are computed as follows.  The variable names defined by the equipment are folded to uppercase, with white space and non-alphanumeric letters being replaced by underscores.  Hyphens are not changed. An underscore is inserted for each  transition from lowercase to uppercase in the equipment provided name.  If the computed name is not unique for the equipment instance, the name is made unique by concatenating an underscore and the variable ID.  For example, the equipment variable name PPExecName is assigned the default name PP_EXEC_NAME.  The following 8 computed names are exceptions to the naming algorithm and are reassigned based on the Sematech VFEI standard: 
ESTABLISH_COMMUNICATONS_TIMEOUT becomes COM_TIMER, 
MDLN becomes EQ_MODEL_ID, 
PREVIOUS_PROCESS_STATE becomes PREV_PROC_STATE, SOFTREV becomes EQ_SOFT_VER, 
MID becomes MATERIAL_ID, 
CMD becomes CMD_VAR, 
TID becomes TID_VAR, and 
MTY becomes MTY_VAR.

public interface SecsMessageReceiveItf {
   public void secsMessageReceive(SecsConn sp, 
     int stream, int func, boolean sendReply, int transactionID, 
     String data, String header);
   }
See the messageTypeAdd method described in the next section to see how to receive SECS messages in your application.
public interface SecsTraceItf {
   public void secsTrace(SecsConn sp, String traceType, String text);
   }

SecsTraceItf onSecsTrace(SecsTraceItf handler)

This event provides you with the detailed information of SECS message traffic that is viewed in the SECS Trace window - see the traceWin method.  The flow of  information is controlled by setting the TraceBits property.  You can cast the SecsConn argument to a SecsHost if you want to use a method that is defined by the SecsHost class and not the SecsConn base class.

Use the onSecsTrace() method to set your own handler.  The return value is the previous handler which you are replacing.

public interface ServerErrorItf {
   public void serverError(String message);
   }

ServerErrorItf onServerError(ServerErrorItf handler)

The SecsConn class reports Tcl programming errors that are trapped in the SECS Server process as ServerError events.  An example would be trying to send an improperly formatted SECS message.  These error events will happen during development but should be rare once the code is debugged.

In addition, there are optional debugging messages available to troubleshoot the initial connection to the SECS Server background process at startup.  When the first SECS connection instance is instantiated, a SECS Server background process is started, and the application is usually able to setup DMH communication with the SECS Server within a few seconds. In an uncommon situation such as computer system that is running low on resources, the connection setup may require more time.  The timing and retry logic is optionally affected by defining and setting the following environment variables:

DMH_CONNECT_DEBUG=1    Define and set this environment variable to 1 to obtain connection debug events.   Debug events provide diagnostic messages for each connection attempt.  They show the timing and the error messages of failed attempts. 

DMH_CONNECT_WAIT=milliseconds    This variable can be defined and set to the desired number of milliseconds of waiting per connection attempt.  The default is 500.  The value may be set from 1 to 60000.

DMH_CONNECT_RETRY=maxAttempts    This environment variable can be defined and set to the desired maximum number of communication attempts.  The default is 20.  The value may be set from 1 to 100.

See the dmhConnect method coded in the SecsConn.java file for more details.  Note that the DMH_CONNECT_* environment variables can be defined and set on a deployed system to affect the startup timing  without making code changes, and without having coded an error event handler.  This is a new feature of the software as of January 2016.

Use the onServerError() method to set your own handler.  The return value is the previous handler which you are replacing.

public interface ValueChangeItf {
   public void valueChange(SecsConn sp, String name, String newvalue);
   }

ValueChangeItf onStateChange(ValueChangeItf handler)

This event notifies your application of state value changes. Possible varname values include 
  • state - the State property value changed
  • comm_state - the CommState property value changed
  • control_state - the ControlState property value changed
  • dataset_delete - a process program has been replaced with a newly received one.  Stream 13 messages were used for the transfer.  The newvalue argument is the ppid.
  • dataset_download - a process program was downloaded to the equipment using Stream 13 messages.  This event happens when the S7F29 length verification message is received with the correct length specified.
  • dataset_upload - a process program was received using Stream 13 transfer messages.   Proper GEM equipment will also post an UploadSuccess event.
  • recipe_delete - a process program was replaced with an uploaded version using Stream 7 messages.
  • recipe_download - a process program was downloaded to the equipment using Stream 7 messsages.
  • recipe_upload - a process program was received from the equipment using Stream 7 messages.
Your application gets notified of the initial values of these items when the SecsHost connection type is initialized.  With the recipe_* events, the newvalue string is the process program identifier (ppid).

Use the onStateChange() method to set your own handler.  The return value is the previous handler which you are replacing.

SecsHost Methods
METHOD DESCRIPTION
General Comments
 
 

 

The SecsHost class extends the SecsConn class.  Public methods of both classes are shown here for convenience. 

The TclList class is documented with the Hume Java classes for DMH communication.

RcResult alarmAdd(String ALID, String ALTX, String ID_TSN)

public class RcResult {
   int rc;   // return code
   String result;
   }

This method is used to manually add alarm definitions for equipment that does not support discovery of alarm types using S5F5.  The ALID argument value is the alarm type identifier which is usually an integer.  The ALTX argument is static text for the alarm description and it is limited to 40 characters in length.  The ID_TSN argument is the SECS item data type for the ALID in TSN notation such as U4. 

If the method succeeds, the rc field in the result structure is set to 0. It is not an error if the alarm definition already exists, the argument values are used to update the existing definition.  A non-zero result indicates an error, and the result string should be examined.  Possible error return codes include:
-2  invalid ALID
-3  invalid ALTX value 
-4  an error occured using the ID_TSN value to format the ALID value as a SECS data item
-9  unexpected SQL error

void alarmEnable(String ALID, boolean is_enabled) Enable or disable reporting of an Alarm type (S5F1).
boolean alarmIsEnabled(String ALID) Test if the reporting of an alarm type is enabled 
boolean alarmIsSet(String ALID) Test if the alarmed state is currently set
HubTableModel alarmTable() This method returns current data from the SECS Server ei_alarm table for the SecsHost instance.  The columns of the table include: spname, ALID, is_enabled, is_set, ALTX, host_managed, and host_wants_enabled.  The HubTableModel extends the Java swing AbstractTableModel and includes a refresh() method.  It can easily be displayed in a JTable.
int binToInt(String binValue)

 

Converts a SECS B (Binary  - Semi "10") data value usually formatted as a hexadecimal string to an integer value.
void commDisable() Disable SECS communication.  The SecsHost is initialized without communication enabled so using this method only makes sense after CommEnable has been called.
RcResult commEnable()

public class RcResult {
   int rc;   // return code
   String result;
   }

Enables SECS communication.  The CommState property value will change and StateChange events will be received.  These changes are the asynchronous indications for success or failure to establish communication.  You may want to display the trace window  in order to see detailed information on the status of communication attempts.  If there is an error setting up the connection, the return code value will be non-zero, and the result field will be an error message.
RcResult connectTypeHsmsActive(String host_or_ip, int port) This method is an alternative to setting the underlying property values to specify an active HSMS connection type, and calling connectTypeSet().
RcResult connectTypeHsmsPassive(int port) This method is an alternative to setting the underlying property values to specify a passive HSMS connection type, and calling connectTypeSet().
RcResult connectTypeSerial(String comDevice, int baudrate) This method is an alternative to setting the underlying property values to specify a SECS-I connection type, and calling connectTypeSet().
RcResult connectTypeSet()

public class RcResult {
   int rc;   // return code
   String result;
   }

This method is called to use the current property values and initialize a SECS interface for the indicated connection type.  It is called by the connectType<Type> methods.  If you are setting connection property data directly, call this method after your property values are set.  The method returns the value 0 to indicate success.  If communication is enabled when this method is called, it becomes disabled as a result of setting up the new connection.  If the return code value is not 0, then an error message is provided in the result field.
RcResult connectTypeTerminalServer(String host_or_ip, int port) This method is an alternative to setting the underlying property values to specify a SECS-I connection type over a TCP/IP terminal server connection and calling connectTypeSet().
void controlStateOffline() This method sends a S1F15R message to request the offline control state. 
int controlStateOnline() This method sends a S1F17R message to request the online control state.  If the return value is 0 or 2 the online state is indicated.
void copy(SecsHost dest) This method copies the configurable SecsHost property values to another instance.
String copyAll(SecsHost dest) This method calls copy() to copy the current property values to another instance, and it also copies table records of events, event reports, alarms, variables, etc in the SECS Server to the destination instance.  The return value is a String formatted as a list of two integers - the total number of table rows found, and the number of rows copied.  In normal circumstances, the two values are equal.
void debugDMHStatus(boolean show) This method causes the DMH message system status window to either be shown or dismissed.
void debugInspect() This method can be used to exec the Inspect introspection debugger if the Datahub SDK has been installed..
void debugTableWindow(boolean show) This method causes the Datahub table management GUI to be shown or dismissed.
void debugTclConsole(boolean show) This method causes a console window for the SECS Server to be shown or dismissed.
void debugTraceWindow(boolean show) This method is used to display a window which updates to show SECS message traffic and state information for the connection.   There are menu options to control the data displayed, and menu actions to save the displayed data to the file system.  This method invokes the Tcl version of the Trace window which is created by the SECS Server process. See the traceWin method to instantiate a native Java window with similar function.  Making the Java version available in your application is desirable to help diagnose communication problems. 
void delete() Java will not delete and finalize a SecsHost instance automatically because a reference to each instance is kept in the static instances hashtable.  So we have provided a delete method that should be called when an instance is no longer needed.  The delete method disables communication as well as deleting data structures and resources used by the instance.
 RcResult eventAdd(String CEID, String ID_TSN, String eventName, String description)
 

public class RcResult {
   int rc;   // return code
   String result;
   }

This method is used to manually add event definitions for equipment that does not support discovery of event types.  The CEID argument value is the event type identifier which is usually an integer.  The ID_TSN argument is the SECS item data type for the CEID in TSN notation such as U4.  The eventName argument is a virtual name for the event type defined by the user.  The desciption argument can be used to provide guidance in selection lists.  If any of the arguments ID_TSN, eventName, or desciption are provided as null or empty strings, then default values are used:  U4 for ID_TSN, and the CEID value as a string for the eventName.

If the method succeeds, the rc field in the result structure is set to 0.  No error occurs if an event definition with the same CEID already exists - the other fields are updated per the call arguments.  A non-zero result indicates an error, and the result string should be examined.  Possible error return codes include:
-2  invalid CEID
-3  invalid eventName value 
-4  an error occured using the ID_TSN value to format the CEID value as a SECS data item
-9  unexpected SQL error

String [] eventChoice() This method returns an array of {CEID EventName Description) String values of event types that do not currently have an associated event report.  The method is used to help implement the GUI feature of new report creation.
Equipment Constant Update see parameterUpdate Equipment Constant is a misnomer.
int eventDiscovery() The SECS-II standard does not provide a way to discover equipment events.  This method is called to attempt event discovery by enabling all events and asking the equipment which events are enabled.  This technique requires that the equipment support the underlying message types and implements an EventsEnabled variable that has the expected name.  A positive return value indicates the number of new event types discovered.  Negative return values indicate various failure modes.
int eventsEnable()
int eventsEnable(String CEIDlist, boolean is_enabled)
Called with no arguments, eventsEnable requests that the equipment enable all event reports.  By providing arguments, you can request the enabling or disabling of selected events.  The SecsHost automatically enables the reporting of events for which you have configured event reports during online initialization.   A negative return value indicates an unexpected internal error.  The value 0 means success, and 1 means at least one of the events does not exist.
boolean eventIsHostEnabled(String CEID) Test if reporting of an event type has been configured in the SecsHost software to be enabled during the initialization logic.
boolean eventIsReported(String CEID) Test if the reporting of an event is currently established with the equipment.
String [] eventReportConfig(String virtualName)

This method returns a four element String array for the configuration of an event report.  The elements are CEID, virtualName, Description, and Variables.  Use TclList.split() to split the Variables element into a String array of the individual virtual variable names.  A null is returned in case of error. 

Use the ReportModel class of the example application for a table of the existing EventReport configurations. 

public String[] eventReportConfigEx(String virtualName) This method returns a five element String array for the configuration of an event report.  The elements are CEID, virtualName, Description, Variables, and RPTID.  Use TclList.split() to split the Variables element into a String array of the individual virtual variable names.  The RPTID value is an empty string if there is no SECS Report ID associated with the event or if the associated RPTID is the same as the CEID.  A null is returned in case of error.

Use the ReportModel class of the example application for a table of the existing EventReport configurations. 

int eventReportDefine(String eventName, String [] varNames)

int eventReportDefine(String eventName, String [] varNames, String secsRptID)
Create or update an event report configuration. 

An event report is a set of variable values that is sent from the tool using S6F11 or S6F13 when the tool control state is online and a particular event occurs. This method configures SECS server table data that represents a desired report, data that links the specified event to the report, and data that indicates that the event should be enabled for reporting. The desired configuration of event reporting is communicated to the tool using S2F33, S2F35, and S2F37 when the initialize method is called, or whenever the tool enters an online control state and automatic initialization is enabled.

The eventName argument is the virtual name of the event which can be configured to be different than the CEID value by using the eventUpdate method.  The varNames argument is an array of the virtual names of the variables whose values are to be reported when the event occurs.  The method variableChoice provides a current list of virtual variable names.  You can use the variableUpdate method to provide your own virtual variable names.  The default virtual variable names are assigned per the conventions of Sematech as explained in the EventReport Event section above

After calling this method, you may want to call the initialize method to have your desired event reports setup immediately and enabled with the equipment. The initialization logic is executed automatically whenever an online control state is established if the AutoInit property is true.

For a less complex application, you may wish to define a distinct event report for each equipment event type that you wish to receive in the application. With the simplest form of this method call, you do not specify the optional SECS Report ID (RPTID) value, and by default the logic creates a distinct event report using the CEID value as the underlying RPTID value.

It is possible to apply a single call to this method to more than one tool event by assigning the same virtual event name value to multiple tool events. The virtual event name value is assigned using the eventUpdate method. When this event naming trick is used and the SECS RPTID value is not specified, the like named events are configured to have separate and equal report definitions using their CEID values for RPTID values.

The SECS Report ID (RPTID) value needs to be specified for certain less capable equipment that are not able to use the CEID values for RPTID values. There is at least one tool type that only allows RPTID values from 1 to 255 (type U1) but has CEID values outside of this range. Specifying the RPTID value can also be useful to apply a single event report definition to more than one event type. If this is done, the latest update of the event report definition is applied to all of the events that are associated (linked) to the specified RPTID. So specifying a common RPTID can be used to reduce the editing needed to manage and update a set of similar event types.

A knowledgeable user can skip using this API and use SECS messages directly to fully exploit the ability to re-use event report definitions with multiple tool events and to have more than one event report definition linked to a tool event. This API only configures 1 or 0 event reports per tool event.

The method returns 0 for success, -1 if the eventName is not known, -2 if a variable is not known, or -3 if the specified or defaulted RPTID value is not compatible with the tRPTID property.

void eventReportDelete(String eventName) Delete an event report configuration.
String eventUpdate(String CEID, String eventName, String description) Assign or update the virtual event name and description for an event type.  Per the SECS-II standard, events use integer values for identifiers.  There is no standardization of values.  You are able to provide meaningful names and descriptions for events.  You can use this feature to great advantage and create virtual equipment drivers with standard event and variable names.  If the description value is passed as null, the current value for the event is not changed.
int initialize() Performs online initialization which enables communication and sets up event reports.  Initialization is controlled by your settings of property values, and configured items.  It optionally includes:
  • establishing communications if not already established
  • requesting the equipment go online if the online control state is not already established
  • querying the status of alarms and variables if being online is new
  • synching the equipment clock
  • setting equipment constant values for the ones that you have configured persistent values
  • setting up event reports per your configuration
  • enabling all events if you do not have any configured equipment based event reports so you can capture the event definitions needed for event reports
  • unloading, purging, or ignoring the spool
By default this initialization is attempted automatically whenever an online control state is established.  The AutoInit property is used to disable automatic initialization.

The return value is 0 for success.  Error return values include:  -1 TIMEOUT, 1 communication failed, 2 not online, 3 clock set, 4 setting of Eq. Constants, 5 disabling of events & reports, 6 event & report enabling, 7 alarm management, 8 Spool init, or ei_custom_init error.

static String SecsConn.listElement(String s, int index)
static String SecsConn.listElement(String s, int i, int j)
static String SecsConn.listElement(String s, int i, int j, int k)
A convenience method to use the TclList class to parse text structured as a list for a specified element, or to parse a nested list for an element. Indexing starts from 0. The method does not throw an exception; an empty value is returned if the text is not a valid list or if an index is out of range.
static String SecsConn.listJoin(String[] list)
A convenience method to convert a string array to a list. The implementation uses the ListBuilder class.
static String[] SecsConn.listSplit(String s)
A convenience method to split text that is structured as a list into an array of elements. The method returns an empty list instead of throwing an exception if the input text is not a valid list.
void messageTypeAdd(int stream, int function, SecsMessageReceiveItf callback)

public interface SecsMessageReceiveItf {
   public void secsMessageReceive(SecsConn sp, 
     int stream, int function, boolean sendReply, int transactionID, 
     String data, String header);
   }

Call messageTypeAdd() to have SECS messages processed by your custom handler methods when the SecsHost has established communication with the equipment.  The callback argument specifies your application object that implements the SecsMessageReceiveItf interface.  You can provide for new SECS message types, or you can replace the built-in handling of particular messages.  For example, you could take over the handling of S6F3 discrete data reports for equipment that uses non-standard formats.  Use the sendReply, sendS9, and sendAbort methods to send reply messages.

The arguments passed to your SecsMessageReceive method are:
sp a reference to the SecsConn instance.  You can cast this to a SecsHost since SecsHost extends the SecsConn class.  stream and function - these are the message type identifiers of SECS, sendReply - a boolean flag which is true if you are supposed to send a reply message. transactionID - an integer value which identifies the specific message instance and is needed to send a matching reply message. data - the message data formatted as a TSN string.  Use the TclList.split or similar methods to parse it.  header - a TSN representation of the message header bytes which is only used to send a Stream 9 error message using the sendS9 method.

void messageTypeRemove(int stream, int function) This method is used to cancel SECS message handlers that you have setup using messageTypeAdd() or to cancel the handling of particular messages by the built-in SecsHost logic.  If you have called messageTypeAdd for the specified message type, the Add is cancelled.  If you have not called messageTypeAdd, the SECS server is told not to handle the message. Unhandled primary messages are replied to with an abort reply.
RcResult parameterAdd(String varID, String ID_TSN, String value_TSN, String varName, String virtualName, String description)

public class RcResult {
   int rc;   // return code
   String result;
   }

This method is used to manually add parameter (ECV) definitions for equipment that does not support discovery of them using S2F29.  The varID argument value is the parameter identifier which is usually an integer.  The ID_TSN argument is the SECS item data type for the varID in TSN notation such as U4.  The value_TSN argument is the data type of the parameter value in TSN notation such as "F4".  The varName argument is a name for the parameter as defined by the equipment.  The virtualName argument is a name for the parameter chosen by the user.  The desciption argument can be used to provide guidance in selection lists.  If any of the arguments ID_TSN, varName, virtualName, or desciption are provided as null or empty strings, then default values are used:  U4 for ID_TSN,  the varID value as a string for the varName, and programmatic mapping of the varName value for the virtualName.

If the method succeeds, the rc field in the result structure is set to 0.  No error occurs if a definition with the same ID already exists - the other fields are updated per the call arguments.  A non-zero result indicates an error, and the result string should be examined.  Possible error return codes include:
-2  invalid varID
-3  invalid varName value 
-4  an error occured using the ID_TSN value to format the varID value as a SECS data item
-5 an error occured using the value_TSN value to format an example value
-9  unexpected SQL error

RcResult parameterUpdate(String varID, String newValue)

public class RcResult {
   int rc;   // return code
   String result;
   }

Use this method to set the value of an Equipment Constant.  The return value is 0 for success, -1 and an error message if improper data is used, 1 if the variable does not exist, 2 if the equipment refuses to change the value at present, and 3 if the equipment rejects the new value. 
String [] processProgramList() Obtain the current list of process programs using S7F19R.  The return value is null in case of error such as the equipment not being online or not supporting S7F19.
RcResult processProgramDownload(String pathname)

public class RcResult {
   int rc;   // return code
   String result;
   }

Download a process program to the equipment using Stream 7 messages.  The process program must be in the process program directory.  If there is no saved table record in file ei_ppid.tab describing the process program file, the logic assumes that the file format contains both the PPID and PPBODY in text TSN notation which was the upload format used prior to May 2008.  The return value of the method call is a two element structure, a return code and text.  The return code is 0 for success, in which case the text will be the PPID (the process program name).  Possible error codes include:
-1 unexpected transaction error
-2 file not found
-6 SECS transaction error
-10 file open or read error
-11  no upload description data and the file data is not consistent with the older upload format
RcResult processProgramLargeRequest(String ppid) This method initiates the upload of a process program to the host using the message types of Stream 13 which are designed for large data set transfers.  Using these messages is more complex than the usual Stream 7 transfer messages so they are less commonly supported.  The ppid argument value is the process program identifier used by the equipment.  The upload logic saves only the data passed as the body of the process program in the uploaded file.  The ppid value used to identify the process program may not be a valid filename.  The upload logic assigns a unique filename to the uploaded program, using the ppid value if possible.  The logic also creates or updates a file of SQL statements, ei_ppid.tab, in the process program directory.  The ei_ppid.tab file saves the ppid value to filename mapping, as well as the datatype of the transferred program.  The ei_ppid.tab file has to be preserved along with the uploaded process programs in order to download them in the future.

The return value is a two element structure, a return code and text.  The return code is 0 if the transfer is initiated successfully as determined by the reply to S7F41.  The transfer is not complete when the method returns.   The large data set transfer logic receives the file in the subdirectory, dataset_transfer, of the directory set by the ProcessProgramDir property.  When the transfer is complete, if there is already an earlier version of the process program file in the process program directory, then there is a StateChange event with the name dataset_delete and the newvalue being the ppid value, which informs you that the earlier version file is being replaced.  Next, there is a StateChange event with the name dataset_upload and the newvalue being the ppid value which informs you of the successful upload completion.  Proper GEM equipment will also post UploadSuccess or UploadFailure data collection event reports to indicate completion as well. 

If the transfer does not complete successfully, there is additional status information is the SECS server table ei_dataset_xfer.   It is possible to query this table or subscribe to data changes of this table to better integrate transfer status information.

Possible error results include values of the ACKC7 reply to S7F41 and the following:
1 permission not granted
4 PPID not found
6 other error
-6  error when sending S7F41 or receiving the S7F42 reply
-14 A large PP receive is already in progress for ppid
-15 Stream 13 transfers are disabled either from configuration or initialization failure
-17 error when parsing the S7F42 reply


RcResult processProgramLargeSend(String filename)
This method initiates the download of a process program to the equipment using the message types of Stream 13 which are designed for large data set transfers.  Using these messages is more complex than the usual Stream 7 transfer messages so they are less commonly supported.  The filename argument value is the file name of a previously uploaded process program in the process program directory.  The file is expected to contain only the data of a process program - this transfer method is not compatible with the previously used upload format that saved both the PPID and PPBODY in TSN notation.  The filename may not be the same as the process program identifier, ppid.  The saved information in the ei_ppid.tab file in the ProcessProgramDir is checked for a possibly different ppid

The return value is a two element structure, a return code and text.  The return code is 0 if the transfer is initiated successfully as determined by the reply to S7F37.  The transfer is not complete when the method returns.  After the data has been sent to the equipment, per GEM, the equipment is expected to verify the byte count of the download process program file using S7F29.  When this verification occurs with the correct byte count, there is a StateChange event with the name dataset_download and the newvalue being the ppid value.   If the transfer does not complete successfully, there is additional status information is the SECS server table ei_dataset_xfer.  

Possible error results include values of the ACKC7 reply to S7F37 and the following:
1 permission not granted
6 other error
-4  PPID filename not found
-6  error when sending S7F37 or receiving the S7F37 reply
-14 A large PP receive is already in progress for ppid
-15 Stream 13 transfers are disabled either from configuration or initialization failure
-17 error when parsing the S7F38 reply
RcResult processProgramUpload(String ppid)

public class RcResult {
   int rc;   // return code
   String result;
   }

Upload a process program from the equipment to our process program directory using Stream 7 messages.  The return value is a two element structure, a return code and text. The return code is 0 for success, in which case the text will be the pathname of the saved program.   The upload logic saves only the data passed as the PPBODY of the process program in the uploaded file.  The PPID value used to identify the process program may not be a valid filename.  The upload logic assigns a unique filename to the uploaded program, using the PPID value if possible.  The logic also creates or updates a file of SQL statements, ei_ppid.tab, in the process program directory.  The ei_ppid.tab file saves the PPID value to filename mapping, as well as the datatype of the transferred program.  The ei_ppid.tab file should be preserved along with the uploaded process programs in order to download them in the future.  A successful upload causes a StateChange event with the name recipe_upload and the newvalue being the ppid value.   If there is a prior version of the uploaded file in the process program directory, there is a StateChange event with the name recipe_delete and the newvalue being the ppid value which occurs before the recipe_upload event.

Possible error codes include
1 improper SECS message data
2 blank ppid in message data
3 unsupported PPBODY data type
4 file system error
-1 unexpected transaction error
-2 upload refused or failed
public static SecsHost newSecsHost() 

void SecsHost(String Name, String dmhGroup)

void SecsHost(String spname, String [] cols, String [] row) 
 

The constructor.  The Name argument becomes the name of a global data item and a Tcl command in the SECS Server process.  It needs to be unique for each SecsHost instance, and not coincide with a keyword in the Tcl programming language.  The default value of Name is similar to host0. The name should be a single alphanumeric token. 

One of the constructor forms accepts property values as String arrays.  This form is used by our example Supervisor application.  Take a look at the source code for the SecsHost to understand the names used for the property values.  Essentially there is a direct mapping of properties to column names in an SQL table, ei_startup, which is used to manage interface startup information.

The dmhGroup argument becomes the DMH message system group name used by the SecsHost and SECS Server process.  If you are instantiating more than one SecsHost  instance in your process, construct each instance using the same dmhGroup name argument so that the SECS Server process is shared.   The groupname chosen needs to be unique among other DMH server instances on the computer where the SecsHost is executing.  The default value is GEMHOST.  This value does not conflict with the default value for Hume Datahub instances which is mbx, or the default value for the GemEqApp which is GEM.  The name should be a single alphanumeric token. 

The  SECS Server process can be debugged remotely by connecting to the DMH mailbox SERVER_RPC@hostname:dmhGroup using the Inspect application or using the DMH mailbox SERVER_SQL@hostname:dmhGroup by the hubclient application.

void sendAbort(int stream, int primaryFunction) This method is used to send an F0 abort message in lieu of a proper reply.  It is used to indicate that the received message is not appropriate in the current context.
void sendReply(int stream, int function, int transactionID)

void sendReply(int stream, int function, int transactionID, String TSN_data)

This method is used by your custom SECS message handling logic to send reply messages either with or without data.  The reply data is formatted as Tcl Secs Notation text.
void sendS9(int function, String header) This method is used to indicate an error condition response to a received message - it is sent in lieu of a normal reply.  You will not receive a message type, unless you register for it.  In general, host software has less of a need to send Stream 9 messages than equipment software.
RcResult sendSecsMsg(int stream, int function, boolean replyIsWanted, String TsnData, boolean wait4reply)

public class RcResult {
   int rc;   // return code
   String result;
   }
 
 
 
 
 

 

These methods are used to send a primary SECS message, optionally indicating a reply is wanted, and optionally indicating that the call should wait for a reply.  A null or empty String value may be used for the TsnData argument when a header only message is to be sent.  If a multiblock enquire/grant transaction is required for the message type, the SecsHost software does it automatically.  The reply value for the sendSecsMsg() method  is a a two element data structure.  The first element is an integer code, and the second element is reply or diagnostic data.  The possible return values are:
-1
errorMessage  - the error message starts with "ERROR" and describes the fault
-2
DISABLED   - communication is disabled so the message could not be sent
-4 
SENDFAILURE   - the send attempt failed.
-5 
BUSY   - an eq_send call is currently active.  You should not see this error, since by design send commands are serialized using DMH messages to the connection's command mailbox.
-8
MULTIBLOCK_REFUSED - You are sending a message type that requires multiblock enquire/grant and the equipment failed to send the code 0 GRANT reply.  Enquire/grant messages by default are not used for HSMS communication, but it is possible to enable them. (Possible with message types S2F33, S2F35, S2F45, S4F19, & S7F3).
SENT_NO_REPLY  - sent successfully no reply requested
SENT_NO_REPLY_WAIT  - sent successfully, a reply was indicated, not waiting for the reply was indicated.  The reply will be ignored when it arrives.
ReplyTsnData   -sent ok, reply requested and received.
-6 
TIMEOUT  - sent ok, reply requested, no reply, T3 timeout. 
-7 
ABORTED  - sent ok, F0 abort reply received.
-9
REJECTED  - sent ok, Stream 9 error message "reply".
static int SecsConn.serverLicenseCheck() This function returns an integer code for the license status when using the SecsServer[.exe].  An  OEM who features SECS/GEM as an option, can test whether a valid license is installed, in which case the return value is 0.  The check does not test or validate running with a Datahub SDK installation.  Return code values are:
-1
SecsServer.exe is not found. An SDK installation is not checked.
0
a valid license is installed
1
no licenses.txt found
2
the licenses.txt file contains improperly formatted data
3
no license code found for the system in the licenses.txt file
4
invalid license code found for the system in the licenses.txt file
static void SecsConn.serverSqlCmd(String sql) Send an SQL command to the SECS Server process without waiting for a reply.  This method is used by the SecsHost software and made public in case of custom requirements.
static String SecsConn.serverSqlReply(String sql) Send an SQL command to the SECS Server process and wait for the reply.  This method is used by the SecsHost software and made public in case of custom requirements.
static void SecsConn.serverTclCmd(String tclCommand); Send a Tcl command to the SECS Server process without waiting for a reply.  This method is used by the software and made public in case of custom requirements.  After a connection instance has been constructed and the connection type set, the tclCmd( ) method should be used instead of this method for commands that are directed to a particular interface instance.  Why?  Doing so serializes the commands for a particular interface, and provides re-entrant execution protection.
static String SecsConn.serverTclReply(String tclCommand); Send a Tcl command to the SECS Server process and wait for the reply message.  This call is used by the SecsHost software and made public in case of custom requirements.  After a connection instance has been constructed and the connection type set, the tclReply( ) method should be used instead of this method for commands that are directed to a particular interface instance.
static int SecsHost.superSave() Save the SECS server table data including interface startup configurations.  You can write your own applications with your own persistence mechanisms.  Our example Supervisor application uses this method to save the state of the configured interfaces for the next session.
static void SecsHost.supervisorStart (String DmhGroup) This method is the startup call for our Supervisor application example.  It restores data from the last SuperSave call, and instantiates all of the configured interfaces.  The interfaces that are configured with autoStart true, are enabled for communication.
void tclCmd(String tcl) This method is used to send Tcl code to the SECS server command mailbox for the connection.  It is used by the SecsHost software and made public to support custom requirements.
RcResult tclReply(String tcl)

public class RcResult {
   int rc;   // return code
   String result;
   }

These methods are used to send Tcl code to the SECS server command mailbox for the connection and wait for the evaluation result.  They are used by the SecsHost software and made public to support custom requirements.  With tclReply() the return value is a structure.  The first element is a return code for the evaluation with 0 meaning success.  The second element is the return value from the executed Tcl code, or an error message if the return code is not 0. 
int traceSetup(String traceId, int periodSeconds, int totalSamples, int samplesPerReport, String SVIDs) Control TRACE Reports - a convenience method to send the S2F23R message.  If totalSamples is 0, the trace is disabled.  If totalSamples is greater than 0, you should insure that it is an even multiple of samplesPerReport.  The reporting period value specified in seconds, periodSeconds, is subject to equipment limitations.  The SVIDs argument is a white space delimited list of Status Variable identifiers.  The return values are 0 = success, 1 = too many SVIDs, 2 = no more traces allowed, 3 = invalid period specified, -1 = error such as not being in online communication, -2 = at least one unknown SVID, -3 at least one variable is not a Status Variable (class SV). 

The method also creates or updates event report configuration data so that the S6F1 trace reports are received as event reports with the CEID of TRACE_REPORT.  When there are multiple samples per report, the event report logic parses the received data into multiple event reports, one per sample.  In this situation you will usually want the CLOCK variable as one of the reported items to know the observation time of the sample.  If you want to have more than one trace report series active at a time, then you can use the messageTypeAdd() method to register for the S6F1 messages and receive them directly without using the virtual event report receiving logic.

void traceWin(boolean show);
void traceWin(boolean show, boolean allowLogging)
The SecsHost is able to instantiate and manage a  window class, Tracewin, which provides a controllable display of the data being exchanged across the SECS interface.  The argument is set to true to display the window, or false to close the window.  There are menu options to provide hex dump formatting of the data, or higher level descriptive formatting.  There are also menu actions to save the displayed data to the file system.  The allowLogging argument controls whether there is a menu item which provides for configuring the continuous unattended saving of trace data to the file system.  Since this feature has performance, disk usage, and security implications you may wish to restrict access to the configuration of logging.
RcResult variableAdd(String varID, String ID_TSN, String varName, String virtualName, String description, String varClass)

public class RcResult {
   int rc;   // return code
   String result;
   }

This method is used to manually add variable definitions for equipment that does not support discovery of them.  The method can also be used to insure that variable definitions exist and reports using them can be defined before initialization logic is executed.  The most common scenario is that initialization logic is run and discovered data is saved by calling superSave() during a prior session, and this method is not used. The varID argument value is the variable identifier which is usually an integer.  The ID_TSN argument is the SECS item data type for the varID in TSN notation such as U4.  The varName argument is a name for the variable as defined by the equipment.  The virtualName argument is a name for the variable chosen by the user.  The virtualName should be unique.  System assigned virtualName values are described above with the EventReport event description.  If both the varName and the virtualName values are set to the varID value, the built-in initialization logic of processing S1F12 will replace the varName and virtualName values with system computed values.  Therefore, provide a different varName value if you wish to use the varID value as the virtualName. The description argument can be used to provide guidance in selection lists.  The varClass argument value is set to "SV" for Status Variables and "DVVAL" for Data Value variables.  If any of the arguments ID_TSN, varName, virtualName, or description are provided as null or empty strings, then default values are used:  U4 for ID_TSN,  the varID value as a string for the varName, and programmatic mapping of the varName value for the virtualName.

If the method succeeds, the rc field in the result structure is set to 0.  No error occurs if a definition with the same ID already exists - the other fields are updated per the call arguments.  A non-zero result indicates an error, and the result string should be examined.  Possible error return codes include:
-2  invalid varID
-3  invalid varClass value 
-4  an error occured using the ID_TSN value to format the varID value as a SECS data item
-9  unexpected SQL error

String [] variableChoice() This method returns a list of variable names which are candidates for use in dynamic Event Report configuration.  The names are the virtualName (VFEIname) values.  A null value is returned in case of error.
String variableGetId(String virtualNames)

String [] variableGetId(String [] virtualNames)

These methods are used to map variable Virtual names assigned by using the variableUpdate method or assigned by default when the variables are first known, to the identifiers used by the equipment.  The latter are typically integer values such as SVID's or ECID's.  If called with a String argument, the virtualNames value may contain 1 or more white space separated names, and the result will be a white space separated list of the corresponding Ids.  An empty result is returned for an unknown name value.  If called with a String array argument, each array element is expected to contain a single name, and a String array result is returned for the corresponding Id values.
HostVariableInfo variableGetInfo(String varID)

public class HostVariableInfo {
  public String varID;
  public String idTsn;
  public String varName;
  public String virtualName;
  public String description;
  public String varClass;
  public String valueTsn;
  public String varMethod;
  public String varValue;
  public String tLatest;
  public String units;
  public String minValue;
  public String maxValue;
  public String defaultValue;
};

This method returns the known configuration and value information of a variable or Equipment Constant Variable (ECV).  A null result is returned for an unknown varID input value.  The information comes from the replies to messages that are sent during the online initialization, from data received in event reports and trace reports, or from the restored table data of a previous session.
String variableGetVirtualName(String Ids)

String [] variableGetVirtualName(String [] Ids)

These methods are used to map variable identifiers which are typically integer values (SVID, ECID, etc) to the Virtual names assigned by using the variableUpdate method or assigned by default when the variables are first known.  If called with a String argument, the Ids value may contain 1 or more white space separated Id values, and the result will be a white space separated list of the corresponding Virtual names.  An empty name result is returned for an unknown Id value.  If called with a String array argument, each array element is expected to contain a single Id, and a String array result is returned for the corresponding Virtual names.
RcResult variableQuery(int varID)
RcResult variableQuery(String varname)
RcResult variableQueryVirtual(String virtualName)

public class RcResult {
   int rc;   // return code
   String result;
   }

These methods are used to obtain the value of a Parameter or Status Variable using the numeric or name identifier.  The varname argument represents the name given the variable by the equipment.   Note that some equipment has the same variable names used more than once.   The variableQueryVirtual method uses the virtual variable name as the argument value which is unique for each variable.  For the methods to succeed, you must be communicating in an online state, and the variables must be known from the replies that are received during online initialization to S1F11 and S2F29.  The variable data can either be discovered during the current session, or known by loading variable data saved from a previous session.

If the method succeeds, the rc field in the result structure is set to 0.   A non-zero rc result indicates an error, and the result string should be examined.  Possible error return codes include:

-1 unexpected error
-2  communication is not enabled
-3 unknown identifier (can occur if initialization queries have not been completed)
-6  no reply TIMEOUT, abort reply, or Stream 9 error reply
DataTable variableTable() This method returns a current subset of the SECS server variable table for the SecsHost instance.  The included columns are varID, varname, VFEIname, description, varclass, value_TSN, varmethod,  varvalue, host_setval, host_managed, and t_latest.
int variableUpdate(String varID, String virtualName, String description) You are able to assign meaningful names and descriptions to the equipment variables using this method.  The virtualName values are used in Event Report configurations and as the variable names in the Event Report event data.  If the description field is passed as a null value, the current description is not changed.

SecsHost Built-in Features


This section of the document has information on the built-in features of the SecsHost software in regards to the SEMI E5 and GEM standards.
 

Built-In Variables and Events

The SecsHost software creates certain variable table records to hold configured property values.  These records are of little interest to the Java developer since they are managed through property value settings.

There is only one other variable record of note.  The AUTO_INIT_RESULT variable exists to save the execution result when the initialization logic executes automatically.  It is common to configure this variable to be part of the event report for the AUTO_VIRT_INIT event.  This dynamic event report can be configured and received even if the underlying equipment does not support dynamic event reports.  The event report is created and managed by the SecsHost software.  There are three other events that are synthesized in the SecsHost software and presented to the application using the same mechanisms used to dispatch equipment based event reports.  Here is a list of the built-in driver events:

AUTO_VIRT_INIT
This event report occurs when the autoInit property is left at its default value of true, and the SecsHost attempts the initialization logic for the virtual reporting system automatically after establishing an online control state with the equipment.  The value of the variable is a two element list.  The first element indicates whether there was a trapped execution error during initialization.  The first element will ordinarily be 0 to indicate that execution proceeded without error.  The second element will be an error message if an execution error was trapped.  In the usual success case, the second element is the return code from the ei_initialize procedure.  The following return values are possible: 0 meaning success, 1 communication failure, 2 request online failed, 3 clock synchronization failed, 4 failed setting equipment constants, 5 failed disabling events, 6 failed enabling events and reports, 7 failed enabling disabling alarms, 8 spool initialization failed.  You can and should edit the properties of your SecsHost so the initialization does not attempt to use message types that your equipment cannot handle.
COM_DISABLE
This event report occurs when communication with the equipment is lost.
COM_ENABLE
This event report occurs when communication with the equipment is established (or re-established).
TRACE_REPORT
The SecsHost logic maps Trace Reports into Event Reports with this event name.  This lets you use common software to capture trace and event reports.

Built-in Handling of SECS Message Types

The E5 standard identifies data items used in message items with all uppercase letters such as CEID.  Typically, the standard allows for different data types to be used for a particular message item.  Historically, the host software has been required to know and use the specific data types that the equipment implements when the standard allows for different data types.  That is why the SecsHost has configurable properties for the data types that the built-in logic uses and that cannot be discovered automatically.  For most message types, the Hume SECS equipment software accepts any data type for a message data item as long as the value is equivalent.  This behavior cannot be assumed for other implementations.  The table below lists the subset of message types where the SecsHost has built-in handling of the message type, or sends the message type as part of its built-in logic.  Other message types can be easily sent by your application using the sendSecsMsg method or received and handled by your application using the messageTypeAdd method.  The Data Formats in the table below show the Host message formats in situations where host and equipment send the same message type with different data formats.
 
Type Sender Data Format Comments
S1F1R H, E   "Are You There?"
S1F2 H L "On Line Data"
S1F3R H L [<SVID>]*
<SVID>  := {U4 <varID>}
"Selected Equipment Status Request" 
S1F4 E L [<SV>]* "Selected Equipment Status Data"
The data type of the SV value depends on the variable.
S1F11R H L [<SVID>]*  "Status Variable Namelist Request"
S1F12 E L [{L:3 <SVID> <SVNAME> <UNITS>}]+  "Status Variable Namelist Reply"
S1F13R H,E L  "Establish Communications Request"
S1F14 H L:2 {B 0} L  "Establish Communications Request Acknowledge"
S1F15R H   "Request OFF-LINE"
S1F16 E <OFLACK> "OFF-LINE Acknowledge"
S1F17R H   "Request ON-LINE"
S1F18 E <ONLACK> "ON-LINE Acknowledge"
       
S2F13 H L [<ECID>]* "Equipment Constant Request"
S2F14 E L [<ECV>]* "Equipment Constant Data"
S2F15R H L [{L:2 <ECID> <ECV>}]* "New Equipment Constant Send"
S2F16 E <EAC> "New Equipment Constant Ack"
S2F17R H   "Date and Time Request"
S2F18 E A:16 YYYYMMDDHHMMSScc 
A:12 YYMMDDHHMMSS
"Date and Time Data"
S2F23R H L:5 <TRID> <DSPER> <TOTSMP> <REPGSZ> {L [<SVID>]+}  "Trace Initialize Send"
S2F24 E <TIAACK> "Trace Initialize Acknowledge"
S2F25R H,E B [<b>]* "Loopback Diagnostic Request"
S2F26 H B [<b>]*  "Loopback Diagnostic Data"
S2F29R H L [<ECID>]* "Equipment Constant Namelist Request"
S2F30 E L [L:6 <ECID> <ECNAME> <ECMIN> <ECMAX> <ECDEF> <UNITS>]+  "Equipment Constant Namelist"
S2F31R H A:16 YYYYMMDDHHMMSScc 
A:12 YYMMDDHHMMSS
"Date and Time Set Request"
S2F32 E <TIACK> "Date and Time Set Acknowledge"
S2F33R H L:2 <DATAID> {L [{L:2 <RPTID> {L [<VID>]*}]*} "Define Report"
S2F34 E <DRACK> "Define Report Acknowledge"
S2F35R H L:2 <DATAID> {L [<CEID> {L [<RPTID>]*}]*} "Link Event Report"
S2F36 E <LRACK> "Link Event Report Acknowledge"
S2F37R H L:2 <CEED> {L [<CEID>]*} "Enable/Disable Event Report"
S2F38 E <ERACK> "Enable/Disable Event Report Acknowledge"
S2F39R H L:2 <DATAID> <DATALENGTH> "Multi-block Inquire"
S2F40 E <GRANT> "Multi-block Grant"
       
S4F25R H L:2 <DATAID> <DATALENGTH> "Multi-block Inquire"
S4F26 E <GRANT> "Multi-block Grant"




S5F1R E L:3 <ALCD> <ALID> <ALTX> "Alarm Report Send"
S5F2 H B 0 "Alarm Report Ack"
S5F3R H L:2 <ALED> <ALID> "Enable/Disable Alarm Send"
S5F4 E <ACKC5> "Enable/Disable Alarm Ack"
S5F5R H <ALID vector> "List Alarms Request"
S5F6 E L [{L:3 <ALCD> <ALID> <ALTX>}]* "List Alarm Data"
S5F7R H   "List Enabled Alarm Request"
S5F8 E L [{L:3 <ALCD> <ALID> <ALTX>}]* "List Enabled Alarm Data"
       
S6F1 E L:4 <TRID> <SMPLN> <STIME> {L [<SV>]+} "Trace Data Send"
S6F3[R] E L:3 <DATAID> <CEID> [{L:n {L:2 <DSID1> {L:m [{L:2 <DVNAME> <DVVAL>}]*}}]* "Discrete Variable Data Send"
S6F4 H B 0 "Discrete Variable Data Ack"
S6F5R E L:2 <DATAID> <DATALENGTH> "Multi-block Data Send Inquire"
S6F6 H B 0 "Multi-block Grant"
S6F11R E L:3 <DATAID> <CEID> {L [{L:2 <RPTID> {L [<V>]+}}]+} "Event Report Send"
S6F12 H B 0 "Event Report Ack"
S6F13R E L:3 <DATAID> <CEID> {L [{L:2 {U4 <rptid>} {L [{L:2 {U4 <vid>} <V>}]+}}]+} "Annotated Event Report Send"
S6F14 H B 0 "Annotated Event Report Ack"
S6F23R H <RSDC> "Request or Purge Spooled Data"
S6F24 E <RSDA> "Request or Purge Spooled Data Ack"
       
S7F1R H,E L:2 <PPID> <LENGTH> "Process Program Load Inquire"
S7F2 E,H <PPGNT> "Process Program Load Grant" - The SecsHost always sends B 0.
S7F3R H,E L:2 <PPID> <PPBODY> "Process Program Download"
S7F4 E,H <ACKC7> "Process Program Download Acknowledge"
S7F5R H,E <PPID> "Process Program Upload Request"
S7F6 E,H L:2 <PPID> <PPBODY> "Process Program Upload Data"
S7F19R H   "Current Process Program Dir Request"
S7F20 E L [<PPID>]* "Current Process Program Data"




S*F0     abort replies are handled as a special case of reply
S9F1 E <MHEAD> "Unknown Device ID"  - The SecsHost has logic to automatically correct this error when first establishing communication.
S9F3 E <MHEAD> "Unknown Stream"
S9F5 E <MHEAD> "Unknown Function"
S9F7 E,H <MHEAD> "Illegal Data"
S9F9 E,H <MHEAD> "Transaction Timeout"
T3 timeout
S9F11 E <MHEAD> "Data Too Long" 
       
S10F1 E L:2 {B 0} {A <text>} "Terminal Request"
the example application handles this message type
S10F3R H L:2 <TID> {A <text>} "Terminal Display, Single"
 S10F4  E  <ACKC10>  

License Terms

Subject to Change Without Notice

The Hume Java SecsHost software is licensed for development and runtime use at no additional charge for computers that are licensed for development use of the Hume Integration Datahub SDK.

Hume Integration is also pleased to offer separate runtime licenses for using the SecsHost software on systems that are not licensed as development systems.  Contact Hume Integration for more information.


Document Version

Date of last revision: $Date: 2016/04/06 13:43:05 $