SecsEquip - A Java Library for Equipment SECS Interfaces


The SecsEquip class library provides a high-level start when deploying SEMI standard GEM-compliant SECS equipment interfaces using Java. Without any customization, the software implements almost all of the Fundamental GEM Requirements and the Additional GEM Capabilities. Method calls are provided for the developer to add his own Status Variables, Equipment Configuration Variables, Alarm Definitions, and Event Definitions to the existing items specified in the GEM standard.  The developer writes handlers to receive asynchronous inputs such as Remote Command invocations, Terminal Display invocations, or the reception of any SECS message type of his choosing.  A callback interface may also be used to provide Status Variable values needed for satisfying Host requests and for sending dynamic Event Reports.

Feature Summary


User Guide

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

The humeDocs.zip contains the javadoc files for the SecsEquip library and related classes.  This is an essential download for Java developers.  You need to associate the documentation in this archive with the SecsEquip.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 host applications for you to communicate with your equipment 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 JavaEquipApp.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 or Linux, then you get a Program Group that includes the Program item "Host Supervisor".  This is the most convenient host program to run for testing your Java equipment application.  You also have Program items "Gem Equipment" and "GEM Tool".  These program items are Tcl/Tk applications that are similar to the Java SecsEquip applications.  You do not want to run more than one of these applications at the same time as your Java equipment application unless you configure the applications to use different TCP/IP socket ports.  You can familarize yourself with the Tcl/Tk host and equipment applications by running them both and having them communicate with each other.  Then at some point you can terminate the Tcl/Tk equipment application and use the Host Supervisor application to communicate with your Java equipment 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 recent version of the JRE or JDK such as version 1.8 or newer with your Java IDE.   Contact Hume regarding earlier versions if needed.

Extract the files in the JavaEquipApp.zip archive to a directory of your choice such as c:\java\hume\equip.  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 host 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 JavaEquipApp.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 SecsEquip.jar file to the classpath. 

Here is a summary of how to create an Eclipse project for the equipment application.  
  1. Use the menu item File/New/Java Project
  2. Fill in the Project Name - for example,  equipmentSECS
  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\equip"
  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 SecsEquip.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 SecsEquip.jar file.  However, If you see under the SecsEquip.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 "/equipmentSECS/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 applications.  In the left Package Explorer pane, expand JavaEquipApp and double-click on EquipGUI.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 EquipGUI.java, type control L (ctrl-L) and enter line number 105 to go to line 105 of the file.    A source line near that location is similar to "SecsEquip se = new SecsEquip("eqsim", "GEM");".   Move your mouse over the SecsEquip class name and you should see API help appear for the SecsEquip class.  If you hover over SecsEquip in "new SecsEquip" you see help for the constructor.  Now click the mouse on either SecsEquip term and press the F3 button to display the source code.  The SecsEquip.java file should be loaded into the editor, and you should be located at the class declaration or constructor declaration.

Hume provides two example Java equipment applications, EquipGui.java, and ToolUI.java.  You will want to run and explore each one.  The EquipGui application features Operator controls for a simulated tool.  There are controls for the User to select and run process recipes.  The ToolUI application only includes User controls for SECS/GEM features that should be provided by your application.  Be aware that there is a hidden System Administrator menu exposed by right clicking on the Communication LED.  The design of the ToolUI application is that the Frame window can be used directly as an additional top-level window of your application, or you can merge its features into your tool GUI.  The ToolUI application incorporates example logic to execute Remote Commands sent by the Host which is nearly identical to the Remote Command Logic of the EquipGui application.

If you installed the Hume SDK with the default paths, you should be able to run or debug the applications 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 SecsEquip class is used, review the EquipGui.java  and the ToolUI.java source code files.  In the "Outline" panel on the far right of the Eclipse Java perspective, scroll down near the bottom and select the "secsInterfaceInit()" method.  This action takes you to startup initialization code of either demonstration application.  You will code a similar sequence for your own equipment.

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 10, Windows 7 Pro, or Windows XP.  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 SecsEquip.jar file from the JavaEquipApp.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 SecsServer85CENTOS7_x86_64.zip archive or similar.   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 Host Supervisor application installed as a Program Item.

Environment Variable DMH_JAVA_TCLDIR

When the SecsEquip 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 SecsEquip class with an existing project, you add the SecsEquip.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 all of the following import statements

import com.hume.SECS.*;
import com.hume.DMH.DmhClientItf;
import com.hume.DMH.ListBuilder;
import com.hume.DMH.ListFormatException;
import com.hume.DMH.StringList;
import com.hume.DMH.TclList;

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

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

Here is the general flow of initializing and configuring a SecsEquip instance as seen in the EquipGUI.java source code:

  1. Construct a SecsEquip instance.   At runtime, constructing the instance causes the child SECS server process to be started.
  2. Code your event callbacks using the method signatures defined in the interface declarations.  The reception of StateChange events and SECS messages of your choosing are dispatched into your application using callbacks.  The callbacks are executed by 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:
  3. SwingUtilities.invokeLater(new Runnable() {public void run() { GuiXXXUpdate(); }})
  4. Use the messageTypeAdd method to register callbacks for SECS message types that you desire to handle in your application.  Getting communication established and sending alarm and event reports is already provided for.
  5. Call startupLoad and startupRestore to initialize the communication and control state properties to their persisted values.  Alternatively you may  have your own persistence mechanisims and call connectTypeHsmsPassive or connectTypeHsmsActive to set the HSMS connection type.  Do this early in the initialization so that the SECS Server creates a data array and table records which are used internally to manage the interface's configuration.
  6. Set other properties as desired such as the timer values, MDLN, SOFTREV, ....
  7. Add equipment specific alarm types using the alarmAdd method.
  8. Add new event types using the eventAdd method.
  9. Add Parameters using parameterAdd.  Parameters are values that the host is allowed to change within your specified limits.  Host initiated parameter changes are delivered to your application as ParameterChange events. 
  10. Add Status and Data Value Variables using the variableAdd method.  Variables are read-only values for the host such as  process measurements.  The host can query current values, and include variables in event report definitions in order to perform data collection.  Setup your callback logic to supply the current values of selected variables and use the variableMethodSet call to specify your callback interface(s).
  11. Call commEnable after you have the proper configuration in place to enable communication with the host.
  12. 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, HsmsHost, HsmsPassive, and HsmsPort.
  13. Non-connection properties such as the Device ID and timer values can be updated at any time without disrupting communication.
  14. Call commDisable to disable SECS communication.  It is called automatically by the SecsEquip close, 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 the split method to parse the text, they take care of parsing and removing surrounding braces for you.   If an empty string is sent, you receive 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 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.  Java 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, "I8 110"
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, "U8 990"
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 SecsEquip class has built-in logic to handle more than 85 of the standard SECS message types.  You do not have to code or provide for complex GEM capabilities such as configuring and sending dynamic event reports, or managing the communication and state models. See the reference table for more detail on the built-in message types.

Similarly, the variables required for GEM compliance are already defined, and are listed in a table .  In some cases, such as the PPExecName variable, your custom application logic has to provide current data values.  The example application demonstrates using the variableSet method or the variableMethodSet method as techniques to supply variable values.  If a data item's value is changed infrequently, its more efficient to use variableSet which provides the current value to the SECS server process.  The variableMethodSet method is the right choice for data items whose value changes more often, or are easier to manage as Java application data items.

The SecsEquip software uses type U4 numeric identifiers for the numeric IDs called out by GEM such as ALID, CEID, ECID, and SVID.  These identifiers are passed as unsigned, 4 byte integers - SEMI Octal code 54.

 There also are some standard event report types specified by GEM and pre-defined for you as listed in a table.  Your application logic needs to call eventPost as these events and your own defined events occur during processing.
 

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 GUI 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 making method calls to report events, or alarms.  Because of the internal design of the SecsEquip, 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.

Miscellaneous Notes

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

GEM Compliance Statement

The software is written to conform to SEMI Standard E30 - Generic Model for Communications and Control of SEMI Equipment (GEM).  It also provides compliance to SEMI standards E5, E37, E37.1, and E10.  The software is also fully compliant with photovoltaic industry standard PV2.

The Equipment OEM developer will need to be mindful of the standards when using the Hume SecsEquip class in order to insure that compliance is fully met. 
 
Fundamental GEM Requirement Implemented Gem Compliant Implementation Notes
State Models Yes Yes The Communication State model is implemented by the SecsEquip and controlled by calling the commEnable and commDisable methods.  The current Communication State value is readable as the property, CommState. Your application receives notification of CommState and similar state changes by handling the SecsEquip StateChange event.  This event notifies you of important changes such as communication with the Host starting or ending.

Your logic and your Operator GUI affect the Control State by setting the ControlIntentOnline and ControlModeRemote properties.  The ControlStateStartup property is used to determine startup state.

The standards require the persistent configuration of the communication connection properties, communication enablement, and the control state start properties.  The example application uses the methods startupSave, startupLoad and startupRestore, and the StartupDialog class for this purpose.  You may substitute your own configuration and persistence mechanisms or use the provided ones.

Comments on the Process State model follows in the next row.  Other equipment models such as Spooling are described below in this table.

Equipment Processing States Yes Yes The example application fully implements a Process State model that you can copy and modify.  Follow the example as far as posting standard GEM events for Process State changes and related events such as selecting a different Process Program.  You also need to update Status Variables to keep track of the previous and current process states, just as the example application demonstrates.
Host Initiated S1F13/F14 Scenario Yes Yes This behavior is fully provided by the SecsEquip class.
Event Notification Yes Yes Your logic needs to call the eventPost() method at the occurrence of standard collection events.  You may choose to define and report additional event types for the activities of your equipment.
On-Line Identification Yes Yes You are obligated to set the property values MDLN and SOFTREV to reflect the hardware and software configuration of the equipment.  Any change in the equipment software should result in a new unique value of SOFTREV.
Error Messages Yes Yes The standard requires use of Stream 9 Error reporting.  The SecsEquip sends specific Stream 9 messages for communication faults, conversation timeouts, incorrect device ID, unhandled message stream or function types, and non-standard data.  In the custom message handling logic that you write, use the method sendS9 to send error messages when the received message data is not in the expected format or has improper values.
Documentation Yes Yes Hume Integration has example documentation which meets requirements of the GEM and SECS standards.  This documentation is provided to Equipment providers with permission to create derivative works.

 The SECS Server has the ability to export HTML documents of the configured event, alarm, and variable table data.  You may want to use this feature of the table window that is display by executing the debugTableWindow method.

Control (Operator Initiated) Yes Yes Use the JavaEquipApp application as a worked example.  The startup control state is settable using the property ControlStateStartup.  The operator choice of ON-LINE or OFF-LINE control is settable as the boolean property value ControlIntentOnline.  The desired substate of ON-LINE control, LOCAL or REMOTE, is settable as the boolean property ControlModeRemote.  The actual control state value reflects interaction with the Host and is readable as the property ControlState.  Your application receives notification of ControlState and similar state changes by handling the SecsEquip StateChange event.
ADDITIONAL CAPABILITIES      
Establish Communications Yes Yes This behavior is fully provided by the SecsEquip class.
Dynamic Event Report Configuration  Yes Yes This behavior is fully provided by the SecsEquip class.

With the capabilities that involve Status Variable values (SV) or Data Variable values (DVVAL), your job is to add equipment specific variables using the variableAdd method.  You either provide their values through a callback using variableMethodSet or by calling variableSet when their values are changed. 

Variable Data Collection Yes Yes This behavior is fully provided by the SecsEquip class. 
Trace Data Collection Yes Yes This behavior is fully provided by the SecsEquip class. 
Status Data Collection Yes Yes This behavior is fully provided by the SecsEquip class.
Alarm Management Yes Yes This behavior is fully provided by the SecsEquip class.  Your job is to add equipment specific alarm types using the alarmAdd method.  You use the method alarmSet to indicate when an alarm condition is set or cleared.  You can optionally use the method alarmEnable to enable or disable reporting of an alarm type as a Stream 5 message.  Gem also requires event reports for the Alarm Set and Alarm Clear events.  These event definitions are automatically created and managed for you by the SecsEquip when you use the alarmAdd method.
Remote Control Yes  Yes The example application shows how to use messageTypeAdd to receive and process Remote Commands (S2F21, S2F41, or S2F49) in your application code.   You need to implement control logic that is mindful of the Process State model and the Control State model.  For example, you need to disallow Remote Commands that affect processing when you are in the Online Local Control State. 
Equipment Configuration Variables (ECVs)
Yes Yes This behavior is fully provided by the SecsEquip class.  Your job is to add equipment specific items using the parameterAdd method.  You call parameterSet if your GUI logic or controller logic changes the value so that the SECS Server can update the ECIDChangeName and ECIDChangeValue GEM variables, and issue the GEM OperatorECVChange event.  If the host changes an ECV, you are notified via a ParameterChange event.
Process Program Management Yes Yes The SecsEquip class fully implements process program management features with upload and download capabilities.  You can set the directory used for process programs as the property ProcessProgramDirectory.  You can set whether process program data is transferred as binary or text using the ProcessProgramTypeBinary property.  Your application is notified of process program change events by handling the SecsEquip StateChange event.   You will receive notice when recipes are downloaded from the host, uploaded to the host, or deleted by the host.  You can use these notifications to trigger validation of downloaded recipes, or you can defer validation until the time the process program is loaded for use.
Material Movement Yes Yes The GEM standard only requires that the equipment provide Data Collection events when material is sent from any port on the equipment, or received by any port, whether the transfers are automated or manual.

Automated Material Movement is implemented by calling the method messageTypeAdd and registering a callback for each of the primary message types that the host sends.  In your callback, you parse the received SECS message data using the TclList.split() and TclList.listElement methods.  You send reply messages using the sendReply method.  You initiate your own primary messages and optionally wait for the SECS replies using the sendSecsMsg method.

Equipment Terminal Services Yes Yes The example application for the SecsEquip demonstrates displaying data received from the host, sending acknowledgment events, and sending display data to the host.  For your own implementation,  use the method terminalDisplayAck to send acknowledgment events, and follow the example code for sending input data to the host using sendSecsMsg.
Clock Yes Yes The SecsEquip component fully implements a host-settable Clock variable value with standard data format choices.  The implementation does not affect the system clock, the host's setting is saved as an offset.
Limits Monitoring No   See the notes for Material Movement, above, to understand the general approach that is taken to implement this capability. 
Spooling Yes Yes The SecsEquip component fully implements Spooling.  We recommend that the equipment supplier only allow spooling of Alarm messages, and Event report messages or similar messages where there is no control logic tied to the receiving of the reply messages.  These are exactly the message types that most factory CIM workers want to collect with spooling.  If restricting the spooled message types is not done, there are complex issues with implementation and timing that cannot be adequately tested and verified correct.  The standard describes allowing the spooling of nearly any primary message type, out of consideration that any message may occur when the spool is being unloaded, and it should take its proper sequence at the end of the spool.  In practice this is a rare circumstance because an HSMS implementation can unload thousands of messages in a few seconds.  The downside of allowing messages that have control implications to be spooled is that they are queued for a variable and potentially lengthy delay before delivery.  The equipment provider's job is to provide a robust control system, and we think that knowing immediately that a near real-time message conversation cannot be initiated is the right choice. 

The Equipment provider can add to the message types allowed for spooling using the SpoolingAllow property.  The default behavior is to allow only Stream 5 (Alarms) and Stream 6 (Event reports) to be spooled.

Control (Host-Initiated) Yes Yes The SecsEquip class fully implements this behavior.


SecsEquip API Reference


SecsEquip Properties
Property Access Description

boolean isAlarmEventShared()
void setAlarmEventShared(boolean b)
Set this property value true to have the same AlarmDetected and AlarmCleared data collection events reported for any alarm type.  The preferred value of this property should be set before calling the alarmAdd() methods.  The behavior preferred by the Photovoltaic Industry Draft Standard #4557 is to have the value set true and to share generic events.  The default value of the property is false to preserve compatibilty with existing applications. 
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 value1993 is for non-standard Draft HSMS, and 1995 is for standard HSMS.  The default is 1995.  An exception is thrown if an inappropriate value is set.  We suggest you use the methods connectTypeHsmsPassive() and connectTypeHsmsActive() instead of setting individual properties and then calling this method.
boolean isControlIntentOnline()
void setControlIntentOnline(boolean b)
Whether your intended GEM Control State is ON-LINE and interacting with the host or OFF-LINE.  The default setting is false, meaning OFF-LINE.
boolean isControlModeRemote()
void setControlModeRemote(boolean b)
When in ON-LINE control, whether your intended substate is REMOTE or LOCAL.  The default setting is false, meaning LOCAL.
String getControlState() A read-only value of the actual GEM Control State, which reflects your ControlIntentOnline value, your ControlModeRemote value, and host dynamics.  Possible values are ON-LINE LOCAL, and ON-LINE REMOTE, OFF-LINE Equipment, OFF-LINE Host, and OFF-LINE SeekOnline

int getControlStateStartup()
String getControlStateStartupText()
void setControlStateStartup(int StateIndex) throws Exception

public static final int CS_OFFLINE_EQUIPMENT=0,
    CS_OFFLINE_ATTEMPT_ONLINE=1,
    CS_OFFLINE_HOST=2,
    CS_ONLINE_LOCAL=3,
    CS_ONLINE_REMOTE=4;

Your software is able to specify the initial state for the GEM Control State model.  The choices are CS_OFFLINE_EQUIPMENT, CS_OFFLINE_ATTEMPT_ONLINE, CS_OFFLINE_HOST, CS_ONLINE_LOCAL or CS_ONLINE_REMOTE.  The default setting is CS_OFFLINE_EQUIPMENT but this value may be automatically changed when commEnable() is called to be consistent with your ControlIntentOnline and ControlModeRemote values. If your ControlIntent is OFF-LINE, and your startup is an Online state, the startup state is changed to CS_OFFLINE_EQUIPMENT.  If ControlIntentOnline is true and your startup state is CS_OFFLINE_EQUIPMENT, your startup state is changed to CS_OFFLINE_ATTEMPT_ONLINE.  Similarly the setting of ControlModeRemote can overrule an online startup state corresponding to the opposite LOCAL or REMOTE online substate choice. The ControlState String values are enumerated in the SecsEquip.ControlStateText array as indexed by the integer constants representing the substates.  You can use the getControlStateStartupText() method to obtain the string value of the startup state.
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.  You can change the Device ID at any time, but if you change it while communicating, you may create problems for the host software.  Settable range is 0..32767.
static DmhClientItf getDmh() SecsEquip 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 for custom purposes.
static String getDmhGroupName() The DMH message system groupname used by the SECS server.  The same groupname should be specified to the constructor of every SecsEquip instance in the application in order to share the same SECS server process.
String getHsmsHost() 
void setHsmsHost(String host_or_ip_addr)
For an active HSMS connection, specifies the TCP/IP hostname or IP address of the passive computer.  The default value is "localhost" which is a standard way of specifying your own computer.
boolean isHsmsPassive() 
void setHsmsPassive(boolean passive)
For an HSMS connection, whether the SecsEquip plays the passive, TCP/IP server role.  The default value is true since the usual role for the equipment is passive. 
int getHsmsPort() 
void setHsmsPort(int p)
For an HSMS connection, the TCP/IP socket port number.  Defaults to 5555.
boolean isIdRangeChecked()
void setIdRangeChecked(boolean b)
By default, the methods to add Alarm, Event, Variable, and Parameter definitions, restrict the numeric ID values allowed to ranges which prevent you from colliding with built-in values, or colliding with each other's values.  However, the range checking can be disabled by setting this property value false.  Also, you can renumber the built-in events and variables, and customize the events that are assigned for alarm set and clear events.  Thus, you are able to completely customize the identifiers used by the SECS interface.  If you choose to renumber and customize the identifiers, do it in your initialization logic before enabling communication, but after restoring or configuring the connection type.  This insures that connection instance data exists in the SECS server to hold your customization.
String getMDLN()
void setMDLN(String mdln) throws Exception
The SECS Equipment Model Type - limited to no more than 20 characters by the E5 standard.
String getName() The SecsEquip 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 isParameterSetSaved()
void setParameterSetSaved(boolean b)
This property controls whether the parameter values are saved at the program exit and restored during the next session.  Parameters are also referred to as Equipment Configuration Variables (ECVs). Saving the values of Parameters is standard GEM behavior so the default value is true.  If the value is true, the saved value data is  restored the first time that commEnable is called, unless it has been already restored by calling the method parametersRestore.  In other words, you can use the method parametersRestore to force loading of the saved parameter values before commEnable is called.  The value data is saved as a file of SQL statements in the subdirectory spooldata.  The filename used is "EcvParms_" + Name + ".sql".

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.
boolean isPPFilesByRequest()

void setPPFilesByRequest(boolean isByRequest)
This boolean property is set true if the app must prepare process program files for upload transfer to support SECS message types S7F5R or S7F41R which are handled by the built-in SECS Server logic.  The value is left at the default value of false if process programs already exist as files in the recipe directory or if the equipment does not feature process program transfers.  When the value is set true, the app must handle PPFileRequest events as the trigger to write process program files.  See the description of the PPFileRequest event for more details.
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  "recipes" of the directory where the SECS server is executing.  Note that by default, each equipment interface shares the same 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 isProcessProgramTypeBinary()
void setProcessProgramTypeBinary()
A boolean flag to indicate whether Process Program files should be transferred as type B (binary) data, or type A (ASCII) data.  The default is true, meaning binary transfer.  If Process Program files are printable text, the type A transfer is easier for the factory personnel to work with.  The software is able to transfer binary data as type A but not all host software can accommodate this.
boolean isReportConfigSaved() 
void setReportConfigSaved(boolean b)
This property controls whether the state of event reporting is saved at the program exit and restored during the next session.  Saving the state of dynamic reporting is standard GEM behavior so the default value is true.  If the value is true, the saved event reporting configuration is  restored the first time that commEnable is called, unless it has been already restored by calling the method reportsRestore.  In other words, you can use the method reportsRestore to force loading of the saved reporting configuration before commEnable is called.  The report configuration data is saved as a file of SQL statements in the subdirectory spooldata.  The filename used is "reportdata_" + Name + ".sql".
boolean isS13InUse()
void setS13InUse(boolean b)
This boolean property chooses whether to enable using Stream 13 large process program transfer message types when an online control state exists.  In addition to the Stream 13 messages, this property also enables or disables using S7F29, S7F37, S7F38, S7F41, and S7F42 which are used with Stream 13 for transferring large unformatted, process programs.  The default value is false. 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.  If Stream 13 message types are enabled, per GEM your application should implement sending S7F27 process program verification messages for  received process programs.
String getSOFTREV() 
 void setSOFTREV(String softrev) throws Exception
The SECS Software revision - limited to no more than 20 characters.  Default value is"1.0.0".  You may wish to consider a pattern of major.minor.patchlevel.
String getSpoolDirectory()
void setSpoolDirectory(String spoolDirectory) throws Exception
The file system directory for spooling, report configuration, and parameter (ECV) persistence files.  The default TraceSaving logging directory is also underneath the spooling directory. The get method returns a fully qualified path that uses slash path separators on all platforms.  The default spooling directory is the sub-directory spooling under the working directory of the SECS server.  For a default Datahub SDK installation and startup, the directory is /usr/local/gem2/server/spooling.  The directory value may be set early in the initialization before startupRestore() or connectTypeSet is called.  An exception is thrown by the set method if the specified directory is not valid or if the method call is not made before the connection type is set.
String getSpoolingAllow()
void setSpoolingAllow(String v) throws Exception
This property is set to specify the streams which the host is allowed to specify for spooling in message type S2F43.  It is formatted as a space separated list of "S<s>" tokens where the <s> value is stream number.  The standard does not allow Stream 1 to be spooled.  The default  value is "S5 S6" which allows for spooling alarm messages and event reports.  An empty string value disallows any spooling.  The value only affects the handling of S2F43 messages from the host.  Your software is able to change at any time which message types are being spooled using the method, SpoolStreamFns.
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.  The StateChange event is used to obtain asynchronous notification of this property value change.
int getT3()
void setT3(int v) throws Exception
SECS Reply 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
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 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 transfered 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 of setTraceSaving() is used as follows.  If the rc value is less than 0 the 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 Process Program transfer occur and the trace window is displaying connection activity.  Range 1000..120000, default 4000.
int getVarValueTimeout()
void setVarValueTimeout(int milliseconds)
When you define a variable using variableAdd() and you use the variableMethodSet() method to register a callback that supplies the value of the variable, there is an internal timer that is used to limit the time allowed for your callback to execute and provide the value.  The default timeout value of this timer is 20000 milliseconds.  Under unusual circumstances, your callback evaluations may require more time, and you can modify this timer value.


 
SecsEquip 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 ParameterChangeItf {
   public void parameterChange(SecsConn sp, String name, String newvalue);
   }

ParameterChangeItf onParameterChange(ParameterChangeItf handler)

This event notifies you of host initiated Equipment Configuration Variable (ECV) changes.  The new value is within the limits you have configured.

Use the onParameterChange() method to install your own handler.  The return value is the previous handler that you are replacing.

public interface PPFileRequestItf {
    public RcResult PPFileRequest(String ppid, String recipeDir);
    }

PPFileRequestItf onPPFileRequest(PPFileRequestItf handler);
An application which manages Process Programs in a database or in non-file representations should set the property PPFilesByRequest true and code a handler for this event type.  When the host sends S7F5R or S7F41R to initiate an upload, a PPFileRequest event is raised to trigger the application to write the process program file in the recipe directory.  The app should use the event argument data, ppid for the name of the desired process program, and recipeDir for the file system directory where the file is written.  For Stream 13 transfers initiated by S7F41R or for Stream 7 transfers using S7F5R, the app assigned filename value may differ from the ppid value.  The app writes the file or fails, and sets the return string result value of the callback to the filename written or to an error description.  Set the string result value to the filename only, and do not include the directory path.  The app also sets the return integer code value to 0 for success, or to an error value.  The pathname for the output file is computed by concatenating the recipeDir with a slash and then the filename assigned by the app.  Do not use a backslashes, even on windows.  See the Console application source code for example usage of this feature. 

The return value of the callback, an integer and a string in the RcResult structure are used to communicate success or failure to the SECS Server and subsequently to the host.  Integer error values from the SEMI E5 data item ACKC7 are applicable.  Approximately 20 seconds are provided to write the file.  If this timeout period is not adequate, the app should instead offer a remote command that initiates a file export and then performs an equipment initiated upload.

This event is only part of what the application must do to properly manage process programs that are not managed as files in the recipe directory.  The app should call MessageTypeAdd(7, 17) and (7, 19) to handle delete and directory requests.  The app should also use the StateChange events, recipe_download, and dataset_download to trigger file import logic.  The app can use recipe_upload and dataset_upload to trigger deletion of the export files if desired, or they can left alone to be overwritten by future uploads and downloads.
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.  This mechanism is demonstrated for Remote Commands and for Terminal Services in the example 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 SecsEquip if you want to use a method that is defined by the SecsEquip 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 are not expected 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 SpoolingAlertItf {
   public void spoolingAlert(SecsEquip sp, String msgid);
   }

SpoolingAlertItf onSpoolingAlert(SpoolingAlertItf handler)

The GEM standard describes Spooling events that are to be brought to the attention of the equipment operator.  The msgid values include SPOOLING_ACTIVATED, SPOOLING_FULL, SPOOLING_TERMINATED, SPOOLING_NOT_PERSISTENT, and SPOOLING_DATA_DISCARDED.  See the example explanation messages in the application.  The latter two values are not seen in normal circumstances.

Use the onSpoolingAlert() 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 varName, 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
  • clock_offset - this value is the number of seconds added to the system clock to provide CLOCK variable values for the host.  If the value differs from 0, the host has used S2F31 to set the clock.  Your logic can work with  host specified time values by adjusting the system time using this offset value, or by  reading the CLOCK variable using VariableGet().  We recommend that you avoid this complexity by instructing your customers to use NTP time synchronization and that you disable S2F31 using MessageTypeRemove(). 
  • comm_state - the CommState property value changed
  • control_state - the ControlState property value changed
  • dataset_download - a process program has been downloaded from the host using Stream 13 transfer messages.  The newValue argument is a two item list, the ppid, and the pathname to the newly received file.  Use TclList.listElement or the TclList split method to parse the list.  See the discussion of downloaded files in the description of method processProgramLargeRequest.
  • dataset_upload - a process program was successfully transmitted to the host using Stream 13 transfer messages.  The newValue argument is the ppid.
  • event - this value changes when a data collection event is posted either by your logic calling the eventPost method, or by the built-in SECS server logic.  The newValue argument is a two item list, the CEID of the event, and a 1 or 0 indicating whether an event report message was sent or not.  A report is not sent or spooled if communication is disabled, or if the event type is disabled, or if the control state is offline.  Also, when spooling is active, the event report may not be spooled.
  • recipe_delete - a process program was deleted by the host or replaced with a downloaded version using Stream 7 transfer messages.
  • recipe_download - a process program was downloaded from the host to the equipment using Stream 7 transfer messages.  However, if the PPFilesByRequest feature is being used, the newValue argument is a two item list, the ppid, and the pathname to the newly received file.
  • recipe_upload - a process program was transmitted to the host from the equipment using Stream 7 transfer messages.
  • spooling_state - the SecsEquip spooling state, ACTIVE or INACTIVE.
  • SpoolCountActual - the number of SECS messages currently spooled 
  • SpoolCountTotal - the total number of messages spooled and/or discarded 
  • SpoolMax - the configured maximum number of spooled messages 
  • SpoolStreamFns - the list of S<s>,  S<s>F<f> message types that configured for spooling 
Your application gets notified of the initial values of these items when the SecsEquip 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.

SecsEquip Methods
METHOD DESCRIPTION
General Comments
 
 

 

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

void alarmAdd(int ALID, String ALTX) throws Exception

void alarmAdd(int ALID, String ALTX, int alarmSetCEID, int alarmClearCEID) throws Exception
Add an alarm type definition. Newly created alarms are enabled.  The first form is the commonly used choice for new SECS interfaces where the CEID's for the GEM Alarm events are configured automatically.   Depending on the setting of the AlarmEventShared property, the GEM alarm set and clear data collection events will either be the same events shared by all alarm types, or two new events will be created for each alarm type.  Set your preferred value of AlarmEventShared before using the AlarmAdd methods. 

If the AlarmEventShared property is true, use only the first form of alarmAdd where the set and clear event IDs are not specified.  Use any ALID value from 1000 to 3999.  If the AlarmEventShared property is false, choose only even numbers for the ALID from 1000 to 3998  to allow for two enabled events which are created for each alarm, an alarm set event with CEID == ALID, and an alarm clear event with  CEID == ALID+1. 

The ALTX argument is a description of the alarm and it has a length limit of 120 ASCII characters.  The ALTX should not contain single quote characters.

The second form of alarmAdd() lets you specify the CEID values used for the Alarm Set and Clear event reports.  Use this form if you need to customize which data collection events are posted for the alarm's Set and Clear events.  If the event types do not already exist, they are created.  There is no validation performed on the specified CEID values, they only need to be representable as 4 byte unsigned integers.   With this form of alarmAdd you are able to specify any ALID value from 1000 to 3999 with the default range restriction in place.

With either form, you are able to bypass the usual range restriction of the ALID value by setting the property IdRangeChecked false.

void alarmEnable(int ALID, boolean is_enabled) Enable or disable reporting of an Alarm type (S5F1).
boolean alarmIsEnabled(int ALID) Test if the reporting of an alarm type is enabled 
boolean alarmIsSet(int ALID) Test if the alarmed state is currently set
void alarmSet(int ALID, boolean is_set) Set or Clear the alarmed state of an alarm.
HubTableModel alarmTable() This method returns current data from the SECS Server ei_alarm table for the SecsEquip instance.  The columns of the table include: spname, ALID, is_enabled, is_set, and ALTX.  The HubTableModel extends the Java swing AbstractTableModel and includes a refresh() method.  It can easily be displayed in a JTable.
String alarmText(int ALID) This method looks up the description, ALTX, of an alarm type.  An empty string is returned for a non-existent alarm type.
int binToInt(String binValue)

 

Converts a SECS B (Binary  - Semi "10") data value usually formatted as a hexadecimal string to an integer value.
void close() This method can be used to stop communicating and gracefully shutdown the instance.  It is comparable to a destructor or finalize method, and the instance should not be used after it is called.  The method leaves intact persistent file system data such as the state of spooling and reporting for future instantion.
void commDisable() Disable SECS communication.  The SecsEquip 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.  When your equipment is configured for the Active HSMS role, field personnel will want to display the trace window with the 0x0002 TRACE property bit set 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 the recommended alternative to setting the underlying property values to specify an active HSMS connection type, and calling ConnectTypeSet().
RcResult connectTypeHsmsPassive(int port) This method is the recommended alternative to setting the underlying property values to specify a passive HSMS 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.
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() The delete method is called when an instance is no longer wanted, and there is no intention of future use.  The delete method disables communication as well as deleting data structures and resources used by the instance.  It also deletes the interface's persisted data including the TraceSaveDir directory.  The close method should be used instead of delete for a shutdown that does not delete persisted data.
void eventAdd(int CEID, boolean isReported, String description) throws Exception

void eventAdd(String eventName, int CEID, boolean isReported, String description) throws Exception

This method is used to create an Event type.  With the default range checking of ID values, you are restricted to use CEID values between 5000 and 9999 so you do not collide with Alarm Set and Clear events, or the built-in events.  You can set the IdRangeChecked property false if you need to customize the assigned IDs.  Events can be given meaningful names, and the names can be used when posting event occurrences.  Choose names that are less than 256 characters and consist of alphanumeric characters and/or the hyphen or underscore.  The first form of eventAdd() defaults the event name to the CEID value expressed as a String.  The second form of the eventAdd() method allows you to specify your own event name value which should be unique among all of the event names for the SecsEquip instance.
void eventDvvals(String eventName, String  [] dvvalNames)
This method is used by the application to provide descriptive information used in the S1F24 reply which is a newly proposed standard message as of October 2011.  To support this message type, the application provides eventName values when creating events using eventAdd().  Then, for event types which have associated Data Value variables (class DVVAL), the application uses this method to inform the SECS Server of the association using the variable varname values.   This method is used late in the initialization after the event type and the associated DVVAL variables have been added.
void eventEnable(int CEID, boolean is_enabled) Event reports are enabled for an event type when first created.  You can use this method to control whether an event report is enabled.
boolean eventIsEnabled(int CEID) Test if reporting of an event type is currently enabled.
void eventPost (int CEID)

void eventPostByName(String eventName)

These methods are used to announce when an event has occurred.  In general, make sure that the data items that the host might want in an event report are set to their proper values before eventPost is called.  You should make this call without testing to see if reporting of the event is enabled and without other testing of the communication or control states. The two method forms allow for posting the event by its CEID or its name.
int eventRenumber(String eventName, int newCEID) throws Exception This method is provided so that the CEID values of the built-in events can be customized.  Use the method after restoring or configuring the connection type, and before enabling communication. If the newCEID value is in use by a different event, that event is given a "temporary" ID value of the current value plus 1 million under the assumption that it will be renumbered as well.  After initialization, if events are found with ID values greater than 1 million, they indicate that more than one event has been assigned to the same ID value. 

A positive return value is a warning, and the value 0 indicates success.  In more detail, the return values and their meanings are:

0
The event already has the desired ID, or the event was renumbered successfully.
1
The newCEID was in in-use so the existing event was renumbered to a "temporary" ID.
2 or more
The return value is the number of events of this name that were found.  The extra table records were deleted and the surviving table record has the desired ID or was renumbered successfully.  This condition is not ordinarily expected.
Exception
If the varname does not identify an existing event an exception is thrown.  Also, if the method does not succeed from an unexpected error such as a timeout, an exception is thrown. 
java.util.ArrayList<int []> eventReportLinks() This method call returns a list of integer pairs for the current associations of event types and event report definitions.  Each int [2] pair has the CEID value at subscript 0, and then the RPTID value at subscript 1.  These association links are setup by  the host using S2F35.  They can also be setup using the reportLink method.  This method supports helping you display or provide for editing of the event report configuration.
void eventUnlink(int CEID) This method can be used to unlink (disassociate) any reports that are associated with an event type.  The call can be used if your tool supports manual editing of event reports.
boolean linktest() Synchronously test a COMMUNICATING HSMS connection to verify that the link is responsive.  May take up to timeout period T6 to return. On failure, the HSMS socket connection is closed and the CommState will no longer be COMMUNICATING.  Useful for equipment to force a broken connection to be discovered just before important event reports so that the report messages are spooled or so that the app is in sync with the actual communication state. Returns true if the link is up, false if the link is down.
void linktestAsync() Cause a linktest HSMS control message to be sent to test if a healthy connection still exists.  Forces discovery of a bad connection after a T6 timeout. If the link test fails, the HSMS socket connection is closed and the CommState is no longer COMMUNICATING.  The method is useful for periodic polling if there is an issue with broken connections not being discovered soon enough.
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 SecsEquip is in the online control state and the messages are received from the host.  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.  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 SecsEquip since SecsEquip 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 during the online control state by the built-in SecsEquip 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.
void parameterAdd(int varID, String varname, String description, String valueTsn,    String initialValue, String minValue, String maxValue, String defaultValue,
   String units) throws Exception

void parameterAdd(int varID, String varname, String description, String valueTsn,    String initialValue, String minValue, String maxValue, String defaultValue,
   String units, boolean affectsProcessing) throws Exception
This method is used to add Equipment Configuration Variable definitions (ECV's).  ECV's are also referred to as Equipment Constant Variables, but this is a misnomer in the SECS standards and an oxymoron as well, they are the only variable type that the host is allowed to change.  Our suggestion to you and the industry at large is to refer to ECV's as Equipment Configuration Variables.

With the default range checking active, use varID values  that are between 1000 to 2999.  Use a unique value for each parameter.  The variable name value, varname, should start with an alphanumeric character or the underscore and not have trailing spaces.  Limit yourself to 32 alphanumeric ASCII characters including the underscore, hyphen, and internal spaces.  We suggest you use a single token CamelCase name and make each name unique.  The valueTsn argument is the Tcl SECS notation type code for the ECV value such as F4 for floating point, or A:80 for an ASCII string up to 80 characters long.  Call parameterSet when the ECV value is changed by your GUI or controller logic so that the SECS Server can manage the appropriate GEM event.  With ASCII types, indicate the maximum number of characters, n, that you wish to allow the host to set, by using a type code of the form A:n.  The value of n can be as large as 60000.

The SECS standards prohibit the host from changing Parameter values that affect processing when the tool is in LOCAL control.  A common practice has been to allow the host to change ECV values in LOCAL mode if the value does not affect the current processing run, even if it does affect future runs.  The first form of parameterAdd() assumes that the value does not affect processing (at least for the current run) and so the host is allowed to change values in LOCAL mode.  The second form of parameterAdd() includes the argument affectsProcessing which enables you to explicitly control whether the host is allowed to change the parameter value in LOCAL control mode.

If you have custom ID requirements, you can set the IdRangeChecked property false to disable varID range checking, and you can renumber existing Parameters and Variables using the variableRenumber method.

String parameterGet(int varID)
String parameterGetByName(String varname)
These methods are used to get the current value of an ECV.  The return value is null if there is an unexpected error.   It is marginally more efficient to lookup the variable by the varID value.
VariableInfo parameterGetInfo(int varID)
VariableInfo parameterGetInfoByName(String varname)

public class VariableInfo {
 public int varID;
 public String varname;
 public String description;
 public String varClass;
 public String valueTsn;
 public String varmethod;
 public String units;
 public String minValue;
 public String maxValue;
 public String defaultValue;
}

These methods return the configuration data of an ECV.  The return value is a VariableInfo data structure.
void parameterSet(int varID, String newValue)
void parameterSetByName(String varname, String newValue)
These methods are used to update the value of an ECV by your control logic. The SecsEquip software takes care of notifying the host with the appropriate GEM event.  It is marginally more efficient to lookup the variable by the varID value.
void parametersRestore() Restore the saved values of the parameters (ECVs).  The parametersRestore() method gets called automatically when you first enable communication if property ParameterSetSaved is true, and parametersRestore() has not already been called.  The call restores the values of parameters from the last session, and it initializes saving for the current session. There is logic so that restoring only occurs once.  It is useful to make this call if you want to force the restore action to occur before communication is enabled.  For example, this could support viewing the current values of the parameters before communication is enabled.  The connection type should be set and all of the parameters should be defined before calling this method.
RcResult processProgramDownload(String ppid)

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

The equipment can initiate the download of a process program from the host using S7F5R.  The ppid argument value is both the process program identifier and the file name that is used by the equipment for the process program file. There is no standard SECS message for the equipment to know what process programs are available for download.  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 full absolute pathname of the process program file.  Possible error codes include the error code values of sendSecsMsg() and the following:
-10 file system error
-11 improper data
-12 denial by the host




RcResult processProgramLargeRequest(String ppid)
This method initiates the download of a process program from 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 both the process program identifier and the file name that is used by the equipment for the process program file. There is no standard SECS message for the equipment to know what process programs are available for download.  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 host's reply to S7F41.  The transfer is not complete when the method returns.   The large data set transfer logic receives the downloaded file in the subdirectory, dataset_transfer, of the directory set by the ProcessProgramDir property.  When the transfer is complete, there is a StateChange event with the name dataset_download and the newvalue being a two element list consisting of the ppid value and the full pathname to the newly received file.  To fully comply with the large process program transfer scenarios specified by GEM E30, your application should react to the StateChange event by verifying the newly received process program and sending the S7F27 Process Program Verification message to the host using sendSecsMsg.  The S7F27 message is sent with replyIsWanted true, but there is no reason to wait for the host's reply.  After verification, your application can move the file into the ProcessProgramDir for use, possibly overwriting an earlier version.

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
-13 PP transfers are disabled when spooling is active
-14 A large PP receive is already in progress for ppid
-15 Stream 13 transfers are disabled either from configuration or initialization failure
-16 PPID is not usable as a restricted filename
-17 error when parsing the S7F42 reply


RcResult processProgramLargeSend(String filename)
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.  In most cases, the filename argument value is both the process program identifier and the file name that is used by the equipment for the process program file.  However, when using the PPFilesByRequest feature, the argument value should be the process program identifier, ppid, instead of the filename.  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 host's reply to S7F37.  The transfer is not complete when the method returns.   The large data set transfer logic makes a temporary copy of the file for transfer in the subdirectory, dataset_transfer, of the directory set by the ProcessProgramDir property.  This allows your application to change or access the process program while the copy is being transferred.  When the transfer is complete, there is a StateChange event with the name dataset_upload and the newvalue being the filename value.   If the transfer does not complete successfully, there is additional status information is the SECS server table ei_dataset_xfer.   The SECS Server also posts UploadSuccess, UploadTimeout, and UploadFailure data collection events that can be monitored as StateChange events with the name event.

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
-13 PP transfers are disabled when spooling is active
-14 A large PP receive is already in progress for ppid
-15 Stream 13 transfers are disabled either from configuration or initialization failure
-16 error copying the PPID for large send
-17 error when parsing the S7F38 reply
RcResult processProgramUpload(String ppid)

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

Equipment initiated request to transfer a process program to the host using S7F3R.  The ppid argument value is identically the file name of the process program and the identifier for the process program. 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..  Positive return code values are the ACKC7 data values sent by the host.   Diagnostic text is provided in the result string for all return code values.  Possible return code values include those of sendSecsMsg and the following: 

6 or greater, host indicated error code
5 unsupported mode
4 PPID not found
3 matrix overflow
2 length error
1 permission not granted
-13 upload disabled during spooling

Important:  Do not assume that the host saves process program files with the same file names or in the same format that the equipment does.  The only proper way to use an uploaded process program file is to download it using the same host software that uploaded it.

String processStateNames(int[] stateValue, String [] stateName) throws Exception
Calling this method during initialization adds a Status Variable named ProcessStateNames whose value is a list of Process State values and their names.  The variable is not required by the standards but including it is strongly recommended.  It helps the host provide better displays of processing status.  The stateValue argument is an array of process state integer values.  The stateName argument is a corresponding array of state names. 

The return value is the TSN formatted value of the variable.
void propertySet(String name, String value); There are some less commonly configured properties that can be initialized using this method, such as:
AlarmsAreSaved
Set to 0 to disable the built-in saving and restoring of alarm enablement.
dataid
set to a starting integer such as 0 to cause DATAID values to be sequential integers
recv_max
the maximum number of bytes for a received message (default is 2048000)
spool_no_reply
set to 1 to cause spooling activation when the host does not reply to a primary message
stricttypes
set to 1 to limit the use of S1F3 and S2F13 message types to SV and ECV variables respectively.
trace
additional messages can be added to the tracing and logging
VarValueTimeout
the timeout number of milliseconds for a variable value request (default 20000)
wbit_s5f1
set to 1 to cause S5F1 alarm reports to be sent asking for a reply
wbit_s6f1
set to 1 to cause S6F1 trace reports to be sent asking for a reply
Current settings can be viewed using the Trace Window.  In general, refrain from changing element values of the SECS connection array except as advised.  
int reportDefine(int rptID, int [] varIDs) This method is optionally used to update, create, or delete an event report definition.  If the varIDs array argument is null or empty, the report configuration is deleted.  The return values are: 
0 - a new report created, 
1 - an existing report updated, 
2 - report deleted, 
-1 unexpected transaction error,
-2 unknown variable ID, 
-3 invalid rptID.

Any unsigned number can be used for a report ID (rptID) value. Manual editing of event reports, or the creation of built-in event reports  is not required by GEM since dynamic reporting is provided.   We recommend that you do not provide predefined, built-in reports.  Let the host configure the reporting that is desired.  If you do provide built-in reports, you have a complex situation since GEM specifies that the state of event eporting setup by the host is persistent.  This means the saved and restored reports can delete your predefined ones.  If you choose to implement built-in reports, we recommend that you add an equipment parameter (ECV) and make the user choose between having the built-in reports or having the saved reports defined at startup.  Do one of the following to insure built-in reports are available:  (1) Set the property ReportConfigSaved to false to prevent your built-in reports from being replaced by the restore logic, or (2) Call reportsRestore after your events and variables are defined, and then add your built-in reports after the restore logic has run.

void reportDelete(int rptID) Delete an event report definition. The method  reportsClear() can be used to delete all of the event reports.
int [] reportGetDef(int rptID) Returns an array of the variable IDs in an event report definition.  An empty array is returned if the report does not exist.
java.util.ArrayList<VariableInfo> reportGetInfo(int rptID)

public class VariableInfo {
 public int varID;
 public String varname;
 public String description;
 public String varClass;
 public String valueTsn;
 public String varmethod;
 public String units;
 public String minValue;
 public String maxValue;
 public String defaultValue;
}

Returns a list of VariableInfo structures for the variables in an event report definition.  An empty list is returned if the report does not exist.
int reportLink(int rptID, int CEID) This method supports optional manual editing of the event report configuration or providing for built-in event reports linked to specified events.   The method is used to link or associate a report definition to an event type, causing the report to be sent as part of the event report message.  Both the report and the event type should exist at the time the method is called.  The return values are: 0 success, -2 invalid rptID, -3 invalid CEID, -1 unexpected internal error.
void reportUnlink(int rptID)
void reportUnlink(int rptID, int CEID)
This overloaded method is used to remove the link or association of a report and an event type.  If just the rptID is specified, the report is unlinked from all event types.
void reportsClear() This method erases any existing event report definitions, unlinks the event reports from event types, and disables the event reports that were linked to the deleted reports.  The call also deletes any saved event report data, so it can be used to prevent or nullify the restoring of event reports from the previous saved session.  The method is not usually called since saving and restoring the dynamic event report configuration is standard GEM behavior.
int [] reportsList() The method returns an array of the report ID values for the current report definitions.
void reportsRestore() The reportsRestore() method gets called automatically when you first enable communication if property ReportConfigSaved is true, and reportsRestore has not already been called.  The call restores the state of event reporting from the last session, and it initializes saving for the current session.  Restoring overwrites the existing event report definitions.  There is logic so that restoring only occurs once.  It is useful to make this call if you want to force the restore action to occur before communication is enabled.  For example, this could support viewing the event report configuration before communication is enabled.  A connection type should be set and the variables and event types should be defined before calling this method.
void SecsEquip(String Name, String dmhGroup)  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 SecsEquip instance, and not coincide with a keyword in the Tcl programming language.  The example application uses the Name value of eqsim.  The name should be a single alphanumeric token. 

The dmhGroup argument becomes the DMH message system group name used by the SecsEquip and SECS Server process.  If you are instantiating more than one SecsEquip 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 SecsEquip is executing.  The example application uses the name GEM which does not conflict with the default value for Hume Datahub instances which is mbx or the value GEMHOST used by the example Java Host application.  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.  For example, when the control state is ON-LINE LOCAL, the abort reply should be sent to a host remote command message that would affect processing.
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 instead of a normal reply.  The SecsEquip software takes care of many of the possible error conditions automatically, including, 1- bad Device ID, 3 - bad stream, 5 - bad function, and 9 - T3 timeout.  You will not receive a message type, unless you register for it.  Therefore, you will mostly send the function value 7 to indicate improper data.
RcResult sendSecsMsg(int stream, int function, boolean replyIsWanted, String TsnData, boolean waitForReply)

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 SecsEquip 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
-3 
OFF-LINE   - the control state is OFF-LINE and per GEM only S1F1, S1F13, and S9FX are sendable. 

-4 
DISCARDED   - spooling is active and this message type is not spooled.  Usually the connection is down.  But this result can also occur for a newly established connection before the host has purged or finished unloading the spool. 
-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.
SPOOLED    Your message has been spooled for later sending.  Even if you specify waiting for the reply result you receive this instead of the reply data if the message is spooled.  We recommend you not allowing spooling of message types where you care about the reply.
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 SecsEquip 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 SecsEquip 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 SecsEquip 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 SecsEquip software and made public in case of custom requirements.  After a SecsEquip 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.
void spoolPurge () This method discards any spooled messages that are queued for the host.
void spoolStop() This method sets the messages types that are enabled for spooling to an empty string, thus, further spooling is stopped.
void spoolStreamFns()
void spoolStreamFns(String StreamFns)
The method is used to set the spooled message types.  If called with no arguments, the streams that are allowed for the host to enable (property SpoolingAllow) are enabled.  If called with an argument, the call bypasses the SpoolingAllow property and enables spooling for the S<s> and S<s>F<f> message types that are specified in the input string.
static EquipStartupData SecsEquip.startupLoad(String name) This method retrieves the persisted startup configuration for the named interface.  If no startup data is found, the returned data structure is populated with reasonable defaults, and the name field in the data structure is set to null to indicate that a saved record did not exist.  The method uses the SECS server's ei_equipment data table.  The table data is saved as the file ei_equipment.tab in the SECS server's working directory when the startupSave() method is called. 
void startupRestore(EquipStartupData esd) The method applies the passed startup configuration to the instance, configuring properties according to the data and calling connectTypeSet().  The method does not call commEnable() which allows you to fully configure the instance before going online.  The name field in the input structure is ignored since the instance has already been constructed and given a name.
static RcResult SecsEquip.startupSave(EquipStartupData esd) throws Exception This method assumes that startupLoad() was called during initialization so that the SECS server creates the ei_equipment table which is used to manage equipment startup data.  The method creates or updates a row in the table using the passed configuration, and then saves all of the table data to the file system as the file ei_equipment.tab in the SECS server's working directory.  An exception is thrown if the table data is not saved successfully.  There is only partial checking of the validity of the passed data.  The return value data structure is used to pass a possible warning message for the values controlling tracing and logging.  In this case, the return code value is greater than 0.

This method is used by the StartupDialog class in the example application.

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 SecsEquip 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 SecsEquip software and made public to support custom requirements.  The return value is an RcResult 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. 
void terminalDisplayAck() Calling this method posts the data collection event named TerminalServicesOperatorAck which is used by the equipment to indicate acknowledgment of a host Terminal Display.
void traceWin(boolean show);
void traceWin(boolean show, boolean allowLogging)
The SecsEquip 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 show 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. 
String tsnI8Value(long int64) This method is no longer needed, ordinary decimal notation can be used for 8 byte signed (I8) or unsigned (U8) values.
void varGroupSet(int [] varIDs, String [] values)
This method is a more efficient alternative to calling variableSet() multiple times, the method sends the updated values to the SECS Server in one message.
Tip: Define static final int values for your variable IDs so you can use symbolic names.
void varGroupSetEventPost(int [] varIDs, String [] values, int CEID)
This method is a more efficient alternative to calling variableSet() multiple times and then posting a Data Collection event using eventPost().  The method sends the variable values and posts the event using one message to the SECS Server which provides better data integrity and better performance.  The array of varID values should be the same length as the array of variable values, and the elements of each array should correspond by subscript value.

If the CEID value is less than 0, no event is posted, and the method is equivalent to varGroupSet(). 

The method is most efficient for applications which use the SECS Server ei_variable table to manage variable values instead of using VarValueRequest callbacks.   When callbacks are used, the event posting methods should be called directly.  They feature an optimization which queries the SECS Server for needed variable values and sends them in a single second message.
void variableAdd(int varID, String varname, String description, String varClass, 
   String valueTsn, String initialValue, String units) throws Exception
Use this method to add a Status Value variable (varClass == "SV") or a Data Value variable (varClass == "DVVAL").  Both classes of variables are available for the host to configure in event reports.  A DVVAL does not need to have a valid value, for example the alarm ID of the latest alarm when there have been no alarms.  The variable name value, varname, should start with an alphanumeric character or the underscore and not have trailing spaces.  The length limit is 256 alphanumeric ASCII characters including the underscore, hyphen, and internal spaces.  We suggest you use a single token CamelCase name, limit yourself to 32 characters, and make each name unique.  With the default checking of Id values, use varID values between 3000 and 9999. By default the current variable value is represented in the SECS Server's data table, and set by your logic calling variableSet().  You call variableMethodSet() to specify that your logic will manage the current value of the variable, and that the SECS server should obtain the current value using an evaluation callback.

If you have custom ID requirements, you can set the IdRangeChecked property false to disable varID range checking, and you can renumber existing Parameters and Variables using the variableRenumber method.

String variableGet(int varID)
String variableGetByName(String varname)
These methods are used to get the current value of a variable.  They use the same access logic that host requests use so they can test your custom value logic.  The return value is null if there is an error.  It is marginally more efficient to lookup the variable by the varID value.
VariableInfo variableGetInfo(int varID)
VariableInfo variableGetInfoByName( String varname)

public class VariableInfo {
 public int varID;
 public String varname;
 public String description;
 public String varClass;
 public String valueTsn;
 public String varmethod;
 public String units;
 public String minValue;
 public String maxValue;
 public String defaultValue;
}

These methods return the configuration information of a variable or parameter (ECV).
int variableRenumber(String varname, int newVarId) throws Exception This method is provided so that the ID values of the built-in variables and parameters (ECVs)  can be customized.  All of these data items are represented in the same table, and should be given unique numeric identifiers.  Use the method after restoring or configuring the connection type, and before enabling communication.  If the newVarId value is in use by a different variable, that variable is given a "temporary" varID value of the current value plus 1 million under the assumption that it will be renumbered as well.  After initialization, if variables are found with ID values greater than 1 million, they indicate that more than one variable has been assigned to the same ID value. 

A positive return value is a warning, and the value 0 indicates success.  In more detail, the return values and their meanings are:

0
The variable already has the desired ID, or the variable was renumbered successfully.
1
The newVarId was in in-use so the existing variable was renumbered to a "temporary" ID.
2 or more
The return value is the number of variables of this name that were found.  The extra table records were deleted and the surviving table record has the desired ID or was renumbered successfully.  This condition is not ordinarily expected.
Exception
If the varname does not identify an existing variable an exception is thrown.  Also, if the method does not succeed from an unexpected error such as a timeout, an exception is thrown.


void variableSet(int varID, String newValue)
void variableSetByName(String varname, String newValue)
These methods are used to update the value of a Status or Data Value variable whose current value is managed by the SECS Server in the ei_variable table.  You are either calling a Set method whenever the value of a SECS variable changes, or you have called variableMethodSet to specify a callback interface for the SECS Server to use.   It is marginally more efficient to lookup the variable by the varID value.
void variableMethodSet(int varID, VarValueRequestItf callback)

public interface VarValueRequestItf {
   // you reply with the current value
   public String varValueRequest(SecsEquip sp, int varID);
   }

You use this method to register a callback that is executed by the SecsEquip software when the value of a Status Value or Data Value variable is needed.  The callback is executed by a different thread than your main GUI thread, so be sure to use threadsafe programming techniques such as synchronized( ) statements.  See  the application example.

If the callback argument is null then any existing callback for the variable is unregistered and the method is updated so that the value is managed in the ei_varible table using variableSet().


Built-in Features

The table of contents link in the frameset viewer shows the SECS Equipment Built-in Features document for this section. Having a separate document shared with the multiple Equipment libraries helps us provide you with more accurate, detailed information.

License Terms

Subject to Change Without Notice

The Hume Java SecsEquip 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 SecsEquip software on systems that are not licensed as development systems.  Contact Hume Integration for more information.


Document Version

Date of last revision: $Date: 2023/08/28 20:39:17 $