The SecsHost class library provides a high-level start when deploying
Host SECS Interface software using Java.
Without any code development, the software is able to communicate with
GEM standard equipment, manage dynamic Event Reports, upload and
download
process programs, and manage automatic online initialization. The
library also imbeds extensive fallback logic that accommodates working
with non-standard and non-GEM compliant equipment. A supervisory
application is provided with source code that enables you to
interactively
configure and manage multiple Host interfaces. Application source
code is also provided for a Host Graphical User Interface (GUI), and
related
dialogs such as property editing, and a window to display detail on the
data that is being exchanged over the SECS interface. The
SecsHost
software operates with or without these windows being present - it is a
component that can be imbedded and deployed in an application of your
own
design. An application developer registers callback interfaces to
receive asynchronous inputs such as Event Reports, Alarm Reports, or
specified
SECS message types. The example application code demonstrates
using
these techniques without undue complexity. You can readily
understand
how to use the software and get on with building your own application,
or you can customize the application we provide to meet your own
requirements.
DMH_JAVA_TCLDIR=C:/usr/local/gem2/serverIn 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.
Coding is easier if you add the statement import com.hume.SECS.*;
to the import statements of your application source code. By
doing
this, the package name, com.hume.SECS, can be omitted from name
references. You will typically want to add the statements:
import com.hume.SECS.*;
import com.hume.DMH.*;
to make it convenient to use the SECS software and work with String
text that is structured as lists.
Your primary focus as a developer is using the class SecsHost. This class implements public methods to send and receive SECS messages, and manage a host SECS interface.
Here is the general flow of using and configuring the SecsHost:
SwingUtilities.invokeLater(new Runnable() {public void run() { GuiXXXUpdate(); }})
As general guidance, when you expect a string value, you will get a
two element list, of the form "A:n {this is n chars of text}". If
a string value does not have imbedded white space, it may be formatted
without braces, such as "A:8 OneToken". When you use the TclList.listElement
or split methods to parse the
text, they take care of parsing and
removing
surrounding braces for you. If an empty string is sent, you will
see a one element list, A:0.
For parsing lists or extracting items from TSN text, use the TclList class or the StringList class. The
StringList class is easier to use than the TclList because it does not
throw exceptions, but it does not have the static parsing methods that
TclList offers. To construct TSN text, the ListBuilder class is more efficient
and has more options than TclList or StringList. Use your context
sensitive help to display the API reference material for these
classes. The API reference is also online at the Hume website java
directory.
SECS has the notion of array data -
0 or more values of a given type. When you expect to receive a
single
numeric value, you receive a two element list, with the type code as
the
first element, such as "U4:1 290". You can also receive an empty
array "U4:0" or an array with more than one value as in "U4:3 0 1
2".
Binary data values are formatted using C-language hexadecimal integer
notation,
for example, "B:3 0x00 0x01 0x02". You can use the binToInt
method to convert these values to integer values. With received
data,
the type code has a length value appended to it after a colon.
With
data that you format for sending, the length information is optional,
the
data is parsed to determine the length. See the TSN.html
document for more details.
Semi Octal type code | TSN type code | Meaning & Examples |
00 | L | List, L, L:0, "L {A {atc 100}} {A 1.0.0}", "L:2 {L:2 {U4 200} {U4 210}} {B 0}" |
10 | B | binary - unsigned 8 bit data, "B 0", "B 1 2 3" |
11 | TF | boolean data, TSN type codes BL or BOOLEAN are also accepted as input, "TF 1" |
20 | A | Character string data. Traditionally this has meant
printable
ASCII characters but some implementations are sending any 8 bit
characters
including nulls using this type. "A {hello world}", "A hello" |
21 | J | Japan International Standard (JIS-8) encoded text. This format is not commonly used or supported because in the past the SEMI standards have failed to identify specific reference documents. |
22 | V1..VE | Variant data, also known as Localized Character Strings. Your unicode text is automatically converted into the chosen encoding. V1 is for Unicode 2.0, V2 is for UTF-8 encoding. See the TSN.html document for more details. "V1 {sent as Unicode}" |
30 | I8 | 8-byte signed integer, use hex notation for the value, "I8 0x123456789abcdf01" |
31 | I1 | 1-byte signed integer, "I1 -3" |
32 | I2 | 2-byte signed integer, "I2 99", "I2 15 -7 99" |
34 | I4 | 4-byte integer signed, "I4 -5" |
40 | F8 | 8-byte floating point, "F8 6.02e23", "F8 0.1" |
44 | F4 | 4-byte floating point, "F4 1.0" |
50 | U8 | 8-byte unsigned integer, use hex notation for the value, "U8 0x7fffffffffffffff" |
51 | U1 | 1-byte unsigned integer, "U1 0" |
52 | U2 | 2-byte unsigned integer, "U2 512" |
54 | U4 | 4-byte unsigned integer, "U2 979" |
Logic in your application can send SECS messages or initiate conversations using the sendSecsMsg method. For HSMS communication, if you are sending a message and not waiting for the reply, sendSecsMsg can be used from your GUI code without fear of making your GUI unresponsive. In some cases you need to wait for a SECS reply message. If you are using HSMS, under most circumstances, the reply or failure to reply will be resolved within a few seconds. The unusual circumstance is that you still have a TCP/IP connection so your send is successful, but then there is no reply, and you wait the full T3 period. If the risk of this delay is not acceptable, you can create a new thread, and use the new thread to perform the SECS conversation where you need to wait for the reply message.
For SECS-I serial communication, timing is somewhat different. With SECS-I there is no underlying TCP/IP connection that can signal the application when it is broken. So there is a higher risk of your sending thread being in an unresponsive wait to determine if a send is successful, and then in a longer wait to obtain the reply. So you may want to use a separate thread than your GUI thread to send SECS messages or conduct send-and-reply conversations.
Property Access | Description |
boolean isAutoInit() void setAutoInit(boolean autoInit) |
Configures whether the interface should execute initialization logic automatically when an online control state is established or re-established. Since the actions performed during initialization are configurable using other properties, most application will configure the individual actions, and leave this overall flag at its default value of true. |
boolean isAutoStart() void setAutoStart(boolean autoStart) |
Configures whether the interface should be started automatically with communication enabled. This property is used if the interface is created using the constructor method that accepts the property values as string array arguments. The default value is false. |
int getBAUD() void setBAUD(int baudrate) |
If you are using the SECS-I, RS-232 connection type, this property sets the baudrate of the serial port. The default value is 9600. If communication is already enabled, you have to make a connectTypeSerial() or connectTypeSet() call to use a changed value. |
String getCeidOffline() void setCeidOffline(String ceid) |
The event report identifier (CEID) that signifies that the equipment is transitioning to an off-line control state. This value is used by the logic that tracks the equipment control state. The default value is "4000". |
public Object clientData | The SecsHost class has a public clientData value that the example HostGui class uses. If you replace the HostGui class, you can use this as a pointer to your own application object. |
String getCommState() | Read-only value of your GEM Communication State. Possible values are DISABLED, ENABLED {NOT COMMUNICATING}, and COMMUNICATING. The StateChange event is used to obtain asynchronous notification of this property value change. |
int getConnectionType() void setConnectionType(int v) throws Exception |
Configures the basic choice of connection type. The value 0 means SECS-I RS-232, 1 means SECS-I terminal server, 1993 is for non-standard Draft HSMS, 1995 is for standard HSMS. The default is 1995. We suggest you use the connectType* methods to set the connection type rather than manipulating the properties directly. An exception is thrown if an inappropriate value is set. |
String getControlState() | A read-only value of the GEM Control State. Possible values are OFF-LINE and ON-LINE. |
int getDEVID() void setDEVID(int DEVID) throws Exception |
The SECS Device ID. An identifier imbedded in SECS header data usually left at the default of 0. The SecsHost software has adaptive logic to correct an improper value. Settable range is 0..32767. |
static DMHClientItf SecsConn.getDmh() | SecsHost instances use a shared connection to the DMH message system in order to communicate with the SECS server process. The connection instance is available in case you want to access it in your application. |
static String SecsConn.getDmhGroupName() | The DMH message system groupname used by the SECS server. The same groupname should be specified to the constructor of every SecsHost instance in the application in order to share the same SECS server process. |
String getHsmsHost() void setHsmsHost(String hostOrIpAddr) |
For an active HSMS connection, specifies the TCP/IP hostname or IP address of the equipment computer. The default value is "localhost". |
boolean getHsmsPassive() void setHsmsPassive(boolean passive) |
For an HSMS connection, whether the SecsHost plays the passive, TCP/IP server role. The default value is false since the usual role for the host is non-passive. |
int getHsmsPort() void setHsmsPort(int p) |
For an HSMS connection, the TCP/IP socket port number. Defaults to 5555. |
public static java.util.Hashtable<String,SecsHost> instances | There is a hashtable SecsHost.instances which is used to keep track of the existing SecsHost instances. The key values are the Name properties. |
boolean isMult() void setMult(boolean multipleReplies) |
A flag used only for SECS-I to specify whether the equipment can handle owing more than one reply at a time. The default value is true. |
String getName() | The SecsHost name passed to the constructor and used in the SECS server process as a Tcl command name, a global array name, and an identifier in SQL table records. |
boolean isPPbodyFileMode() void setPPbodyFileMode(boolean isFileMode) |
This boolean property controls whether S7F3 and S7F6 process program transfer messages are handled by direct data transfers to and from files bypassing handling the messages in memory. This avoids possibly large memory allocations and enables transferring process programs that are as large as the 16 meg limit of Stream 7. Setting the option also reduces the data that is seen by tracing and logging - only summary information can be seen in the diagnostics. The default value is false. It is recommended to set the option true if process programs sizes are as large as 1 meg. The mode is transparent to the Java application; the processProgramDownload and Upload methods work the same and the built-in SECS Server Stream 7 receiving with ValueChange notifications work the same irrespective of the PPbodyFileMode setting. |
String getProcessProgramDir() void setProcessProgramDir(String path) |
A pathname to the file system directory where Process Program files are located. The default value is the relative subdirectory "<Name>_recipes" of the directory where the SECS server is executing. Note that by default, each interface has its own directory for Process Program files. Reading this property returns the absolute directory path to the process program directory. The value can be set using a relative or absolute pathname. |
boolean areReportsCleared() void setReportsClear(boolean Clear) |
This boolean property controls whether to delete all existing event reports during initialization before defining new ones. When this value is false, the report definition logic deletes reports one at a time as each new report is defined to make sure the report ID is not in use The value can be set true to eliminate possible undesired event reports, or to have only a single deletion message sent when setting up new reports. The default is false. |
boolean areReportsEnabled() void setReportsEnable() |
Setting this boolean property true insures that all equipment based events are enabled for reporting during initialization. If the value is set false, only the events that are specifically configured with data reports or for being enabled are enabled. However, if there are no event reports configured, then all equipment based event reports are enabled irrespective of this property setting. So, the meaning of the property is to insure that all equipment based events are enabled, and the false value is not used for disabling event reports. The default value is true. |
int getRTY() void setRTY(int v) throws Exception |
SECS-I maximum send retry, range 0..31, default 3 |
String getSerialPort() void setSerialPort(String SerialPort) |
For a SECS-I connection, the serial port device such as "COM1". The default value is "COM1" on all platforms. POSIX platforms typically need a device name such as "/dev/ttyS0". |
String getSpoolInit() void setSpoolInit(String v) throws Exception |
Controls initialization of the equipment spooling of messages. The allowed values are PURGE, UNLOAD, or IGNORE. The default value is IGNORE. |
String getState() | A read-only value of the low-level connection state. Possible values include OFFLINE, LISTENING, and COMMUNICATING. You will see the OFFLINE state if the connection to the host is broken, or in the case of SECS-I implicitly broken by a conversation timeout. The StateChange event is used to obtain asynchronous notification of this property value change. |
static String getSupervisorDir() static void setSupervisorDir(String pathname) throws Exception |
The default directory for file system saving and
loading is where the SecsServer[.exe] program is found, or where the
Datahub SDK gem2/server directory is found. This property can be
set by a custom application in order to specify a different base
directory for file system writing and reading. The pathname
argument may be relative to the Java application working directory or an
absolute directory path specification. Use slashes for path
separators, for example, "C:/Users/cim/data". When used, the
property must be set before SupervisorStart() is called, and may only be
called once. Specifying a system environment variable,
HUME_SUPERVISOR_DIR, with the desired pathname works as an alternative
to using this method for applications that call the SupervisorStart()
method. Applications that directly instantiate SecsHost instances instead of calling SupervisorStart() can also use this property to specify the root working directory for file system writing and reading for all SecsHost instances. The property value must be set before instantiating any SECS connection instances. Here we assume these apps do not use the SecsHost() constructor that uses table rows from the supervisor startup table. |
int getT1() void setT1(int v) throws Exception |
SECS-I Inter-Character Timeout in milliseconds, range 100..10000, default 500 |
int getT2() void setT2(int v) throws Exception |
SECS-I Protocol Timeout in milliseconds, range 200..25000, default 10000 |
int getT3() void setT3(int v) throws Exception |
SECS Reply Timeout in milliseconds, range 1000..120000, default 45000 |
int getT4() void setT4(int v) throws Exception |
SECS-I Inter-Block Timeout in milliseconds, range 1000..120000, default 45000 |
int getT5() void setT5(int v) throws Exception |
HSMS Connect Separation Timeout - the delay between re-connection attempts in milliseconds, range 1000..240000, default 10000. The T5 timer value is also used for SECS-I host logic as a retry timer for communication attempts. |
int getT6() void setT6(int v) throws Exception |
HSMS Control Transaction Timeout in milliseconds, range 1000..240000, default 5000 |
int getT7() void setT7(int v) throws Exception |
HSMS Not Selected Timeout in milliseconds, range 1000..24000, default 10000 |
int getT8() void setT8(int v) |
HSMS Network Intercharacter Timeout, default value 5000. This value is not used. |
int getTraceBits() void setTraceBits(int traceBits) |
Used as a bitfield to control diagnostic trace information
for SECS
port activity which is passed to the application in the SecsTrace
event.
By setting specific bits, the corresponding output is turned on.
General Tracing: (TraceType = trace) Receive Tracing: (TraceType = rtrace) Send Tracing: (TraceType = strace) |
int getTraceLogMaxWidth() void setTraceLogMaxWidth(int ctChars) throws Exception |
This property allows setting an approximate maximum number of characters in text lines when saving Trace data to log files. Lines that are longer than the maximum are trimmed and a short explanation message is appended. The property helps you reduce the size of the log files when large Process Programs are transferred or other long data messages are logged. The value may be configured as 0 for no limit, or a value greater than or equal to 1000; the default is 4000. |
RcResult setTraceSaving(boolean save, boolean
compress, int
maxDayFiles, String saveDir, String zipCmd)
public class RcResult { boolean isTraceDataSaved() boolean isTraceDataCompressed() String getTraceSaveDir() int getTraceSaveMaxDayFiles() String getTraceSaveZipCmd() |
The toolset software has the configurable feature of
continuously saving
the SECS communication trace data to files - one file per day, up to a
maximum number per year, and optionally compressing the closed file
from
the previous day shortly after midnight. The setTraceSaving
method is used to reconfigure the logging feature with the various
properties
being set atomically in one call. The saving logic writes each day's
output
to a distinct file, in the directory named by the saveDir
argument.
The maxDayFiles argument controls how many day files are saved
per
year. It can be configured between 1 and 366. When file
saving
is initiated, the output filename is set to traceNNN.txt
where the NNN value is the current day of the year, 0 to 365,
modulo
the maxDayFiles value. If this file already exists and
has
been written to earlier in the same day, then the output is appended to
it, otherwise the file is created as a new file. Note that if the maxDayFiles
value is set to 1, each day's output is saved to the same filename, trace000.txt.
The default values provide for saving the data from each connection in
a separate directory. Separate directories are required for each
connection. When trace data is being written, the compress
argument controls whether the logic attempts to compress the output
file
when it is closed at the end of the day (midnight). For
compression
to occur, the maxDayFiles value must be greater than 1 and a
non-blank
compression command must exist as the zipCmd argument.
The
default assignment of zipCmd is similar to zip -m tracetxt.zip.
This command causes the data file from the previous day to be moved
into
the tracetxt.zip archive, creating the archive if it does not
exist.
The compression logic appends the day file name to the configured
command
before execution. Only trusted persons should be allowed to
configure
the compression command because of the security considerations.
The RcResult return value is used as follows. If the rc value is less than 0 the setTraceSaving() arguments were not acceptable and an error message is provided as the result String. If the rc value is 0, the call succeeded. If the rc value is greater than 0, the call succeeded with an advisory message as the result String. For example, a message occurs if compression is set true but there is a maximum of only 1 file, so there is no distinct file for the previous day to compress. |
int getTracewinMaxWidth()
void setTracewinMaxWidth(int ctChars) throws Exception |
The approximate maximum number of characters to display in a single line of the trace window. This value guards against excessive data use when long messages such as recipe transfer occur and the trace window is displaying connection activity. Range 1000..120000, default 4000. |
String gettDATAID() void settDATAID(String tsntype) throws Exception |
The SECS TSN type code for DATAID items. Defaults to U4. |
String gettDATALENGTH() void settDATALENGTH(String t) throws Exception |
The SECS TSN type code for DATALENGTH items. Defaults to U4. |
String gettLENGTH() void settLENGTH(String tsntype) throws Exception |
The SECS TSN type code for LENGTH items. Defaults to U4. |
String gettPPID() void settPPID(String tsntype) throws Exception |
The SECS TSN type code for PPID items. Defaults to A. |
String gettREPGSZ() void settREPGSZ(String tsntype) throws Exception |
The SECS TSN type code for REPGSZ items. Defaults to U4. |
String gettRPTID() void settRPTID(String tsntype) throws Exception |
The SECS TSN type code for RPTID items. Defaults to U4. |
String gettTOTSMP() void settTOTSMP(String tsntype) throws Exception |
The SECS TSN type code for TOTSMP items. Defaults to U4. |
String gettTRID() void settTRID(String tsntype) throws Exception |
The SECS TSN type code for TRID items. Defaults to A. |
boolean isS1F3InUse() void setS1F3InUse(boolean b) |
Whether to use the Stream 1, Function 13 (S1F3) message type during initialization to query Status Variable values. After initialization, subsequent value changes are ordinarily known to the host by being received in event reports. The default value is true. |
boolean isS1F11InUse() void setS1F11InUse(boolean b) |
Whether to use S1F11 during initialization to determine Status Variables. Since the set of variables does not ordinarily change, and can be loaded from saved data, the initialization query can be disabled if it is time consuming. The default value is true. |
boolean isS1F13InUse() void setS1F13InUse(boolean b) |
Whether to use S1F13 during initialization to establish communications. The default value is true, and is almost always appropriate since the logic will use S1F1 if S1F13 is rejected. However, there is some defective equipment in use that gets confused if it receives S1F13. |
boolean isS1F17InUse() void setS1F17InUse(boolean b) |
Whether to use S1F17 during initialization to request the Online Control State. The default value is true. |
boolean isS1F21InUse() void setS1F21InUse(boolean b) |
Whether to use S1F21 during initialization to query Data Value Variables (DVVALS). The message type is not supported by older equipment. The default value is false. |
boolean isS1F23InUse() void setS1F23InUse(boolean b) |
Whether to use S1F23 during initialization to query Data Collection Events. The message type is not supported by older equipment. The default value is false. |
boolean isS2F13InUse() void setS2F13InUse(boolean b) |
Whether to use S2F13 during initialization to query Equipment Constant values. The default value is true. |
boolean isS2F29InUse() void setS2F29InUse(boolean b) |
Whether to use S2F29 during initialization to determine Equipment Constants. The default value is true. Since the set of constants does not ordinarily change, and can be loaded from saved data, the initialization query can be disabled if it is time consuming. |
boolean isS2F31InUse() void setS2F31InUse(boolean b) |
Whether to use S2F31 during initialization to synchronize the equipment clock. The default value is true. |
boolean isS5F5InUse() void setS5F5InUse(boolean b) |
Whether to use S5F5 during initialization to determine Alarm types. The default value is true. This query is not used during every initialization. It is only used if the logic sees an enabled alarm type that it does not already know about. |
boolean isS5F7InUse() void setS5F7InUse(boolean b) |
Whether to use S5F7 during initialization to determine enabled Alarms. The default value is true. |
boolean isS13InUse()
void setS13InUse(boolean b) |
This boolean property chooses whether to enable using Stream 13 large process program transfer message types. In addition to the Stream 13 messages, this property also enables or disables using S7F27, S7F29, S7F37, S7F38, S7F41, and S7F42 which are used with Stream 13 for transferring large unformatted, process programs. The default value is true which causes an S13F9 reset message to be sent during initialization. Stream 13 message types are preferred for transferring large data sets because the data is split into multiple smaller messages which require less memory use. |
Event Handler and Argument Data | Description |
All event handlers - NOTES
|
Java supports callback functions through the use of interface
declarations. You declare a class as implementing a particular
interface
type. Then you are able to pass references to instances as
arguments
to indicate the object which should be notified by the callback.
If this is new to you, take a close look at our example application
code.
The Interfaces we use are declared in separate java files, each named for the Interface type name, in the com.hume.SECS directory. We have adopted the convention of appending Itf to interface type names to make it easy to identify which files contain interface declarations. Unless noted otherwise, you should assume that the callback method is executed by a different thread than the main GUI thread of your application. See the notes on threading in the Development section above. When the event happens, your callback interface method is called. |
public interface AlarmReportItf { public void alarmReport(SecsHost sh, String alid, boolean is_set, String altx, String clock); } public AlarmReportItf AlarmReportHandler;
|
Set the AlarmReportHandler variable value to your
application
object to receive Alarm Reports.
This event is raised upon receiving an S5F1 alarm report message. Modern GEM equipment posts events for alarm set and alarm clear conditions so the idea of alarms as distinct from events is becoming obsolete. |
public interface EventReportItf { public void eventReport(SecsHost sh, String CEID, String EventID, java.util.HashMap<String,String> dataItems); } public EventReportItf EventReportHandler=null; |
Set the EventReportHandler variable value to your
application
object to receive Event Reports based on SECS messages S6F11, S6F13,
Trace
Reports (S6F1), and various events synthesized by the software such as
COM_DISABLE.
Use the eventReportDefine
method to
create data collection event reports. Your application needs to
call
the initialize method after defining the
desired
event reports to setup and enable the desired event reports with the
equipment.
Events can be given meaningful names and descriptions using the eventUpdate method. In the event report data, you receive both the underlying event identifier sent by the equipment, the CEID value, and the identifier for the event you have optionally customized, the EventID. If you have not provided a custom name for an event type, the EventID default value is the same as the CEID value. The data of the event report is passed as a HashMap instance which contains variable name and value pairs. The variable names are from the VFEIname column of the SECS server ei_variable table. You are able to assign your own variable names using the variableUpdate method. Using host specified names for variables allows the logic to ensure that each name is unique, and provides for uniform naming across equipment instances. If you do not provide your own name values for variables, the default variable names are assigned using the naming conventions of the Sematech Virtual Factory Equipment Interface (VFEI) standard. The ability to rename events and variables is referred to as Virtual Reporting. The default
names for
variables are computed as follows. The variable names defined by
the equipment are folded to uppercase, with white space and
non-alphanumeric
letters being replaced by underscores. Hyphens are not changed.
An
underscore is inserted for each transition from lowercase to
uppercase
in the equipment provided name. If the computed name is not
unique
for the equipment instance, the name is made unique by concatenating an
underscore and the variable ID. For example, the equipment
variable
name PPExecName is assigned the default name PP_EXEC_NAME. The
following
8 computed names are exceptions to the naming algorithm and are
reassigned
based on the Sematech VFEI standard: |
public interface SecsMessageReceiveItf { public void secsMessageReceive(SecsConn sp, int stream, int func, boolean sendReply, int transactionID, String data, String header); } |
See the messageTypeAdd method described in the next section to see how to receive SECS messages in your application. |
public interface SecsTraceItf { public void secsTrace(SecsConn sp, String traceType, String text); } SecsTraceItf onSecsTrace(SecsTraceItf handler) |
This event provides you with the detailed information of SECS
message
traffic that is viewed in the SECS Trace window - see the traceWin
method. The flow of information is controlled by setting
the
TraceBits property. You can cast the SecsConn argument to a
SecsHost
if you want to use a method that is defined by the SecsHost class and
not
the SecsConn base class.
Use the onSecsTrace() method to set your own handler. The return value is the previous handler which you are replacing. |
public interface ServerErrorItf { public void serverError(String message); } ServerErrorItf onServerError(ServerErrorItf handler) |
The SecsConn class reports Tcl programming errors that are
trapped
in the SECS Server process as ServerError events. An example
would
be trying to send an improperly formatted SECS message. These
error
events will happen during development but should be rare once the code
is debugged. In addition, there are optional debugging messages available to troubleshoot the initial connection to the SECS Server background process at startup. When the first SECS connection instance is instantiated, a SECS Server background process is started, and the application is usually able to setup DMH communication with the SECS Server within a few seconds. In an uncommon situation such as computer system that is running low on resources, the connection setup may require more time. The timing and retry logic is optionally affected by defining and setting the following environment variables: DMH_CONNECT_DEBUG=1 Define and set this environment variable to 1 to obtain connection debug events. Debug events provide diagnostic messages for each connection attempt. They show the timing and the error messages of failed attempts. DMH_CONNECT_WAIT=milliseconds This variable can be defined and set to the desired number of milliseconds of waiting per connection attempt. The default is 500. The value may be set from 1 to 60000. DMH_CONNECT_RETRY=maxAttempts This environment variable can be defined and set to the desired maximum number of communication attempts. The default is 20. The value may be set from 1 to 100. See the dmhConnect method coded in the SecsConn.java file for more details. Note that the DMH_CONNECT_* environment variables can be defined and set on a deployed system to affect the startup timing without making code changes, and without having coded an error event handler. This is a new feature of the software as of January 2016. Use the onServerError() method to set your own handler. The return value is the previous handler which you are replacing. |
public interface ValueChangeItf { public void valueChange(SecsConn sp, String name, String newvalue); } ValueChangeItf onStateChange(ValueChangeItf handler) |
This event notifies your application of state value changes.
Possible varname
values include
Use the onStateChange() method to set your own handler. The return value is the previous handler which you are replacing. |
METHOD | DESCRIPTION |
General Comments
|
The SecsHost class extends the SecsConn class. Public
methods
of both classes are shown here for convenience.
The TclList class is documented with the Hume Java classes for DMH communication. |
RcResult alarmAdd(String ALID, String ALTX, String
ID_TSN)
public class RcResult { |
This method is used to manually add alarm definitions for
equipment
that does not support discovery of alarm types using S5F5. The ALID
argument value is the alarm type identifier which is usually an
integer.
The ALTX argument is static text for the alarm description and
it
is limited to 40 characters in length. The ID_TSN
argument
is the SECS item data type for the ALID in TSN
notation such as U4.
If the method succeeds, the rc field in the result structure
is set
to 0. It is not an error if the alarm definition already exists, the
argument
values are used to update the existing definition. A non-zero
result
indicates an error, and the result string should be examined.
Possible
error return codes include: |
void alarmEnable(String ALID, boolean is_enabled) | Enable or disable reporting of an Alarm type (S5F1). |
boolean alarmIsEnabled(String ALID) | Test if the reporting of an alarm type is enabled |
boolean alarmIsSet(String ALID) | Test if the alarmed state is currently set |
HubTableModel alarmTable() | This method returns current data from the SECS Server ei_alarm table for the SecsHost instance. The columns of the table include: spname, ALID, is_enabled, is_set, ALTX, host_managed, and host_wants_enabled. The HubTableModel extends the Java swing AbstractTableModel and includes a refresh() method. It can easily be displayed in a JTable. |
int binToInt(String binValue)
|
Converts a SECS B (Binary - Semi "10") data value usually formatted as a hexadecimal string to an integer value. |
void commDisable() | Disable SECS communication. The SecsHost is initialized without communication enabled so using this method only makes sense after CommEnable has been called. |
RcResult commEnable()
public class RcResult { |
Enables SECS communication. The CommState
property value will change and StateChange
events
will be received. These changes are the asynchronous indications
for success or failure to establish communication. You may want
to
display the trace window in order to see
detailed information on the status of communication attempts. If
there is an error setting up the connection, the return code value will
be non-zero, and the result field will be an error message. |
RcResult connectTypeHsmsActive(String host_or_ip, int port) | This method is an alternative to setting the underlying property values to specify an active HSMS connection type, and calling connectTypeSet(). |
RcResult connectTypeHsmsPassive(int port) | This method is an alternative to setting the underlying property values to specify a passive HSMS connection type, and calling connectTypeSet(). |
RcResult connectTypeSerial(String comDevice, int baudrate) | This method is an alternative to setting the underlying property values to specify a SECS-I connection type, and calling connectTypeSet(). |
RcResult connectTypeSet()
public class RcResult { |
This method is called to use the current property values and initialize a SECS interface for the indicated connection type. It is called by the connectType<Type> methods. If you are setting connection property data directly, call this method after your property values are set. The method returns the value 0 to indicate success. If communication is enabled when this method is called, it becomes disabled as a result of setting up the new connection. If the return code value is not 0, then an error message is provided in the result field. |
RcResult connectTypeTerminalServer(String host_or_ip, int port) | This method is an alternative to setting the underlying property values to specify a SECS-I connection type over a TCP/IP terminal server connection and calling connectTypeSet(). |
void controlStateOffline() | This method sends a S1F15R message to request the offline control state. |
int controlStateOnline() | This method sends a S1F17R message to request the online control state. If the return value is 0 or 2 the online state is indicated. |
void copy(SecsHost dest) | This method copies the configurable SecsHost property values to another instance. |
String copyAll(SecsHost dest) | This method calls copy() to copy the current property values to another instance, and it also copies table records of events, event reports, alarms, variables, etc in the SECS Server to the destination instance. The return value is a String formatted as a list of two integers - the total number of table rows found, and the number of rows copied. In normal circumstances, the two values are equal. |
void debugDMHStatus(boolean show) | This method causes the DMH message system status window to either be shown or dismissed. |
void debugInspect() | This method can be used to exec the Inspect introspection debugger if the Datahub SDK has been installed.. |
void debugTableWindow(boolean show) | This method causes the Datahub table management GUI to be shown or dismissed. |
void debugTclConsole(boolean show) | This method causes a console window for the SECS Server to be shown or dismissed. |
void debugTraceWindow(boolean show) | This method is used to display a window which updates to show SECS message traffic and state information for the connection. There are menu options to control the data displayed, and menu actions to save the displayed data to the file system. This method invokes the Tcl version of the Trace window which is created by the SECS Server process. See the traceWin method to instantiate a native Java window with similar function. Making the Java version available in your application is desirable to help diagnose communication problems. |
void delete() | Java will not delete and finalize a SecsHost instance automatically because a reference to each instance is kept in the static instances hashtable. So we have provided a delete method that should be called when an instance is no longer needed. The delete method disables communication as well as deleting data structures and resources used by the instance. |
RcResult eventAdd(String CEID, String ID_TSN,
String eventName,
String description) public class RcResult { |
This method is used to manually add event definitions for
equipment
that does not support discovery of event types. The CEID
argument
value is the event type identifier which is usually an integer.
The ID_TSN
argument is the SECS item data type for the CEID in TSN
notation such as U4. The eventName argument is a virtual
name
for the event type defined by the user. The desciption
argument
can be used to provide guidance in selection lists. If any of the
arguments ID_TSN, eventName, or desciption are
provided
as null or empty strings, then default values are used: U4 for ID_TSN,
and the CEID value as a string for the eventName.
If the method succeeds, the rc field in the result structure
is set
to 0. No error occurs if an event definition with the same CEID
already
exists - the other fields are updated per the call arguments. A
non-zero
result indicates an error, and the result string should be
examined.
Possible error return codes include: |
String [] eventChoice() | This method returns an array of {CEID EventName Description) String values of event types that do not currently have an associated event report. The method is used to help implement the GUI feature of new report creation. |
Equipment Constant Update see parameterUpdate | Equipment Constant is a misnomer. |
int eventDiscovery() | The SECS-II standard does not provide a way to discover equipment events. This method is called to attempt event discovery by enabling all events and asking the equipment which events are enabled. This technique requires that the equipment support the underlying message types and implements an EventsEnabled variable that has the expected name. A positive return value indicates the number of new event types discovered. Negative return values indicate various failure modes. |
int eventsEnable() int eventsEnable(String CEIDlist, boolean is_enabled) |
Called with no arguments, eventsEnable requests that the equipment enable all event reports. By providing arguments, you can request the enabling or disabling of selected events. The SecsHost automatically enables the reporting of events for which you have configured event reports during online initialization. A negative return value indicates an unexpected internal error. The value 0 means success, and 1 means at least one of the events does not exist. |
boolean eventIsHostEnabled(String CEID) | Test if reporting of an event type has been configured in the SecsHost software to be enabled during the initialization logic. |
boolean eventIsReported(String CEID) | Test if the reporting of an event is currently established with the equipment. |
String [] eventReportConfig(String virtualName) |
This method returns a four element String array for the
configuration
of an event report. The elements are CEID, virtualName,
Description,
and Variables. Use TclList.split() to split the Variables element
into a String array of the individual virtual variable names. A
null is returned in case of error.
Use the ReportModel class of the example application for a table of the existing EventReport configurations. |
public String[] eventReportConfigEx(String virtualName) | This method returns a five element String array for
the
configuration
of an event report. The elements are CEID, virtualName,
Description, Variables, and RPTID. Use TclList.split() to split
the Variables element
into a String array of the individual virtual variable names. The
RPTID value is an empty string if there is no SECS Report ID
associated with the event or if the associated RPTID is the same as the
CEID. A
null
is returned in case of error. Use the ReportModel class of the example application for a table of the existing EventReport configurations. |
int eventReportDefine(String eventName, String []
varNames) int eventReportDefine(String eventName, String [] varNames, String secsRptID) |
Create or update an event report configuration. An event report is a set of variable values that is sent from the tool using S6F11 or S6F13 when the tool control state is online and a particular event occurs. This method configures SECS server table data that represents a desired report, data that links the specified event to the report, and data that indicates that the event should be enabled for reporting. The desired configuration of event reporting is communicated to the tool using S2F33, S2F35, and S2F37 when the initialize method is called, or whenever the tool enters an online control state and automatic initialization is enabled. The eventName argument is the virtual name of the event which can be configured to be different than the CEID value by using the eventUpdate method. The varNames argument is an array of the virtual names of the variables whose values are to be reported when the event occurs. The method variableChoice provides a current list of virtual variable names. You can use the variableUpdate method to provide your own virtual variable names. The default virtual variable names are assigned per the conventions of Sematech as explained in the EventReport Event section above. After calling this method, you may want to call the initialize method to have your desired event reports setup immediately and enabled with the equipment. The initialization logic is executed automatically whenever an online control state is established if the AutoInit property is true. For a less complex application, you may wish to define a distinct event report for each equipment event type that you wish to receive in the application. With the simplest form of this method call, you do not specify the optional SECS Report ID (RPTID) value, and by default the logic creates a distinct event report using the CEID value as the underlying RPTID value. It is possible to apply a single call to this method to more than one tool event by assigning the same virtual event name value to multiple tool events. The virtual event name value is assigned using the eventUpdate method. When this event naming trick is used and the SECS RPTID value is not specified, the like named events are configured to have separate and equal report definitions using their CEID values for RPTID values. The SECS Report ID (RPTID) value needs to be specified for certain less capable equipment that are not able to use the CEID values for RPTID values. There is at least one tool type that only allows RPTID values from 1 to 255 (type U1) but has CEID values outside of this range. Specifying the RPTID value can also be useful to apply a single event report definition to more than one event type. If this is done, the latest update of the event report definition is applied to all of the events that are associated (linked) to the specified RPTID. So specifying a common RPTID can be used to reduce the editing needed to manage and update a set of similar event types. A knowledgeable user can skip using this API and use SECS messages directly to fully exploit the ability to re-use event report definitions with multiple tool events and to have more than one event report definition linked to a tool event. This API only configures 1 or 0 event reports per tool event. The method returns 0 for success, -1 if the eventName is not known, -2 if a variable is not known, or -3 if the specified or defaulted RPTID value is not compatible with the tRPTID property. |
void eventReportDelete(String eventName) | Delete an event report configuration. |
String eventUpdate(String CEID, String eventName, String description) | Assign or update the virtual event name and description for an event type. Per the SECS-II standard, events use integer values for identifiers. There is no standardization of values. You are able to provide meaningful names and descriptions for events. You can use this feature to great advantage and create virtual equipment drivers with standard event and variable names. If the description value is passed as null, the current value for the event is not changed. |
int initialize() | Performs online initialization which enables communication
and sets
up event reports. Initialization is controlled by your settings
of
property values, and configured items. It optionally includes:
The return value is 0 for success. Error return values
include:
-1 TIMEOUT, 1 communication failed, 2 not online, 3 clock set, 4
setting
of Eq. Constants, 5 disabling of events & reports, 6 event &
report
enabling, 7 alarm management, 8 Spool init, or ei_custom_init error. |
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. 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 { |
Call messageTypeAdd() to have SECS messages processed
by your
custom handler methods when the SecsHost has established communication
with the equipment. The callback argument specifies your
application
object that implements the SecsMessageReceiveItf interface.
You can provide for new SECS message types, or you can replace the
built-in
handling of particular messages. For example, you could take over
the handling of S6F3 discrete data reports for equipment that uses
non-standard
formats. Use the sendReply, sendS9,
and sendAbort methods to send reply messages.
The arguments passed to your SecsMessageReceive method
are: |
void messageTypeRemove(int stream, int function) | This method is used to cancel SECS message handlers that you have setup using messageTypeAdd() or to cancel the handling of particular messages by the built-in SecsHost logic. If you have called messageTypeAdd for the specified message type, the Add is cancelled. If you have not called messageTypeAdd, the SECS server is told not to handle the message. Unhandled primary messages are replied to with an abort reply. |
RcResult parameterAdd(String varID, String ID_TSN,
String value_TSN,
String varName, String virtualName, String description)
public class RcResult { |
This method is used to manually add parameter (ECV)
definitions for
equipment that does not support discovery of them using S2F29.
The varID
argument value is the parameter identifier which is usually an
integer.
The ID_TSN argument is the SECS item data type for the varID
in TSN notation such as U4. The value_TSN
argument is the data type of the parameter value in TSN
notation
such as "F4". The varName argument is a name for the
parameter
as defined by the equipment. The virtualName argument is
a
name for the parameter chosen by the user. The desciption
argument can be used to provide guidance in selection lists. If
any
of the arguments ID_TSN, varName, virtualName,
or desciption
are provided as null or empty strings, then default values are
used:
U4 for ID_TSN, the varID value as a string for
the varName, and programmatic mapping of the varName value
for the virtualName.
If the method succeeds, the rc field in the result structure
is set
to 0. No error occurs if a definition with the same ID already
exists
- the other fields are updated per the call arguments. A non-zero
result indicates an error, and the result string should be
examined.
Possible error return codes include: |
RcResult parameterUpdate(String varID, String
newValue)
public class RcResult { |
Use this method to set the value of an Equipment Constant. The return value is 0 for success, -1 and an error message if improper data is used, 1 if the variable does not exist, 2 if the equipment refuses to change the value at present, and 3 if the equipment rejects the new value. |
String [] processProgramList() | Obtain the current list of process programs using S7F19R. The return value is null in case of error such as the equipment not being online or not supporting S7F19. |
RcResult processProgramDownload(String pathname)
public class RcResult { |
Download a process program to the equipment using Stream 7
messages. The process program must be in the process program
directory. If there is no saved table record in file ei_ppid.tab describing the process
program file, the logic assumes that the file format contains both the
PPID and PPBODY in text TSN notation which was the upload format used
prior to May 2008. The return
value
of the method call is a two element structure, a return code and
text. The return
code
is 0 for success, in which case the text will be the PPID (the process
program name). Possible error codes include: -1 unexpected transaction error -2 file not found -6 SECS transaction error -10 file open or read error -11 no upload description data and the file data is not consistent with the older upload format |
RcResult processProgramLargeRequest(String ppid) | This method initiates the upload
of a process program to the host
using the message types of Stream 13 which are designed for large data
set transfers. Using these messages is more complex than the
usual
Stream 7 transfer messages so they are less commonly supported.
The ppid
argument value is the process
program
identifier used by the equipment. The upload logic saves only the
data passed as the body of the
process program in the uploaded file. The ppid value used to identify
the process program may not be a valid filename. The upload logic
assigns a unique filename to the uploaded program, using the ppid value
if possible. The logic also creates or updates a file of SQL
statements, ei_ppid.tab, in
the process program directory. The ei_ppid.tab file saves the ppid
value to filename mapping, as well as the datatype of the transferred
program. The ei_ppid.tab file has to be preserved along with the
uploaded process programs in order to download them in the future. The return value is a two element structure, a return code and text. The return code is 0 if the transfer is initiated successfully as determined by the reply to S7F41. The transfer is not complete when the method returns. The large data set transfer logic receives the file in the subdirectory, dataset_transfer, of the directory set by the ProcessProgramDir property. When the transfer is complete, if there is already an earlier version of the process program file in the process program directory, then there is a StateChange event with the name dataset_delete and the newvalue being the ppid value, which informs you that the earlier version file is being replaced. Next, there is a StateChange event with the name dataset_upload and the newvalue being the ppid value which informs you of the successful upload completion. Proper GEM equipment will also post UploadSuccess or UploadFailure data collection event reports to indicate completion as well. If the transfer does not complete successfully, there is additional status information is the SECS server table ei_dataset_xfer. It is possible to query this table or subscribe to data changes of this table to better integrate transfer status information. Possible error results include values of the ACKC7 reply to S7F41 and the following: 1 permission not granted 4 PPID not found 6 other error -6 error when sending S7F41 or receiving the S7F42 reply -14 A large PP receive is already in progress for ppid -15 Stream 13 transfers are disabled either from configuration or initialization failure -17 error when parsing the S7F42 reply |
RcResult processProgramLargeSend(String filename) |
This method initiates the
download of a process program to the equipment using
the message types of Stream 13 which are designed for large data
set transfers. Using these messages is more complex than the
usual
Stream 7 transfer messages so they are less commonly supported.
The filename argument value
is the file name of a previously uploaded process program in the
process program directory. The file is expected to contain only
the data of a process program - this transfer method is not compatible
with the previously used upload format that saved both the PPID and
PPBODY in TSN notation. The filename
may not be the same as the process program identifier, ppid. The saved information
in the ei_ppid.tab file in the
ProcessProgramDir is checked for a
possibly different ppid.
The return value is a two element structure, a return code and text. The return code is 0 if the transfer is initiated successfully as determined by the reply to S7F37. The transfer is not complete when the method returns. After the data has been sent to the equipment, per GEM, the equipment is expected to verify the byte count of the download process program file using S7F29. When this verification occurs with the correct byte count, there is a StateChange event with the name dataset_download and the newvalue being the ppid value. If the transfer does not complete successfully, there is additional status information is the SECS server table ei_dataset_xfer. Possible error results include values of the ACKC7 reply to S7F37 and the following: 1 permission not granted 6 other error -4 PPID filename not found -6 error when sending S7F37 or receiving the S7F37 reply -14 A large PP receive is already in progress for ppid -15 Stream 13 transfers are disabled either from configuration or initialization failure -17 error when parsing the S7F38 reply |
RcResult processProgramUpload(String ppid)
public class RcResult { |
Upload a process program from the equipment to our process
program directory using Stream 7 messages.
The return value is a two element structure, a return code and text.
The
return code is 0 for success, in which case the text will be the
pathname
of the saved program. The upload logic saves only the data
passed as the PPBODY of the process program in the uploaded file.
The PPID value used to identify the process program may not be a valid
filename. The upload logic assigns a unique filename to the
uploaded program, using the PPID value if possible. The logic
also creates or updates a file of SQL statements, ei_ppid.tab, in the process program
directory. The ei_ppid.tab file saves the PPID value to filename
mapping, as well as the datatype of the transferred program. The
ei_ppid.tab file should be preserved along with the uploaded process
programs in order to download them in the future. A successful
upload causes a StateChange
event with the name recipe_upload and the newvalue being the ppid
value. If there is a prior version of the uploaded file in
the process program directory, there is a StateChange
event with
the name recipe_delete and the newvalue being the ppid
value which occurs before the recipe_upload
event. Possible error codes include 1 improper SECS message data 2 blank ppid in message data 3 unsupported PPBODY data type 4 file system error -1 unexpected transaction error -2 upload refused or failed |
public static SecsHost newSecsHost()
void SecsHost(String Name, String dmhGroup) void SecsHost(String spname, String [] cols, String []
row) |
The constructor. The Name argument becomes the
name of
a global data item and a Tcl command in the SECS Server process.
It needs to be unique for each SecsHost instance, and not coincide with
a keyword in the Tcl programming language. The default value of Name
is similar to host0. The name should be a single alphanumeric
token.
One of the constructor forms accepts property values as String arrays. This form is used by our example Supervisor application. Take a look at the source code for the SecsHost to understand the names used for the property values. Essentially there is a direct mapping of properties to column names in an SQL table, ei_startup, which is used to manage interface startup information. The dmhGroup argument becomes the DMH message system group name used by the SecsHost and SECS Server process. If you are instantiating more than one SecsHost instance in your process, construct each instance using the same dmhGroup name argument so that the SECS Server process is shared. The groupname chosen needs to be unique among other DMH server instances on the computer where the SecsHost is executing. The default value is GEMHOST. This value does not conflict with the default value for Hume Datahub instances which is mbx, or the default value for the GemEqApp which is GEM. The name should be a single alphanumeric token. The SECS Server process can be debugged remotely by connecting to the DMH mailbox SERVER_RPC@hostname:dmhGroup using the Inspect application or using the DMH mailbox SERVER_SQL@hostname:dmhGroup by the hubclient application. |
void sendAbort(int stream, int primaryFunction) | This method is used to send an F0 abort message in lieu of a proper reply. It is used to indicate that the received message is not appropriate in the current context. |
void sendReply(int stream, int function, int
transactionID)
void sendReply(int stream, int function, int transactionID, String TSN_data) |
This method is used by your custom SECS message handling logic to send reply messages either with or without data. The reply data is formatted as Tcl Secs Notation text. |
void sendS9(int function, String header) | This method is used to indicate an error condition response
to a received
message - it is sent in lieu of a normal reply. You will not
receive
a message type, unless you register for it. In general, host
software
has less of a need to send Stream 9 messages than equipment software. |
RcResult sendSecsMsg(int stream, int function,
boolean replyIsWanted,
String TsnData, boolean wait4reply)
public class RcResult {
|
These methods are used to send a primary SECS message,
optionally indicating
a reply is wanted, and optionally indicating that the call should wait
for a reply. A null or empty String value may be used for the TsnData
argument
when a header only message is to be sent. If a multiblock
enquire/grant
transaction is required for the message type, the SecsHost software
does
it automatically. The reply value for the sendSecsMsg()
method
is a a two element data structure. The first element is an
integer
code, and the second element is reply or diagnostic data. The
possible
return values are:
|
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:
|
static void SecsConn.serverSqlCmd(String sql) | Send an SQL command to the SECS Server process without waiting for a reply. This method is used by the SecsHost software and made public in case of custom requirements. |
static String SecsConn.serverSqlReply(String sql) | Send an SQL command to the SECS Server process and wait for the reply. This method is used by the SecsHost software and made public in case of custom requirements. |
static void SecsConn.serverTclCmd(String tclCommand); | Send a Tcl command to the SECS Server process without waiting for a reply. This method is used by the software and made public in case of custom requirements. After a connection instance has been constructed and the connection type set, the tclCmd( ) method should be used instead of this method for commands that are directed to a particular interface instance. Why? Doing so serializes the commands for a particular interface, and provides re-entrant execution protection. |
static String SecsConn.serverTclReply(String tclCommand); | Send a Tcl command to the SECS Server process and wait for the reply message. This call is used by the SecsHost software and made public in case of custom requirements. After a connection instance has been constructed and the connection type set, the tclReply( ) method should be used instead of this method for commands that are directed to a particular interface instance. |
static int SecsHost.superSave() | Save the SECS server table data including interface startup configurations. You can write your own applications with your own persistence mechanisms. Our example Supervisor application uses this method to save the state of the configured interfaces for the next session. |
static void SecsHost.supervisorStart (String DmhGroup) | This method is the startup call for our Supervisor
application example.
It restores data from the last SuperSave call, and instantiates all of
the configured interfaces. The interfaces that are configured
with autoStart
true, are enabled for communication. If the application has not called setSupervisorDir() a check is made for the existence of a system environment variable HUME_SUPERVISOR_DIR when this method is executed. If a value exists, the supervisorStart method sets the SECS Server working directory using the value before attempting to read or write application data. |
void tclCmd(String tcl) | This method is used to send Tcl code to the SECS server command mailbox for the connection. It is used by the SecsHost software and made public to support custom requirements. |
RcResult tclReply(String tcl)
public class RcResult { |
These methods are used to send Tcl code to the SECS server command mailbox for the connection and wait for the evaluation result. They are used by the SecsHost software and made public to support custom requirements. With tclReply() the return value is a structure. The first element is a return code for the evaluation with 0 meaning success. The second element is the return value from the executed Tcl code, or an error message if the return code is not 0. |
int traceSetup(String traceId, int periodSeconds, int totalSamples, int samplesPerReport, String SVIDs) | Control TRACE Reports - a convenience method to send the
S2F23R message.
If totalSamples is 0, the trace is disabled. If totalSamples
is greater than 0, you should insure that it is an even multiple of samplesPerReport.
The reporting period value specified in seconds, periodSeconds,
is subject to equipment limitations. The SVIDs argument
is
a white space delimited list of Status Variable identifiers. The
return values are 0 = success, 1 = too many SVIDs, 2 = no more traces
allowed,
3 = invalid period specified, -1 = error such as not being in online
communication,
-2 = at least one unknown SVID, -3 at least one variable is not a
Status
Variable (class SV).
The method also creates or updates event report configuration data so that the S6F1 trace reports are received as event reports with the CEID of TRACE_REPORT. When there are multiple samples per report, the event report logic parses the received data into multiple event reports, one per sample. In this situation you will usually want the CLOCK variable as one of the reported items to know the observation time of the sample. If you want to have more than one trace report series active at a time, then you can use the messageTypeAdd() method to register for the S6F1 messages and receive them directly without using the virtual event report receiving logic. |
void traceWin(boolean show); void traceWin(boolean show, boolean allowLogging) |
The SecsHost is able to instantiate and manage a window class, Tracewin, which provides a controllable display of the data being exchanged across the SECS interface. The argument is set to true to display the window, or false to close the window. There are menu options to provide hex dump formatting of the data, or higher level descriptive formatting. There are also menu actions to save the displayed data to the file system. The allowLogging argument controls whether there is a menu item which provides for configuring the continuous unattended saving of trace data to the file system. Since this feature has performance, disk usage, and security implications you may wish to restrict access to the configuration of logging. |
RcResult variableAdd(String varID, String ID_TSN,
String varName,
String virtualName, String description, String varClass)
public class RcResult { |
This method is used to manually add variable definitions for
equipment
that does not support discovery of them. The method can also be used to insure that variable definitions exist
and reports using them can be defined before initialization logic is
executed. The most common scenario is that initialization logic is run
and discovered data is saved by calling superSave() during a prior
session, and this method is not used. The varID
argument
value is the variable identifier which is usually an integer. The
ID_TSN
argument is the SECS item data type for the varID in TSN
notation such as U4. The varName argument is a name for
the
variable as defined by the equipment. The virtualName
argument
is a name for the variable chosen by the user. The virtualName should be unique. System assigned virtualName values are described above with the EventReport event description. If both the varName and the virtualName values are set to the varID value, the built-in initialization logic of processing S1F12 will replace the varName and virtualName values with system computed values. Therefore, provide a different varName value if you wish to use the varID value as the virtualName. The description
argument can be used to provide guidance in selection lists. The varClass
argument value is set to "SV" for Status Variables and "DVVAL" for Data
Value variables. If any of the arguments ID_TSN, varName,
virtualName,
or description are provided as null or empty strings, then
default
values are used: U4 for ID_TSN, the varID
value
as a string for the varName, and programmatic mapping of the varName
value
for the virtualName.
If the method succeeds, the rc field in the result structure
is set
to 0. No error occurs if a definition with the same ID already
exists
- the other fields are updated per the call arguments. A non-zero
result indicates an error, and the result string should be
examined.
Possible error return codes include: |
String [] variableChoice() | This method returns a list of variable names which are candidates for use in dynamic Event Report configuration. The names are the virtualName (VFEIname) values. A null value is returned in case of error. |
String variableGetId(String virtualNames)
String [] variableGetId(String [] virtualNames) |
These methods are used to map variable Virtual names assigned by using the variableUpdate method or assigned by default when the variables are first known, to the identifiers used by the equipment. The latter are typically integer values such as SVID's or ECID's. If called with a String argument, the virtualNames value may contain 1 or more white space separated names, and the result will be a white space separated list of the corresponding Ids. An empty result is returned for an unknown name value. If called with a String array argument, each array element is expected to contain a single name, and a String array result is returned for the corresponding Id values. |
HostVariableInfo variableGetInfo(String varID)
public class HostVariableInfo { |
This method returns the known configuration and value information of a variable or Equipment Constant Variable (ECV). A null result is returned for an unknown varID input value. The information comes from the replies to messages that are sent during the online initialization, from data received in event reports and trace reports, or from the restored table data of a previous session. |
String variableGetVirtualName(String Ids)
String [] variableGetVirtualName(String [] Ids) |
These methods are used to map variable identifiers which are typically integer values (SVID, ECID, etc) to the Virtual names assigned by using the variableUpdate method or assigned by default when the variables are first known. If called with a String argument, the Ids value may contain 1 or more white space separated Id values, and the result will be a white space separated list of the corresponding Virtual names. An empty name result is returned for an unknown Id value. If called with a String array argument, each array element is expected to contain a single Id, and a String array result is returned for the corresponding Virtual names. |
RcResult variableQuery(int varID) RcResult variableQuery(String varname) RcResult variableQueryVirtual(String virtualName) public class RcResult { int rc; // return code String result; } |
These methods are used to obtain
the value of a Parameter or Status Variable using the numeric or name
identifier. The varname
argument represents the name given the variable by the
equipment. Note that some equipment has the same variable
names used more than once. The variableQueryVirtual
method uses the virtual variable name as the argument value which is
unique for each variable. For the methods to succeed, you must be
communicating in an online state, and the variables must be known from
the replies that are received during online initialization to S1F11 and
S2F29. The variable data can either be discovered during the
current session, or known by loading variable data saved from a
previous session. If the method succeeds, the rc field in the result structure is set to 0. A non-zero rc result indicates an error, and the result string should be examined. Possible error return codes include: -1 unexpected error -2 communication is not enabled -3 unknown identifier (can occur if initialization queries have not been completed) -6 no reply TIMEOUT, abort reply, or Stream 9 error reply |
DataTable variableTable() | This method returns a current subset of the SECS server variable table for the SecsHost instance. The included columns are varID, varname, VFEIname, description, varclass, value_TSN, varmethod, varvalue, host_setval, host_managed, and t_latest. |
int variableUpdate(String varID, String virtualName, String description) | You are able to assign meaningful names and descriptions to the equipment variables using this method. The virtualName values are used in Event Report configurations and as the variable names in the Event Report event data. If the description field is passed as a null value, the current description is not changed. |
This section of the document has information on the built-in features
of the SecsHost software in regards to the SEMI E5 and GEM standards.
There is only one other variable record of note. The AUTO_INIT_RESULT variable exists to save the execution result when the initialization logic executes automatically. It is common to configure this variable to be part of the event report for the AUTO_VIRT_INIT event. This dynamic event report can be configured and received even if the underlying equipment does not support dynamic event reports. The event report is created and managed by the SecsHost software. There are three other events that are synthesized in the SecsHost software and presented to the application using the same mechanisms used to dispatch equipment based event reports. Here is a list of the built-in driver events:
Type | Sender | Data Format | Comments |
S1F1R | H, E | "Are You There?" | |
S1F2 | H | L | "On Line Data" |
S1F3R | H | L [<SVID>]* <SVID> := {U4 <varID>} |
"Selected Equipment Status Request" |
S1F4 | E | L [<SV>]* | "Selected Equipment Status Data" The data type of the SV value depends on the variable. |
S1F11R | H | L [<SVID>]* | "Status Variable Namelist Request" |
S1F12 | E | L [{L:3 <SVID> <SVNAME> <UNITS>}]+ | "Status Variable Namelist Reply" |
S1F13R | H,E | L | "Establish Communications Request" |
S1F14 | H | L:2 {B 0} L | "Establish Communications Request Acknowledge" |
S1F15R | H | "Request OFF-LINE" | |
S1F16 | E | <OFLACK> | "OFF-LINE Acknowledge" |
S1F17R | H | "Request ON-LINE" | |
S1F18 | E | <ONLACK> | "ON-LINE Acknowledge" |
S2F13 | H | L [<ECID>]* | "Equipment Constant Request" |
S2F14 | E | L [<ECV>]* | "Equipment Constant Data" |
S2F15R | H | L [{L:2 <ECID> <ECV>}]* | "New Equipment Constant Send" |
S2F16 | E | <EAC> | "New Equipment Constant Ack" |
S2F17R | H | "Date and Time Request" | |
S2F18 | E | A:16 YYYYMMDDHHMMSScc A:12 YYMMDDHHMMSS |
"Date and Time Data" |
S2F23R | H | L:5 <TRID> <DSPER> <TOTSMP> <REPGSZ> {L [<SVID>]+} | "Trace Initialize Send" |
S2F24 | E | <TIAACK> | "Trace Initialize Acknowledge" |
S2F25R | H,E | B [<b>]* | "Loopback Diagnostic Request" |
S2F26 | H | B [<b>]* | "Loopback Diagnostic Data" |
S2F29R | H | L [<ECID>]* | "Equipment Constant Namelist Request" |
S2F30 | E | L [L:6 <ECID> <ECNAME> <ECMIN> <ECMAX> <ECDEF> <UNITS>]+ | "Equipment Constant Namelist" |
S2F31R | H | A:16 YYYYMMDDHHMMSScc A:12 YYMMDDHHMMSS |
"Date and Time Set Request" |
S2F32 | E | <TIACK> | "Date and Time Set Acknowledge" |
S2F33R | H | L:2 <DATAID> {L [{L:2 <RPTID> {L [<VID>]*}]*} | "Define Report" |
S2F34 | E | <DRACK> | "Define Report Acknowledge" |
S2F35R | H | L:2 <DATAID> {L [<CEID> {L [<RPTID>]*}]*} | "Link Event Report" |
S2F36 | E | <LRACK> | "Link Event Report Acknowledge" |
S2F37R | H | L:2 <CEED> {L [<CEID>]*} | "Enable/Disable Event Report" |
S2F38 | E | <ERACK> | "Enable/Disable Event Report Acknowledge" |
S2F39R | H | L:2 <DATAID> <DATALENGTH> | "Multi-block Inquire" |
S2F40 | E | <GRANT> | "Multi-block Grant" |
S4F25R | H | L:2 <DATAID> <DATALENGTH> | "Multi-block Inquire" |
S4F26 | E | <GRANT> | "Multi-block Grant" |
S5F1R | E | L:3 <ALCD> <ALID> <ALTX> | "Alarm Report Send" |
S5F2 | H | B 0 | "Alarm Report Ack" |
S5F3R | H | L:2 <ALED> <ALID> | "Enable/Disable Alarm Send" |
S5F4 | E | <ACKC5> | "Enable/Disable Alarm Ack" |
S5F5R | H | <ALID vector> | "List Alarms Request" |
S5F6 | E | L [{L:3 <ALCD> <ALID> <ALTX>}]* | "List Alarm Data" |
S5F7R | H | "List Enabled Alarm Request" | |
S5F8 | E | L [{L:3 <ALCD> <ALID> <ALTX>}]* | "List Enabled Alarm Data" |
S6F1 | E | L:4 <TRID> <SMPLN> <STIME> {L [<SV>]+} | "Trace Data Send" |
S6F3[R] | E | L:3 <DATAID> <CEID> [{L:n {L:2 <DSID1> {L:m [{L:2 <DVNAME> <DVVAL>}]*}}]* | "Discrete Variable Data Send" |
S6F4 | H | B 0 | "Discrete Variable Data Ack" |
S6F5R | E | L:2 <DATAID> <DATALENGTH> | "Multi-block Data Send Inquire" |
S6F6 | H | B 0 | "Multi-block Grant" |
S6F11R | E | L:3 <DATAID> <CEID> {L [{L:2 <RPTID> {L [<V>]+}}]+} | "Event Report Send" |
S6F12 | H | B 0 | "Event Report Ack" |
S6F13R | E | L:3 <DATAID> <CEID> {L [{L:2 {U4 <rptid>} {L [{L:2 {U4 <vid>} <V>}]+}}]+} | "Annotated Event Report Send" |
S6F14 | H | B 0 | "Annotated Event Report Ack" |
S6F23R | H | <RSDC> | "Request or Purge Spooled Data" |
S6F24 | E | <RSDA> | "Request or Purge Spooled Data Ack" |
S7F1R | H,E | L:2 <PPID> <LENGTH> | "Process Program Load Inquire" |
S7F2 | E,H | <PPGNT> | "Process Program Load Grant" - The SecsHost always sends B 0. |
S7F3R | H,E | L:2 <PPID> <PPBODY> | "Process Program Download" |
S7F4 | E,H | <ACKC7> | "Process Program Download Acknowledge" |
S7F5R | H,E | <PPID> | "Process Program Upload Request" |
S7F6 | E,H | L:2 <PPID> <PPBODY> | "Process Program Upload Data" |
S7F19R | H | "Current Process Program Dir Request" | |
S7F20 | E | L [<PPID>]* | "Current Process Program Data" |
S*F0 | abort replies are handled as a special case of reply | ||
S9F1 | E | <MHEAD> | "Unknown Device ID" - The SecsHost has logic to automatically correct this error when first establishing communication. |
S9F3 | E | <MHEAD> | "Unknown Stream" |
S9F5 | E | <MHEAD> | "Unknown Function" |
S9F7 | E,H | <MHEAD> | "Illegal Data" |
S9F9 | E,H | <MHEAD> | "Transaction Timeout" T3 timeout |
S9F11 | E | <MHEAD> | "Data Too Long" |
S10F1 | E | L:2 {B 0} {A <text>} | "Terminal Request" the example application handles this message type |
S10F3R | H | L:2 <TID> {A <text>} | "Terminal Display, Single" |
S10F4 | E | <ACKC10> |
The Hume Java SecsHost software is licensed for development and runtime use at no additional charge for computers that are licensed for development use of the Hume Integration Datahub SDK.
Hume Integration is also pleased to offer separate runtime licenses for using the SecsHost software on systems that are not licensed as development systems. Contact Hume Integration for more information.
Date of last revision: $Date: 2022/09/17 17:02:10 $