Hume Integration has created a .NET component for rapidly deploying
SEMI standard GEM compliant SECS equipment interfaces. The
.NET component features a fully CLS (Common Language Specification)
compliant
API and can be used from any of the Microsoft .NET programming
languages,
including C#, C++, Visual Basic, and Java. Without any
customization,
the component 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 complement the existing items
specified
in the GEM standard. The developer uses event
handlers
to receive asynchronous inputs such as Remote Command invocations,
Terminal
Display invocations, or the reception of any SECS message type of his
choosing.
The Equipment OEM developer needs to be mindful of the standards
when using the Hume SecsPort Component 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 SecsPort
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
SecsPort 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 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 SecsPort component. |
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 SecsPort 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 GemGui 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 property value ControlIntentOnline. The desired substate of ON-LINE control, LOCAL or REMOTE, is settable as the 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 SecsPort StateChange event. |
ADDITIONAL CAPABILITIES | |||
Establish Communications | Yes | Yes | This behavior is fully provided by the SecsPort component. |
Dynamic Event Report Configuration | Yes | Yes | This behavior is fully provided by the SecsPort component.
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 SecsPort component. |
Trace Data Collection | Yes | Yes | This behavior is fully provided by the SecsPort component. |
Status Data Collection | Yes | Yes | This behavior is fully provided by the SecsPort component. |
Alarm Management | Yes | Yes | This behavior is fully provided by the SecsPort component. 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 SecsPort when you use the AlarmAdd method. |
Remote Control | Yes | Yes | The SecsPort defines an event, RemoteCommand which you use to receive Remote Commands (S2F21, S2F41, or S2F49) in your application code. You can use the MessageTypeRemove method to selectively not handle any of the Remote Command message types. 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 (ECV's) |
Yes | Yes | This behavior is fully provided by the SecsPort component. Your job is to add equipment specific ECV's 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 SecsPort component fully implements process program management features with upload and download capabilities. You can set the directory used for process programs as the property RecipeDirectory. You can set whether process program data is transferred as binary or text using the RecipesAreBinary property. Your application is notified of process program change events by handling the SecsPort 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 to receive each of the primary message types that the host sends. In your event handling logic, you parse the received SECS message data using the ListSplit and 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 SecsPort demonstrates displaying data received from the host, sending acknowledgment events, and sending display data to the host. For your own implementation, use the event TerminalDisplay with your own display logic, use the method TerminalDisplayAck to send acknowledgment events, and follow the example of the GemGui.BTerminalSend_Click method for sending input data to the host using SendSecsMsg. |
Clock | Yes | Yes | The SecsPort 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 SecsPort 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 method. The default behavior is to allow only Stream 5 (Alarms) and Stream 6 (Event reports) to be spooled. |
Control (Host-Initiated) | Yes | Yes | The SecsPort component fully implements this behavior. |
The SecsPort .NET component is provided as the following files:
The distribution is designed and tested for up-to-date Windows
Professional versions such as Windows
10 and 7. It remains compatible with Windows XP.
The Hume developed SecsPort component is a "component" as defined by the Microsoft .NET Framework. As such, it implements the System.ComponentModel.IComponent interface. Hume Integration is also using the word "component" to describe high level customizable applications such as their Data Collection Component.
The SecsPort .NET component uses the SECS/GEM application files provided in the Hume Datahub SDK product. A developer needs to install the Hume Datahub SDK, and specify on the SETUP screen that the GEM/SECS applications should be installed. The SecsPort component is able to find the Datahub SDK files using the environment variable DMH_BIN which is set when the Datahub SDK is installed.
The situation is simpler for a runtime deployment of your equipment SECS interface. Instead of installing the Datahub SDK, you can simply deploy a single file executeable, HumeSDK.exe or SecsServer.exe. The HumeSDK.exe includes OPC device integration features that the SecsServer.exe does not contain. These files are provided by Hume Integration for the usual case of using the as-provided SDK files. If you have customized the SDK files, you are able to create a custom versions using a build script. We encourage you to use the full SDK during development so that you have the toolset documentation, the debugging tools, and you are able to view the SDK GEM application source code. When you are ready for deployment, you can download the HumeSDK85.zip or SecsServer85.zip archive from the Hume customer support website to obtain the server program and its build script.
In order to run the example application, you need to have either the
.NET development software installed, or the .NET runtime
installed.
The .NET runtime can be downloaded from Microsoft
as the file, dotnetfx.exe. Note that the .NET runtime is not
distributed with or built into all Windows operating system versions.
The source files are provided with Project and Solution files for an
older version of Visual Studio for compatibility with the projects of
long time users. When opening the solution files with newer Visual
Studio versions, accept the default action of migrating the project
files, and you do not need a backup. It only takes a moment. After
migration you can update the projects to target a newer .NET version if
you like. Future updates can be done by replacing newer source files
and continuing use of your migrated project and solution files.
DMH_DOTNET_TCLDIR=C:/usr/local/gem2/serverIn a runtime deployment, the HumeSDK.exe or SecsServer.exe executeable file is placed in a directory of your choice as specified by the DMH_DOTNET_TCLDIR environment variable. The default directories used for process program transfer and trace logging are subdirectories of where the SecsServer.exe or SecsServer.tcl file is found.
The SecsPort software uses the namespace Hume.SECS.
Coding
is easier if you add the statement using Hume.SECS; to the
using
statements of your application source code. By doing this, the
namespace
name, Hume.SECS, can be omitted from name references. A
Visual
Basic developer uses the Imports statement for the same
purpose.
Usage of the SecsPort software was greatly simplified in June 2009
by substituting Events for several features that formerly required
delegates (callbacks). Also, the Events are presented to your
application in the same single thread that constructs the SecsPort
instance. So your application can enjoy the simplificity of a
single threaded application with the power of having multiple threads
carry out communication in the background.
The SecsPort software uses the HumeDMH.dll component internally to control the SECS interface server using the Hume DMH message system. You may want to explore using the DMH message for your own application requirements such as integrating your User Interface with Controller systems, intelligent devices, and instruments. The Hume SECS software is able to play the equipment role and the host role in multiple instances in the same SECS server process. You may want to consider using the Hume SECS software to control SECS sub equipment. In this situation, you would play the role of the host to the sub equipment, and the role of the equipment to the factory host.
Your primary focus as a developer is using the class SecsPort. This class implements public methods to send and receive SECS messages, and manage an equipment SECS interface. You will find the example application code in the GemToolUI/ToolUI.cs or GemEqApp/GemGui.cs files to be very informative.
Here is the general flow of using and configuring the SecsPort:
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 SecsPort API provides methods to split, join, append, and extract list elements. 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 ListElement
or ListSplit 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. With ASCII
string data that contains null characters, the Unicode replacement
character \uFFFD may optionally be used by the .NET application as a
replacement for the null character \u0000. This provides a
work-around for the behavior of the .NET System.Text.StringBuilder class
which truncates StringBuilder text at the first null character when the ToString() method is used.
The Hume .NET API converts the replacement character to the modified
UTF-8 byte sequence for null when communicating with the SECS Server.
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 .NET 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 -1" |
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 0" |
51 | U1 | 1-byte unsigned integer, "U1 0" |
52 | U2 | 2-byte unsigned integer, "U2 512" |
54 | U4 | 4-byte unsigned integer, "U2 979" |
Similarly, the variables required for GEM compliance are already defined, and are listed in the built-in variables 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 by your logic, 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 such as a process temperature reading, or are easier to manage as .NET application data items.
The SecsPort 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 some standard event report types specified by GEM
and
pre-defined for you as listed in the built-in events table.
Your application logic needs to call EventPost
as these events and your own defined events occur during processing.
SendSecsMsg and Threading Choices Summary
(SecsEquip) |
||
Calling
Thread/ WaitForReply |
useWorkerThread=true |
useWorkerThread=false |
GUI thread, WaitForReply=true (useWorkerThread defaults to true) |
Events are dispatched. A
re-entrant execution error is possible. You may want to disable
and enable button actions since the GUI stays responsive. |
Events are not dispatched.
A re-entrant execution error is not possible because multiple
invocations are serialized in a DMH message system queue. The GUI
may be unresponsive if the other party does not respond promptly. |
GUI thread, WaitForReply=false (useWorkerThread defaults to true if you are using VarValueRequest events, otherwise false) |
Events are dispatched. A
re-entrant execution error is possible but highly unlikely with HSMS
since the method returns almost immediately. |
Events are not dispatched.
A re-entrant execution error is not possible. For HSMS
communication, the method call returns almost immediately. |
Other thread, WaitForReply=true (useWorkerThread defaults to false) |
Event dispatching is not
affected. A re-entrant execution error is possible. Since you have your own worker thread, go ahead and use it either by letting the useWorkerThread choice default, or by setting it false. |
Event dispatching is not
affected. A re-entrant execution error is not possible. This is a smart choice to provide your own worker thread(s) but it adds complexity to your application. |
Other thread, WaitForReply=false (useWorkerThread defaults to false) |
Event dispatching is not affected. A re-entrant execution error is possible but highly unlikely with HSMS since the method returns almost immediately. | Event dispatching is not affected. A re-entrant execution error is not possible. For HSMS communication, the method call returns almost immediately. |
Property Access | Description |
bool AlarmsShareEvents |
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 true. |
int BAUD | 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. |
static DmhClient dmh | SecsPort instances use a shared connection to the DMH message system in order to communicate with the SECS server process. The connection instance, dmh, is public in case you want to access it in your application. Since it is shared (static) the access is SecsPort.dmh. |
bool CommIsEnabled |
The CommIsEnabled property is an alternative to using the methods CommEnable() and CommDisable(). The read/write property is used to set or query whether SECS communication is enabled. The default value is false. The application should initialize the handling of events and other properties before enabling communication. |
string CommState | 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. |
bool ControlIntentOnline | Whether your intended GEM Control State is an ON-LINE substate. The default setting is false indicating the OFF-LINE intention. |
bool ControlModeRemote | When in ON-LINE control, whether your intended substate is REMOTE, meaning contolled by the host.. The default setting is false meaning LOCAL control. |
string ControlState | Read-only, your actual GEM Control State which reflects your ControlModeRemote, ControlIntentOnline and host dynamics. Possible values are ON-LINE LOCAL, ON-LINE REMOTE, OFF-LINE Equipment, OFF-LINE Host, and OFF-LINE SeekOnline. These string values are enumerated in the ControlStateText string array, in the same order as ControlStateEnum values. The StateChange event is used to obtain asynchronous notification of this property value change. |
enum ControlStateEnum ControlStateStartup | Your software is able to specify the initial state for the GEM Control State model. The choices are: OfflineEquipment, OfflineAttemptOnline, OfflineHost, OnlineLocal, or OnlineRemote. This setting defaults to OfflineEquipment, but is overruled to be consistent with your ControlIntentOnline and ControlModeRemote values. If your ControlIntentOnline is false, and your startup is an Online state, the startup state is changed to OfflineEquipment. If your ControlIntentOnline is true and your startup state is OfflineEquipment, your startup state is changed to OfflineAttemptOnline. Similarly the setting of ControlModeRemote can overrule an online startup state corresponding to the opposite LOCAL or REMOTE online substate choice. This logic is applied when CommEnable is called. |
int DEVID | The SECS Device ID. An identifier imbedded in SECS header data usually left at the default of 0. You can change it anytime but you are better off setting it before enabling communication. Per the standard, the SecsPort rejects messages from the host that are not for the equipment's Device ID. Settable range is 0..32767. |
static SecsPort.DMHGroupName | The DMH message system groupname used by the SECS server. The same groupname should be specified to the constructor of every SecsPort or SecsHost instance in the application in order to share the same SECS server process. |
bool Hsms | Whether the Connection type is HSMS (LAN based). False implies SEC-I, serial RS-232 communication. Defaults to true. |
string HsmsHost | For an active HSMS connection, specifies the TCP/IP hostname or IP address of the Host computer. |
bool HsmsPassive | For an HSMS connection, whether the SecsPort plays the passive, TCP/IP server role. The default value is true which is the usual role of equipment. |
int HsmsPort | For an HSMS connection, the TCP/IP socket port number. Defaults to 5555. |
bool IdRangeChecked | 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 MDLN | The SECS Equipment Model Type - limited to no more than 20 characters by the E5 standard. |
string Name | The SecsPort 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. |
bool ParametersAreSaved | This property controls whether the values of parameters (ECV's) are saved at the program exit and restored during the next session. Saving the values is standard GEM behavior so the default value is true. If the value is true, the saved values are 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 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". |
bool PPbodyFileMode |
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 application; the ProcessProgramDownload and Upload methods work the same and the built-in SECS Server Stream 7 receiving with StateChange notifications work the same irrespective of the PPbodyFileMode setting. |
bool PPFilesByRequest |
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. |
bool RecipesAreBinary | 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. |
string RecipeDirectory | A pathname to the file system directory where Process Program files are located. The default is "./recipes" - a subdirectory of the current working directory. |
bool ReportsAreSaved | This property controls whether the state of event reporting is saved at the program exit and restored during the next program run. 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 load 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". |
bool secsTraceUseGuiThread |
Set this property true to force SecsTrace events to occur in the SecsPort constructor thread, which is typically the main GUI thread of the application. You would only set this true if you were receiving the SecsTrace events in your application instead of using the built-in Trace Window class. The SecsPort behavior prior to August 2013 was to post these events on the main GUI thread. The behavior was changed to improve the GUI performance of the Tracewin class. The default value is false. |
string SerialPort | For a SECS-I connection, the serial port device such as "COM1". |
string SOFTREV | 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 SpoolDirectory |
The file system directory for spooling, report configuration, alarm enablement, 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 spooldata under the working directory of the SECS server. For a default Datahub SDK installation and startup, the directory is /usr/local/gem2/server/spooldata. 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 SpoolingAllow | 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 State | A read-only value of the low-level connection state. Possible values include OFFLINE, LISTENING, and COMMUNICATING. You will see the OFFLINE state if the connection to the host is broken, or in the case of SECS-I implicitly broken by a conversation timeout. The StateChange event is used to obtain asynchronous notification of this property value change. |
int RTY | SECS-I maximum send retry, range 0..31, default 3 |
int T1 | SECS-I Inter-Character Timeout in milliseconds, range 100..10000, default 500 |
int T2 | SECS-I Protocol Timeout in milliseconds, range 200..25000, default 10000 |
int T3 | SECS Reply Timeout in milliseconds, range 1000..120000, default 45000 |
int T4 | SECS-I Inter-Block Timeout in milliseconds, range 1000..120000, default 45000 |
int T5 | HSMS Connect Separation Timeout - the delay between re-connection attempts in milliseconds, range 1000..240000, default 10000 |
int T6 | HSMS Control Transaction Timeout in milliseconds, range 1000..240000, default 5000 |
int T7 | HSMS Not Selected Timeout in milliseconds, range 1000..240000, default 10000 |
int T8 | HSMS Network Intercharacter Timeout, default value 5000. This value is not used. |
int TRACE | 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 TraceLogMaxWidth | 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(bool save, bool compress, int
maxDayFiles,
string saveDir, string zipCmd)
public class RcResult { bool TraceDataSaved bool TraceDataIsCompressed string TraceSaveDir int TraceSaveMaxDayFiles string TraceSaveZipCmd |
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 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 resultstring.
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.
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. |
int TracewinMaxWidth |
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. |
bool useS13 |
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. |
Event Handler and Argument Data | Description |
All event handlers - NOTES
|
It is possible to use the SecsPort using only events and not
any other type of delegate callback. Events are somewhat easier to develop with than other callbacks because of better handling by the .NET IDE tools. In some cases we have provided for use of delegate callbacks as an alternative to handling an event. The IntelliSense code generation of the .NET IDE turns around the usual sequence of writing an event handling method and then registering it. Instead, try registering an event handler using the += operator. Press the Tab key when prompted to create event handling methods with the correct arguments. The .NET framework hides the difference between executing a static method or an object method as an event handler. You are able to use either kind of method. When the event happens, your handler method is called. You can cast the event sender object to (SecsPort) to have a reference to the component instance. Your event handler is executed by the same thread that constructed the SecsPort instance. |
static void DebugEvent(object sender, StringEventArgs sea) class StringEventArgs : EventArgs { public string message; } delegate type DebugEventHander |
DebugEvents are available to troubleshoot the initial
connection to the SECS Server background process at startup. When
the first SecsPort instance is instantiated, a SECS Server background
process is started, and the .NET application is usually able to setup
DMH communication with the SECS Server within a few seconds. In an
uncommon situation such as a 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 DebugEvents. DebugEvents 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. Code for the receiving the DebugEvent events is generated automatically by the IntelliSense feature of Visual Studio once you have typed SecsPort.DebugEvent +=. The GemEqApp application has demonstration code to receive and display DebugEvent messages. See the DmhConnect method coded in the SecsPort.cs 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 a DebugEvent handler. This is a new feature of the SecsPort component as of January 2016. |
void OpcDataChange(object sender, OpcDataEventArgs e) class OpcDataEventArgs : EventArgs { public NotificationEnum notification; public string tablename; public string [] columns; public string [] keyColumns; public int rowCount; public string errorInfo; public string [] rows; public string createStatement; } public enum NotificationEnum : int { undefined = 0, create = 1, insert = 2, update = 3, delete = 4, drop = 5, select = 6 }; delegate type OpcDataEventHandler |
If you are using the optional
OPC features and you open a subscription to OPC data changes, then the OpcDataChange event notifies your
application as data values and quality attributes change. Here is example code to receive this event. The method stub is generated automatically by the IntelliSense feature of Visual Studio once you have typed sp.OpcDataChange +=. // sp is our SecsPort instance sp.OpcDataChange += new OpcDataEventHandler(sp_OpcDataChange); void sp_OpcDataChange(object sender, OpcDataEventArgs oea) { OutputAppend("Opc data change event"); string[] values; for (int i = 0; i < oea.rowCount; i++) { values = ListSplit(oea.rows[i]); for (int j = 0; j < oea.columns.Length; j++) { // name="value" Console.Write(oea.columns[j] + "=\"" + values[j] + "\""); if (j < oea.columns.Length - 1) Console.Write(", "); else Console.Write("\n"); } } } The initial event has the notification value set to NotificationEnum.create and the createStatement set to an SQL statement for the opc_item table. Subsequent events are similar to SQL selection results for the opc_item table. The notification value is set to NotificationEnum.select, and the rowCount value is set to 1 or more. The opc_item table is described in the OPC Supervisor documentation. The columns field contains the column names of the opc_item table for the subset of data that is passed in the event. Each element of the rows array value is a string containing a list of table data column values corresponding to the column names in the columns array. You use the ListSplit() method to split each row of data into the column values corresponding to the column names. |
void ParameterChange(object sender, ValueChangeEventArgs e) class ValueChangeEventArgs
: EventArgs { delegate type ValueChangeEventHandler |
The ParameterChange
event notifies you of host initiated Equipment
Configuration Variable
(ECV) changes. The new value is within the limits you have
configured. Here is example code to receive this event which is generated automatically by the IntelliSense feature of Visual Studio once you have typed sp.ParameterChange +=: // sp is our SecsPort instance sp.ParameterChange += new ValueChangeEventHandler(sp_ParameterChange); void sp_ParameterChange(object sender, ValueChangeEventArgs e) { OutputAppend("GemGui.sp_ParameterChange " + e.varname + "=" + e.newvalue); } |
void PPFileRequest(object sender, PPFileRequestEventArgs e) class PPFileRequestEventArgs { string ppid; string recipeDir; string filename; returnCode ackc7; void FileWriteOk(string filename); void FileWriteFailure(returnCode rc, string description); } delegate type PPFileRequestEventHander |
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. The filename assigned by the app may differ from the ppid value. The app writes the file or fails, and calls the PPFileRequestEventArgs method FileWriteOk() or FileWriteFailure(). The pathname for the output file is computed by concatenating the
recipeDir with a slash and then the filename which is provided by the call to FileWriteOk().
Set the filename argument value to the filename only, do not include
the directory path. See the GemEqApp/Tests.cs file for
example usage of this feature. The filename and ackc7 data items in the event argument data structure are used to communicate success or failure to the SECS Server and subsequently to the host. 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. Visual Studio will create an event handler in your app when you start typing the following: // sp is the SecsPort instance sp.PPFileRequest += new PPFileRequestEventHandler(sp_PPFileRequest); 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. |
void RemoteCommand(object sender,
RemoteCommandEventArgs e) class RemoteCommandEventArgs : EventArgs { public int stream; public int function; public string rcmd; public string dataid; public string objspec; public string TsnCmdArgs; public bool replyWanted; public int replyFunction; public int transactionID; public string header; } delegate type RemoteCommandEventHandler |
As the example application demonstrates, the RemoteCommand event delivers
Remote Command invocations to your application. Your handler
should send the reply message to the received S2F21, S2F41, or
S2F49
message. Look at the RemoteCommandReceive method code in the
SecsPort class to understand the parsing of the remote command event
data, and then look at the handling logic in the sp_RemoteCommand
method of the GemGui class to understand preparing and sending a reply
message. If you do not want to support Remote Commands call MessageTypeRemove during initialization to remove the handling of these three message types, or just code your event handler to execute SendS9(5, e.header); which means that the message type is not supported. |
void SecsMsgReceive(object sender,
SecsMsgReceiveEventArgs e) class SecsMsgReceiveEventArgs : EventArgs { public int stream; public int function; public bool sendReply; public int transactionID; public string TsnData; public string header; } delegate type for events SecsMsgReceiveEventHandler |
See the MessageTypeAdd method
described
in the next section to register to receive specific SECS messages in
your
application with the SecsMsgReceive
event. Events are easier to use than other callbacks and they are supported by third party platforms such as LabView. However, it is also possible to use a delegate callback to have a specific message type delivered to a custom handler. There is a form of MessageTypeAdd using the following delegate type: delegate void SecsMsgReceiveDelegate(object sender, int stream, int function, bool send_reply, int transactionID, string TSN_data, string header) |
void SecsTrace(object sender, SecsTraceEventArgs e)
class SecsTraceEventArgs : EventArgs { delegate type SecsTraceEventHandler |
The SecsTrace event provides you with the detailed information of SECS message traffic that is viewed in the SECS Trace window. The information is controlled by setting the TRACE property. |
void ServerDisconnected(object
sender, EventArgs
e) delegate type EventHandler |
If the SECS Server process exits your application receives the ServerDisconnected event. This event is not ordinarily expected. A production application will limit access to the SECS Server windows so that users will not use the Exit menu items on these windows. |
void ServerError(object sender, ServerErrorEventArgs
e)
class ServerErrorEventArgs : EventArgs { delegate type ServerErrorEventHandler |
The ServerError event reports Tcl programming errors that are trapped in the SECS Server process. 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. If you have more than one SecsPort instance, the ServerError event is reported only to the latest instantiated instance. The event is passed using an instance in order to present the event on your application thread. |
void SpoolingAlert(object sender,
EqSpoolingAlertEventArgs
s)
class EqSpoolingAlertEventArgs : EventArgs { delegate type EqSpoolingAlertEventHandler |
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 example explanation messages in the application method GuiSpoolingAlert. The latter two values are not seen in normal circumstances. |
void StateChange(object sender, ValueChangeEventArgs
e)
class ValueChangeEventArgs : EventArgs { delegate type ValueChangeEventHandler |
This event notifies your application of state value changes.
Possible varname
values include
|
void TerminalDisplay(object sender,
TerminalDisplayEventArgs e) class TerminalDisplayEventArgs : EventArgs { public int tid; public string [] text; public bool replyWanted; public int replyStream; public int replyFunction; public int transactionID; } delegate type TerminalDisplayEventHandler |
The TerminalDisplay
event is used to dispatch Host sent Terminal Data
into your
application. The string array text holds the communicated data -
one string element for the case of S10F3, or multiple elements in the
case
of S10F5. Your application should send a SECS reply with the
values
of
the ACKC10 SECS reply item - "B 0" for success, "B 1" for not
displayed, and "B 2"
for terminal not available. If you do not wish to support Terminal Displays, use MessageTypeRemove against message types S10F3 and S10F5. |
void VarValueRequest(object sender,
VarValueRequestEventArgs e) class VarValueRequestEventArgs : EventArgs { public int varCount; public int [] varID; public string [] value; } delegate type VarValueRequestEventHandler |
The VarValueRequest event is used to ask
your application for variable values if you have elected to manage the
variable values in your own code. You call the method VariableMethodSet to specify the
variables that your code will manage. In your event handler, loop
through the varID array and assign the current variable value to each
corresponding element in the value array. This event only occurs
when one or more variable values are actually needed to respond to a
host query, or to provide data in an event report. Using this feature causes the SendSecsMsg method to default to using a background worker thread so that your application stays responsive to possible VarValueRequests that may overlap with your message sending. |
METHOD | DESCRIPTION |
General Comments
|
The List manipulation methods are actually implemented by the HumeDMH.dll component, and exposed for your convenience by the SecsPort component. These methods may be called from different threads. |
void AlarmAdd(int ALID, string ALTX)
void AlarmAdd(int ALID, string ALTX, int alarmSetCEID, int alarmClearCEID) |
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 AlarmsShareEvents 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 AlarmsShareEvents before using the AlarmAdd methods. If the AlarmsShareEvents 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 AlarmsShareEvents 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, bool is_enabled) | Enable or disable reporting of an Alarm type (S5F1).
A tool does not usually call this method, it is appropriate to leave it to the host to configure the enablement of alarms. By default per the GEM standard E30, there is built-in logic to save and restore the enabled/disabled settings of the alarms. The file "alarmdata_" + Name + ".sql" is written to the SpoolDirectory. When communication is first enabled, this file is read to restore the enabled/disabled settings from the prior session. An app can disable the built-in logic using the PropertySet method. |
bool AlarmIsEnabled(int ALID) | Test if the reporting of an alarm type is enabled |
bool AlarmIsSet(int ALID) | Test if the alarmed state is currently set |
void AlarmSet(int ALID, bool is_set) | Set or Clear the alarmed state of an alarm. |
string AlarmText(int ALID) | Lookup the description, ALTX, of an alarm type. An empty string is returned for a non-existent 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 CommDisable() | Disable SECS communication. The SecsPort is initialized without communication enabled so using this method only makes sense after CommEnable has been called. This method call is equivalent to setting the CommIsEnabled property false. |
void CommEnable() | Enables SECS communication. The CommEnable method call is equivalent
to setting the CommIsEnabled property
true. 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. |
int 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(). |
int ConnectTypeHsmsPassive(int port) | This method is an alternative to setting the underlying property values to specify a passive HSMS connection type, and calling ConnectTypeSet(). |
int 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(). |
int ConnectTypeSet() | 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. |
void DebugDMHStatus(bool 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. |
void DebugTclConsole(bool show) | This method causes a console window for the SECS Server to be shown or dismissed. |
void DebugTableWindow(bool show) | This method causes the Datahub table management GUI to be shown or dismissed. |
void DebugTraceWindow(bool show) | This method is used to display a window which updates to show SECS message traffic and state information for the SecsPort. 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 in order to instantiate a native .NET window with similar function. Including the .NET window in the administration area of your equipment GUI may be desirable to help field personnel 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 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 Dispose method should be used instead of Delete for a shutdown that does not delete persisted data. |
void Dispose() | As a .NET component, the SecsPort inherits a public Dispose method that can be called to shutdown. The Delete method can be called if there is no intention of future use. |
void EventAdd(int CEID, bool is_reported, string
description)
void EventAdd(string eventName, int CEID, bool is_reported, string description) |
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) void EventDvvals(string eventName, string dvvalList) |
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. The developer can choose to specify the DVVAL varnames as an array, or as a whitespace separated list per the formatting conventions of Tcl language lists. |
void EventEnable(int CEID, bool 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. |
bool 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) | 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. Negative values indicate error condtions. In more detail, the return values and their meanings are:
|
System.Collections.ArrayList 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. |
int HexValue(char b) | This method can be used to convert a single hexadecimal character to an integer value. The BinToInt method will convert a hexadecimal string. |
string HtmlSave() |
This method is used when fully initialized to save the configuration of Alarms, Events, Parameters, and Variables to an HTML file in a form that is useful for preparing documentation. The return value of the method is the pathname of the output file which is written in the working directory of the SECS Server. The method is equivalent to invoking the procedure, ei_html_save, at the Tcl command prompt of the SECS Server. |
bool IsHexDigit(char b) | This method can be used to determine if a single character can be parsed as a hexadecimal digit. |
bool 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. |
StringBuilder ListAppend(string list, string
element);
StringBuilder ListAppend(StringBuilder list, string element1); StringBuilder ListAppend(StringBuilder list, string element1, string element2); StringBuilder ListAppend(StringBuilder list, string element1, string element2, element3); StringBuilder ListAppend(StringBuilder list, string
element1,
string element2, element3, element4); |
These methods are used to add one to four list elements to text that is formatted as a Tcl list. It is a good programming practice to use ListAppend or ListJoin to build a Tcl list, in order to make sure that imbedded white space or other special characters are properly delimited with curly braces or escaped with backslashes. A null value may be passed as any of the string argument values, in order to represent an empty list or empty element. However, a null value should not be passed as a System.Text.StringBuilder argument. The System.Text.StringBuilder class is designed to support more efficient string modification than using instances of the string class. The input StringBuilder objects are modified by reference and returned as the return value of the methods. You can construct a StringBuilder instance that does not contain any characters to represent an empty list. The overloaded method calls make it convenient to add up to four list elements in one call. If you need to add more elements, call the methods repeatedly. |
string ListElement(string list, int index1);
string ListElement(string list, int index1, int index2); string ListElement(string list, int index1, int index2, int index3); |
This function is similar to the lindex function of Tcl. It will parse text formatted as a Tcl list and return the specified element. Indexing starts from 0. Arguments index2 and index3 may be used to indicate that parsing of the TclList should continue up to two additional levels as a nested list structure. If a specified index is out of bounds, an empty string is returned. Not all strings are valid Tcl lists. If an invalid list is parsed, the method call throws the FormatException. |
string ListJoin(string [] argv); | Joins together strings as Tcl list elements forming a result string that is a Tcl list. Braces are added as needed to delimit empty elements, or to delimit special Tcl character sequences involving backslashes , square brackets, etc. |
string [] ListSplit(string list) | ListSplit( ) parses a string formatted as a Tcl list into an array of string elements. The function understands the Tcl usage of quotes, braces and backslash sequences. Not all strings are valid Tcl lists. If an invalid list is parsed, the method call throws the FormatException. Failure occurs when there are unmatched braces, unmatched quotes, or non-whitespace following braces or quotes. |
void MessageTypeAdd(int stream, int function) void MessageTypeAdd(int stream, int function, SecsMsgReceiveDelegate callback) delegate void SecsMsgReceiveDelegate(object sender, int stream, int function, bool send_reply, int transactionID, string TSN_data, string header) |
Use the first form of MessageTypeAdd to have received SECS
messages of the specified type delivered to your application as a SecsMsgReceive event. Events are
easier to code than other callbacks because the support of the IDE. Use the second form of the method to have SECS messages dispatched to your callback handler. To receive a message from the host, an online control state must exist. These methods provide for handling new SECS message types, or for replacing the existing SecsPort handling of particular messages. Use the SendReply, SendS9, and SendAbort methods to send reply messages. |
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 SecsPort logic. For example, you may wish to turn off Process Program management message types for a tool that does not use Process Programs. 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 messages are replied to with an abort reply. If the unhandled message does not ask for a reply, an S9F5 message is sent to indicate an unknown function. |
void OpcAlarmAdd(string
opcConnectionName, string opcItemId, int ALID, string ALTX) void OpcAlarmAdd(string opcConnectionName, string opcItemId, int ALID, string ALTX, bool hasMin, float min, bool hasMax, float max) void OpcAlarmAdd(string opcConnectionName, string opcItemId, int ALID, string ALTX, int alarmSetCEID, int alarmClearCEID, bool hasMin, float min, bool hasMax, float max) |
Changes to some OPC item values
may signify SECS alarms. An alarm
is an undesirable condition with a set and clear state. In the
usual case, you assign ALID
integer identifiers to each alarm type
starting from 1000. As you add alarm definitions, the SECS
software assigns Events for the Setting and Clearing transitions of the
alarm condition. These events will be signalled
automatically. There is a property configuration value, AlarmsShareEvents, to specify
whether different Alarm types share the same Events which is the
default. In this case you may number your ALID values to
increase in sequence by 1. The method OpcAlarmAdd() is called to map the data of an OPC item to a SECS alarm condition. The opcConnectionName argument is the OPC connection name that has been previously configured using the OPC Supervisor application. The opcItemId argument is the fully qualified OPC item name. The ALID and ALTX arguments represent the SECS data items for the alarm identifier and its description. The description is limited to 120 characters. The second form of OpcAlarmAdd provides for specifying a lower bound, an upper bound, or a range of values that indicate an alarm condition. The alarm condition is set for the item if (hasMin && (value < min)) || (hasMax && (value > max)). The default behavior is to map any non-zero value to the alarm set state which works well for any representation of a boolean value. The most complex form of OpcAlarmAdd allows you to specify the SECS Event ID values for the setting and clearing of the alarm condition to meet custom requirements. Both alarmSetCEID and alarmClearCEID argument values are ignored if the property AlarmsShareEvents is true which causes the default assignment of Event ID values. The default value range checking is obtained by setting hasMin = true, min = 0.0, hasMax = true, and max = 0.0. |
void OpcConnectionAlarmAdd(string
opcConnectionName, int ALID, string ALTX) |
The OpcConnectionAlarmAdd method
installs logic so that if the OPC connection opcConnectionName is ever lost, a
SECS alarm
is indicated. You can test this alarm by using the OPC GUI to
disconnect and re-connect to the OPC Server. When you are using
OPC, there is a button action on the ServerDebug dialog that shows the
OPC GUI. The integration
logic is able to recover automatically when the connection is
restored. In the few cases where transient server handle values
are used, new values are re-acquired. |
void OpcEventAdd(string
opcConnectionName, string opcItemId, int CEID, bool isReported, string
Description) void OpcEventAdd(string opcConnectionName, string opcItemId, int CEID, bool isReported, string Description, string criteria, int delayMilliseconds) |
Changes to some OPC item values
may signify SECS Events. A good
example is a enumerated integer which represents the process state and
every value change is an Event. A batch tool is required to post
data collection Events on the transitions of its process state.
Another example is when a data item value is a counter of something
non-trivial. The procedure OpcEventAdd is used to map OPC value changes to SECS Events. The event identifier, CEID, is an integer value from 5000 to 9999. By default any value change of the OPC item signals a SECS event. The optional criteria argument enables you to specify an expression involving the opc_item table field last_value such as {$last_value > 0} to filter which value changes signify events. There is also an optional argument, delayMilliseconds, which can be used to specify a timed interval delay in milliseconds before the SECS event is posted. The default delay value is 0 which causes the SECS event to be posted immediately after the OPC group refresh which contained the data update which triggered the event has been completely processed. Additional delay can be used to allow for receiving updated data values coming later or coming from different OPC group refreshes. You are able to specify a CEID value of one of the standard built-in SECS events to indicate that the standard event is triggered by the OPC item value change. A common situation is to specify the CEID value of 4050 for the ProcessStateUpdate event and link it to an OPC process state variable. |
RcResult OpcGroupSubscribe(string
opcConnectionName, string opcGroupname) RcResult OpcSubscribeClose(string opcConnectionName) |
The OpcGroupSubscribe method opens a
subscription to data changes for a specified OPC connection and group
that you have configured using the OPC Supervisor application. As
changes occur, your application receives OpcDataChange
events. OPC client software can potentially collect large volumes of data and consume lots of network bandwidth. In the implementation of this method and the underlying Datahub table subscription, optimizations have been made to reduce network usage by combining multiple data changes into single DMH messages. Do not perform time-consuming actions in your OpcDataChange event handling logic. If your application does not keep up with the flow of messages and events, the subscription is closed automatically. You can change your Group refresh period or change the sampling period of individual items to reduce performance requirements. Use the OpcSubscribeClose method to shutdown all of your subscriptions and end the OpcDataChange events. |
void OpcParameterAdd(string
opcConnectionName, string opcGroupname, string opcItemId, int varID,
string varname, string description, string value_TSN, string minValue,
string maxValue, string defaultValue, string units, bool
affectsProcessing) |
A Parameter is a read/write data
item served on the SECS
interface such as a configuration choice or a setpoint. The OpcParameterAdd method is used to
configure OPC read/write items as SECS ECV Parameters. The
description of the ParameterAdd method has
more background information including descriptions of the argument
values which also apply to this method. Per the standards, a
Parameter should be a scalar value and not an array
or list of values. The SECS standards specify that Parameter values set by the host are persistent. The toolset has Parameter persistence features built-in. The parameter value is initialized to the defaultValue when this method is invoked. However, before communicating, the logic restores any non-default values set by the host. |
static void SecsPort.OpcStart(string dmhGroup) |
In order to use OPC features
with your SECS interface, your application must call SecsPort.OpcStart. We suggest
you call it before instantiating any SecsPort (or SecsHost)
instances. Use the same DMH Group name for the OpcStart call and the construction
of your SecsPort instances. To get started with OPC, run the OPC Supervisor application and configure connections to your OPC servers. Then configure Groups of OPC items, and configure the membership of items in Groups. Define and set the environment variable, HUME_OPC_DATA_DIR to the directory path where your OPC configuration data exists. You can set a persistent environment variable using the Windows "My Computer"/"Properties"/"Advanced" configuration dialog. Both the OPC Supervisor and the SecsPort initialization use the value of this environment variable. Use a Unix style c:/slash/directory/path specification. The SecsServer.exe program does not include OPC features. Instead, use the HumeSDK.exe program or the full Hume Datahub SDK installation to combine both OPC and SECS/GEM features. If both the HumeSDK.exe and the SecsServer.exe are installed, the initialization logic chooses to use the HumeSDK.exe program. |
static void SecsPort.OpcStop() |
Your application can call SecsPort.OpcStop() at termination
when running the OPC/SECS server is no longer desired. The server
process does not terminate until all using SecsPort instances are
closed. |
void OpcVariableAdd(string
opcConnectionName, string opcItemId, int varID, string varname, string
description, string value_TSN, string units, bool addQuality, int
qualVarID, string qualVarname, string qualDescription, bool linkWrites,
string opcGroupname, string valueMapping) |
An OPC item is easily mapped to
a Status Variable value on
the SECS interface. A SECS host is able to dynamically configure
data collection event reports and ask to receive certain Variable
values at the occurrence of specified Events. See the VariableAdd method description for more
background. The varID argument is an integer identifier which is set to a unique value between 3000 and 9999 for new SECS variables. You are also able to specify the varID value and the varname value of a standard built-in variable to specify that an OPC item supplies the value. For example, a batch processing tool that uses process programs should support the PPExecName and PPUsedName Status Variables. The method adds the quality property of the OPC item as a second SECS Status Variable when the boolean argument addQuality is true. Use the qualVarID, qualVarname, and qualDescription arguments to specify properties for the quality variable. Typical values are (varID+1), (varname + " quality"), and ("OPC quality bitfield for " + varname + " value") respectively. The TSN value type for the quality variable is set to "U2". A variable value can be an array. The value_TSN type code for a scalar type such as "I4" also works for an array of scalar values, so specify the type code of the array element type. For an array of string values or variant values, specify the value_TSN as "L" in order to map the OPC array to a SECS list of string values. A non-array variant value can be passed as SECS value_TSN type "A". The linkWrites boolean value specifies whether you want calls to VariableSet to be able to write values to the underlying OPC item. If you set this argument true, be sure to use a read/write OPC item, and specify an OPC group name, opcGroupname, that includes the OPC item. The valueMapping argument provides for optionally supplying an expression to compute the value for the SECS variable from the OPC value. For example, OPC uses enumerated integer values starting from 0. SECS process state variables are enumerated integer values that start from 64. Supplying the valueMapping argument of {expr {$last_raw + 64}} maps the OPC value into the desired SECS value. Use the variable last_raw to access the OPC item latest value in your valueMapping expression. |
void ParameterAdd(int varID, string varname, string
description,
string value_TSN, string initialValue, string minValue, string
maxValue,
string defaultValue, string units) void ParameterAdd(int varID, string varname, string description, string value_TSN, string initialValue, string minValue, string maxValue, string defaultValue, string units, bool affectsProcessing) |
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 PascalCase name and make each name unique. The value_TSN 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. A Parameter should be a scalar value and not an array or list of values. 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. Call ParameterSet when the ECV value is changed by your GUI or controller logic so that the SECS Server knows the desired value and can manage the appropriate GEM event. 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 error. Lookup by varID instead of varname is marginally more efficient. |
VariableInfo ParameterGetInfo(int varID) VariableInfo ParameterGetInfoByName(string varname) |
These methods return the configuration data of an ECV. The return value is a VariableInfo data structure - see VariableGetInfo. |
int ParameterSet(int varID, string newvalue) int ParameterSetByName(string varname, string newvalue) |
These methods are used to update the value of an ECV. The SecsPort takes care of notifying the host with any GEM Data Collection event. |
void ParametersRestore() | Restores the saved values of the parameters (ECV's). The ParametersRestore() method gets called automatically when you first enable communication if property ParametersAreSaved 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)
struct RcResult { |
Used by the equipment to initiate the download of a process
program
from the host using S7F5. 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 command for
the
equipment to know what process programs are available from the host for
downloading. If the return code value is 0 which indicates
success,
the result string is the full pathname to the process program
file.
Negative return code values indicate error. Possible errors
include
those described with SendSecsMsg(). In addition the
following
error codes are also possible: -10 file system error, -11 improper data received, -12 request denied by the host. In the case of error, the result string is a diagnostic message. |
RcResult ProcessProgramLargeRequest(string ppid) struct RcResult { int rc; // return code string result; } |
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 RecipeDirectory
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 RecipeDirectory 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) struct RcResult { int rc; // return code string result; } |
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 RecipeDirectory
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)
struct RcResult { |
Used by the equipment to initiate transferring a process
program to
the host using S7F3. The ppid argument value is identically the
file
name of the process program and the identifier for the process
program.
The return code value is 0 for complete success. Negative return
code values indicate an error. Possible error values include
those
possible with ProcessProgramDownload(). In addition, the
return
code value of -13 is used to indicate "upload disabled during
spooling".
A positive return code value is the SECS standard ACKC7 code value sent
by the host. Diagnostic text is provided in the result string for
all return code values.
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. |
void ProcessStateNames(int[] stateVal, string[] stateName) |
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 stateVal argument is an array of process state integer values. The stateName argument is a corresponding array of state names. |
void PropertySet(string name, string value) | There are some less commonly configured properties that can be initialized using this method, such as:
|
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,
-2 unknown variable ID, -3 invalid rptID , -1 unexpected transaction
error.
Any unsigned number can be used for a report ID (rptID) value.
(Unsigned
integer types are not supported by the Microsoft Common Language
Specification.)
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 reporting 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 ReportsAreSaved 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. 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. |
System.Collections.ArrayList ReportGetInfo(int rptID) | 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, int CEID) void ReportUnlink(int rptID) |
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() | ReportsRestore gets called automatically when you first enable communication if property ReportsAreSaved 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 SecsPort()
void SecsPort(string spname, string dmhGroup) void SecsPort(System.ComponentModel.Icontainer c) |
The constructor. The spname 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 SecsPort instance, and not coincide with
a keyword in the Tcl programming language. The default value of spname
is similar to equip0. The example application uses the spname
value, eqsim. The name should be a single alphanumeric
token.
The dmhGroup argument becomes the DMH message system group name used by the SecsPort and SECS Server process. If you are instantiating more than one SecsPort 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 SecsPort is executing. The default value is GEM. This value does not conflict with the default value for Hume Datahub instances which is mbx. The name should be a single alphanumeric token. The SecsPort 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 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 in lieu of a normal reply. The SecsPort
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, bool
replyWanted,
string TsnData, bool waitForReply)
RcResult SendSecsMsg(int stream, int function, bool replyWanted, string TsnData, bool waitForReply, bool useWorkerThread) struct 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. The stream
and function arguments are
the message type identifiers of SECS. The TsnData argument is a string
representation of the message body using the type notation of TSN. The list methods ListAppend and ListJoin
are recommended for building complex messages to insure valid
formats. A null or empty string value may be used for the TSN_data
argument
when a header only message is to be sent. The methods differ in that the second form provides the boolean argument useWorkerThread which is used to explicitly specify whether a background thread should be used to perform the call. If this option is defaulted by using the first form, then a worker thread is used if you are executing on the thread that constructed the SecsPort, and you are waiting for a reply, or you are managing Variable values using VarValueRequest events. When the background thread is used, the method call continues to service the application event loop. See the detailed discussion above. The SendSecsMsg() return value is a structure containing an integer return code and a string result. The possible return code values are:
|
static int ServerLicenseCheck() |
This function returns an integer code for the license
status when using the SecsServer.exe or HumeSDK.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 ServerSQLCmd(string sql) | Send an SQL command to the SECS Server process without waiting for a reply. This method is used by the SecsPort software and made public in case of custom requirements. |
static string ServerSQLReply(string sql) | Send an SQL command to the SECS Server process and wait for the reply. This method is used by the SecsPort software and made public in case of custom requirements. The return values vary by SQL statement type and they are described in the Datahub documentation. |
static void ServerTclCmd(string tclCommand); | Send a Tcl command to the SECS Server process without waiting for a reply. This method is used by the SecsPort software and made public in case of custom requirements. After a SecsPort 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 ServerTclReply(string tclCommand); | Send a Tcl command to the SECS Server process and wait for the reply message. This call is used by the SecsPort software and made public in case of custom requirements. After a SecsPort 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 SecsPort.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 SecsPort.StartupSave(EquipStartupData esd) | 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 SecsPort software and made public to support custom requirements. |
string TclReply(string tcl)
RcResult TclReplyRcResult(string tcl) struct RcResult { |
These methods are used to send Tcl code to the SECS server command mailbox for the connection and wait for the evaluation result. The methods are used by the SecsPort software and made public to support custom requirements. With TclReply() the string return value is structured as a list and may be parsed using ListSplit or ListElement. 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. With TclReplyRcResult( ) the same data has been parsed and is returned as separate fields in the RcResult data structure. |
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(bool show); void Tracewin(bool show, bool allowLogging) |
The SecsPort is able to instantiate and manage a Form 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. The allowLogging argument is set true to selectively display menu items that configuring logging - the feature of continuously saving trace data to the file system. 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 currently displayed data to the file system. |
string TsnI8Value(long int64bit) | Format a Tcl SECS Notation (TSN) I8 (signed 8 byte) integer
value using
hexadecimal notation. The C# body of this method is just:
return "0x" + int64bit.ToString("x16"); A similar method would be defined for unsigned 8 byte integer values except that the ulong data type is not supported by the .NET Common Language Specification. The C# code for formatting a TSN U8 value is: |
bool TsnTypeIsOk(string value_TSN) | This method is used to check value_TSN argument values that you pass to the various Add methods. |
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 an enum or const values for your variable IDs. |
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 value_TSN, string varmethod, string initialValue, string units) | 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
PascalCase 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. Leave the
varmethod
argument as null or an empty string if the variable value will be
represented
in the ei_variable table, or you will subsequently call VariableMethodSet
to specify 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. The methods 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. |
VariableInfo VariableGetInfo(int varID) VariableInfo VariableGetInfoByName(string varname) struct VariableInfo { |
These methods return the configuration information of a variable or parameter (ECV). |
int VariableRenumber(string varname, int newID) | 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. Negative values indicate error condtions. In more detail, the return values and their meanings are:
|
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 represented in the SECS Server's ei_variable table. It is marginally more efficient to set the value using the varID to identify the variable. |
void VariableMethodSet(int varID, bool useVarValueRequestEvent) | You use this method to specify using a VarValueRequest event handler that is
executed
by the
SecsPort software when the value of a Status Value or Data Value
variable
is needed.
If the useVarValueRequestEvent argument value is false, then the variable method is changed so that the value is managed in the SECS Server's ei_variable table using the VariableSet method. |
The Hume .NET SecsPort 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 SecsPort software on systems that are not licensed as development systems. Contact Hume Integration for information on the Resale Licensing program.