The SecsEquip Active-X Control for Deploying Equipment SECS Interfaces

The SecsEquip is a Visual Basic Active-X control for rapidly deploying SEMI-standard GEM compliant SECS equipment interfaces.   Without any customization, the control 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 Constants, Alarm Definitions, and Event Definitions.  The control features built-in handling of the core messages of SECS and GEM.  To complement the built-in logic, the developer codes handling of  SECS message  types of his choosing in event callbacks.   An example application is included that demonstrates processing Remote Commands and Terminal Display messages.   The SecsEquip control also provides for using native VB variables as Status Variables.

Feature Summary

• A high-level, working SECS/GEM interface ready for adding equipment specific customization.
• Built-in handling of more than 100 standard SECS message types, all required GEM variables, and event types.
• Built-in event CEID values and variable ID values can be customized to meet your exacting requirements.
• Designed for efficient and productive use of  the Microsoft Visual Basic programming environment running on Windows Professional platforms, and other Active-X compatible platforms.
• Leverages the Hume SECS/GEM application software which has been in 7x24 use by major equipment providers for several years.
• The robust and proven SECS interface server executes as a child process with minimal impact on your application execution.
• SECS-I, HSMS passive and HSMS active roles are supported.
• Convenient use of string data to represent all SECS data types including SECS Variant data, also known as Localized Character Strings.
• Supports remote debugging using the Hume Datahub SDK applications Inspect and hubclient.
• Integrated into the VB design environment with IntelliSense coding of methods and parameter prompting.
• Fully integrated into the VB runtime environment with usage of events, properties,  and excellent diagnostic features such as the dynamically controllable trace window.
• The SecsEquip control has the desirable feature set of our .NET SecsPort Component, and provides a quick, low risk SECS deployment for Equipment OEMs who are running VB6 on existing systems.

GEM Compliance Statement

The Equipment OEM developer will need to be mindful of the standard when using the Hume SecsEquip 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 SecsEquip and controlled by calling the CommEnable and CommDisable methods.  The current Communication State value is readable as the property, CommState. Your application receives notification of CommState and similar state changes by handling the SecsEquip StateChange event.  This event notifies you of important changes such as communication with the Host starting or ending. Your logic and your Operator GUI affect the Control State by setting the ControlIntent and ControlMode properties.  Comments on the Process State model follows in the next row.  Other equipment models such as Spooling are described below in this table.
Equipment Processing States	Yes	Yes	The example application fully implements a Process State model that you can copy and modify.  Follow the example as far as posting standard GEM events for Process State changes and related events such as selecting a different Process Program.  You also need to update Status Variables to keep track of the previous and current process states, just as the example application demonstrates.
Host Initiated S1F13/F14 Scenario	Yes	Yes	This behavior is fully provided by the SecsEquip control.
Event Notification	Yes	Yes	Your logic needs to call the EventPost() method at the occurrence of standard collection events.  You may choose to define and report additional event types for the activities of your equipment.
On-Line Identification	Yes	Yes	You are obligated to set the property values MDLN and SOFTREV to reflect the hardware and software configuration of the equipment.  Any change in the equipment software should result in a new unique value of SOFTREV.
Error Messages	Yes	Yes	The standard requires use of Stream 9 Error reporting.  The SecsEquip sends specific Stream 9 messages for communication faults, conversation timeouts, incorrect device ID, unhandled message stream or function types, and non-standard data.  In the custom message handling logic that you write, use the method SendS9 to send error messages when the received message data is not in the expected format or has improper values.
Documentation	Yes	Yes	Hume Integration has example documentation which meets requirements of the GEM and SECS standards.  This documentation is provided to Equipment providers with permission to create derivative works.  The SECS Server has the ability to export HTML documents of the configured event, alarm, and variable table data.  You may want to use this feature of the table window that is display by executing the DebugTableWindow method.
Control (Operator Initiated)	Yes	Yes	Use the GEMGui form logic 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 ControlIntent.  The desired substate of ON-LINE control, LOCAL or REMOTE, is settable as the property ControlMode.  The actual control state value reflects interaction with the Host and is readable as the property ControlState.  Your application receives notification of ControlState and similar state changes by handling the SecsEquip StateChange event.
ADDITIONAL CAPABILITIES
Establish Communications	Yes	Yes	This behavior is fully provided by the SecsEquip control.
Dynamic Event Report Configuration	Yes	Yes	This behavior is fully provided by the SecsEquip control. 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 variable values when needed in your handling of the VarValueRequest Event or by calling VariableSet when their values are changed.
Variable Data Collection	Yes	Yes	This behavior is fully provided by the SecsEquip control.
Trace Data Collection	Yes	Yes	This behavior is fully provided by the SecsEquip control.
Status Data Collection	Yes	Yes	This behavior is fully provided by the SecsEquip control.
Alarm Management	Yes	Yes	This behavior is fully provided by the SecsEquip.  Your job is to add equipment specific alarm types using the AlarmAdd method.  You use the method AlarmSet to indicate when an alarm condition is set or cleared.  You can optionally use the method AlarmEnable to enable or disable reporting of an alarm type as a Stream 5 message.  GEM also requires event reports for the Alarm Set and Alarm Clear events.  These event definitions are automatically created and managed for you by the SecsEquip when you use the AlarmAdd method.
Remote Control	Yes	Yes	The example application shows how to use MessageTypeAdd to receive and process Remote Commands (S2F41) in your application code.   You need to implement control logic that is mindful of the Process State model and the Control State model.  For example, you need to disallow Remote Commands that affect processing when you are in the Online Local Control State.
Equipment Constants	Yes	Yes	This behavior is fully provided by the SecsEquip control.  Your job is to add equipment specific constants using the ParameterAdd method.  You manage their values by calling ParameterSet when their values are changed by the GUI or your control logic.  If the host changes an Equipment Constant, you are notified via a ParameterChange event.
Process Program Management	Yes	Yes	The SecsEquip control 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 SecsEquip StateChange event.   You will receive notice when recipes are downloaded from the host, uploaded to the host, or deleted by the host.  You can use these notifications to trigger validation of downloaded recipes, or you can defer validation until the time the process program is loaded for use.
Material Movement	Yes	Yes	The GEM standard only requires that the equipment provide Data Collection events when material is sent from any port on the equipment, or received by any port, whether the transfers are automated or manual. Automated Material Movement is implemented by calling the method MessageTypeAdd and registering a callback for each of the primary message types that the host sends.  In your callback, you parse the received SECS message data using the 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 SecsEquip demonstrates displaying data received from the host, sending acknowledgment events, and sending display data to the host.  For your own implementation,  use the method TerminalDisplayAck to send acknowledgment events, and follow the example code for sending input data to the host using SendSecsMsg.
Clock	Yes	Yes	The SecsEquip component fully implements a host-settable Clock variable value with standard data format choices.  The implementation does not affect the system clock, the host's setting is saved as an offset.
Limits Monitoring	No		See the notes for Material Movement, above, to understand the general approach that is taken to implement this capability.
Spooling	Yes	Yes	The SecsEquip component fully implements Spooling.  We recommend that the equipment supplier only allow spooling of Alarm messages, and Event report messages or similar messages where there is no control logic tied to the receiving of the reply messages.  These are exactly the message types that most factory CIM workers want to collect with spooling.  If restricting the spooled message types is not done, there are complex issues with implementation and timing that cannot be adequately tested and verified correct.  The standard describes allowing the spooling of nearly any primary message type, out of consideration that any message may occur when the spool is being unloaded, and it should take its proper sequence at the end of the spool.  In practice this is a rare circumstance because an HSMS implementation can unload thousands of messages in a few seconds.  The downside of allowing messages that have control implications to be spooled is that they are queued for a variable and potentially lengthy delay before delivery.  The equipment provider's job is to provide a robust control system, and we think that knowing immediately that a near real-time message conversation cannot be initiated is the right choice.  The Equipment provider can add to the message types allowed for spooling using the SpoolingAllow 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 SecsEquip control fully implements this behavior.

User Guide

Here is an overview of the provided files:

The VBSecsEquipProj Project:

• SecsEquip.ctl, secs.bmp - source code and the toolbar icon file for the control.
• SecsEquip.ocx - the compiled file for runtime use.
• VBSecsEquipProj.vbp, VBSecsEquipProj.vbw - other project files that can be used to rebuild, customize, or deeply understand the SecsEquip control.  We think you will not need to modify this project for normal usage.  By having the source code, you can be more effective with understanding and debugging the interaction between the SecsEquip control and your application.

• GemGui.frm, alarmtable.frm, ConnectionDlg.frm, ServerDebug.frm, testDialog.frm, tracewin.frm, tracewinLogging.frm   - Visual Basic source for the SECS/GEM Gui and its child windows.
• ToolUI.frm, ConfigurationDlg.frm, TraceAndLoggingConfig.frm - Sources for a simple tool SECS user interface provided with configuration dialogs that provide for editing and saving all of the SECS properties that are required to be editable and persistent.  This simple tool UI and the dialogs are not integrated into the example VBGEMGui application.  Explore them in the IDE environment and use them as a parts kit for your own project. 
  
• GemGuiProj.vbp, GemGuiProj.vbw   - project files
• SecsEquipProjGroup.vbg   - a project group file that combines the two projects.
• VBGEMGui.exe - The compiled application which is runnable if the VB6 runtime, DLL dependencies, and Hume Datahub SDK SECS/GEM Runtime files are installed on the target computer.

• DMH.ocx - an Active-X control used by the SecsEquip control to communicate with and manage a SECS server process 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.

Installation

The SecsEquip VB software 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 SecsEquip control 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 simplified for a runtime deployment of your equipment SECS interface.  Instead of installing the Datahub SDK, you can simply deploy a single file executeable, SecsServer.exe.  This file is 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 version of SecsServer.exe 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 SecsServer85.zip archive from the Hume customer support website to obtain the SecServer.exe program and its build script.

The distribution is designed and tested for Visual Basic 6.0 (SP6) on older windows Professional versions such as Windows XP.

Installation of the SecsEquip software consists of extracting files in the VBSecsEquip.zip archive to a directory of your choice.  You should not add the files in the VBSecsEquip.zip archive to any of the existing Datahub SDK GEM application directories.  The SecsEquip control is able to find and use the Datahub SDK GEM directories without usage of a common directory.

The stored paths in the .zip archive and the existing project settings assume a common directory for the SecsEquip code and binary files and a subdirectory for Process Programs.  For example, if you unzip the archive in the directory C:\hume, you will create the directory structure as follows

    c:\hume\VBSecsEquip\*.*         ' has most of the SecsEquip files

    c:\hume\VBSecsEquip\recipes\*.* ' has dummy Process Programs

If you do need to register the .ocx files, it is a one-time activity.  The installation path should be chosen carefully since you need to unregister and re-register a .ocx if you move it.   The registration can be performed at the command line by executing

    regsvr32 pathname\DMH.ocx
    regsvr32 pathname\SecsEquip.ocx

where pathname is your pathname to the file.   The VB6 Development Environment can also register a component - refer to its documentation.

At runtime, the controls uses the following additional files:

• the VB6 runtime DLLs
• the Microsoft Scripting Runtime, %SystemRoot%\System32\scrrun.dll
• the Microsoft Winsock Control 6.0 (latest SP), %SystemRoot%\System32\MSWINSCK.OCX
• the Microsoft Common Dialog Control 6.0 (latest SP) , %SystemRoot%\System32\comdlg32.ocx

Environment Variable SECS_EQUIP_TCLDIR

SECS_EQUIP_TCLDIR=C:/usr/local/gem2/server

Environment Variable NO_DDE_QUERY

Development

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

Here is the general flow of using and configuring a SecsEquip instance:

1. Add a SecsEquip instance to your main form, it is invisible as runtime.  In our example application, we named the instance secs.  If you name your instance the same, you can directly cut-and-paste code from our example application.
2. Copy or create your own event handling code.  You will likely want to have at least a stub version handler for every event type.  See the Events reference section.
3. Just use one instance of the SecsEquip in your application.  Pass a reference to the SecsEquip to child forms by declaring "Public secs as SecsEquip" in the child form code, and then executing "set child.secs=secs" in your main form code.
4. You can change the control properties such as MDLN and SOFTREV by working with the VB Form editor, or you can write code statements that set the properties to your desired values.  The Form_Load method for your main window is an appropriate place to call a subroutine for your initialization.   The control starts out with communication disabled so you are able to configure the interface before going online.
5. Call the Init method early, before making other configuration method calls.  Its very similar to a class constructor method and it initializes some important data structures.
6. Now perform the bulk of your SECS interface configuration.  Do the following, in any order:
• change properties such as DEVID, timer values, MDLN, SOFTREV, ...
• add equipment specific alarm types using AlarmAdd
• add event types using EventAdd
• add Equipment Constants (Parameters) using ParameterAdd
• add Status and Data Value Variables using VariableAdd
• register to handle additional SECS message types in your application using MessageTypeAdd.  You do not need to handle the core messages of SECS and GEM - they are already handled for you by the control.  You can optionally add support for Terminal Services or Remote Commands like our example application does.
7. Now your code can set the desired Control State properties and then call CommEnable to enable host communications.  You probably want to offer configuration dialogs and make the desired startup configuration of the Contol State and whether communication is enabled or disabled be user specified and persistent.
8. Call CommDisable to disable host communications.
9. When the SecsEquip control is terminated, it will take care of ending communication and terminating the SECS server process.  The SECS server process is also coded to shutdown if communication with your application is lost.  It is highly unusual for any additional automated or manual cleanup to be needed.

Tcl Secs Notation, TSN

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 VB application as a replacement for the null character \u0000.  This provides a work-around for the behavior of various runtime library functions that truncate the string display at the first embedded null.  The Hume VB6 API is able to work with embedded nulls in ASCII data and the Hume logic also converts the replacement character, charW(&HFFFD), 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 VC++ 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"

 

Built-in SECS Data, Message Handling, Events

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, its more efficient to use VariableSet which provides the current value to the SECS server process.  The VariableMethodSet method is the right choice for data items whose value changes more often, or are easier to manage as VB application data items.

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

 There also 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.
 

Custom SECS Message Handling

Logic in your application can send SECS messages or initiate conversations using the SendSecsMsg method.  For HSMS communication,  if you are sending a message and not waiting for the reply, SendSecsMsg can be used from your GUI code without fear of making your GUI unresponsive.  In some cases you need to wait for a SECS reply message.  If you are using HSMS, under most circumstances, the host's reply or failure to reply will be resolved within a few seconds.   The unusual circumstance is that you still have a TCP/IP connection to the host so your send is successful, but then the host does not reply, and you wait the full T3 period.  You can code your logic so that if the host does not respond to any message, you transition to offline control so subsequent message sends fail right away because they are not appropriate in an offline control state.  So with this change, you risk making the GUI unresponsive for a single T3 period in some unusual circumstances.

Miscellaneous Notes

SecsEquip Reference

 SecsEquip Properties

Property Name	Data Type	Description
AlarmsShareEvents	Boolean	Set this property value true to have the same AlarmDetected and AlarmCleared data collection events reported for any alarm type.  The preferred value of this property should be set before calling the AlarmAdd() methods.  The behavior preferred by the Photovoltaic Industry Draft Standard #4557 is to have the value set true and to share generic events.  The default value of the property is false to preserve compatibilty with existing applications.
BAUD	Integer	For SECS-I, the baudrate of the serial port.  Defaults to 9600.
CommState	String	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.
ControlIntentOnline	Boolean	Your intended GEM Control State behavior, whether your equipment is in the OFF-LINE or ON-LINE control state.  The default setting is false meaning that OFF-LINE is desired.
ControlModeRemote	Boolean	When in ON-LINE control, your intended substate of LOCAL or REMOTE control.  Defaults to false meaning that LOCAL control is desired.
ControlState	String	Read-only, your actual GEM Control State which reflects your ControlModeRemote, ControlIntentOnline settings 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 SecsEquip::ControlStateText string array, in the same order as ControlStateEnum values.  The StateChange event is used to obtain asynchronous notification of this property value change.
ControlStateStartup   ' control state values  Public Enum ControlStateEnum     OfflineEquipment = 0     OfflineAttemptOnline = 1     OfflineHost = 2     OnlineLocal = 3     OnlineRemote = 4 End Enum	Enum	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.
DEVID	integer	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 SecsEquip rejects messages from the host that are not for the equipment's Device ID.  Settable range is 0..32767.
DMHGroupName	String	The DMH message system groupname used by the SECS server.  Optionally passed to the Init method.  The default value is GEM. The VB SecsEquip is not designed to share a SECS server.  Every instance of the control should have a different DMHGroupName value.
HSMS	Boolean	Whether the Connection type is HSMS (LAN based).  False implies SECS-I, serial RS-232 communication.  Defaults to true.
HSMS_Host	String	For an active HSMS connection, specifies the TCP/IP hostname or IP address of the Host computer.
HSMS_Passive	Boolean	For an HSMS connection, whether the SecsEquip plays the passive, TCP/IP server role.  The default value is true which is the usual role of equipment.
HSMS_Port	Integer	For an HSMS connection, the TCP/IP socket port number.  Defaults to 5555.
IdRangeChecked	Boolean	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.
MDLN	String	The SECS Equipment Model Type - limited to no more than 20 characters by the E5 standard.
Name	String	The name of the SECS connection as passed to Init or as configured by the Name property of the connection instance. (Read-only).
ParametersAreSaved	Boolean	This property controls whether the values of parameters (Equipment Constant Variables) 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".
RecipesAreBinary	Boolean	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.
RecipeDirectory	String	A pathname to the file system directory where Process Program files are located.  The default is the subdirectory "recipes" of the directory specified by the SECS_EQUIP_TCLDIR environment variable.
ReportsAreSaved	Boolean	This property controls whether the state of event reporting is saved at the program exit and restored during the next session.  Saving the state of dynamic reporting is standard GEM behavior so the default value is true.  If the value is true, the saved event reporting configuration is restored the first time that CommEnable is called, unless it has been already restored by calling the method ReportsRestore.  In other words, you can use the method ReportsRestore to force loading of the saved reporting configuration before CommEnable is called.   The report configuration data is saved as a file of SQL statements in the subdirectory spooldata.  The filename used is "reportdata_" + Name + ".sql".
RTY	Integer	SECS-I maximum send retry, range 0..31, default 3.
SerialPort	String	For a SECS-I connection, the serial port device such as "COM1".
SOFTREV	String	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.
SpoolingAllow	String	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.
State	String	A read-only value of the low-level connection state.  Possible values include OFFLINE, LISTENING, and COMMUNICATING.  You will see the OFFLINE state if the connection to the host is broken.  The StateChange event is used to obtain asynchronous notification of this property value change.
T1	long	SECS-I Inter-Character Timeout in milliseconds, range 100..10000, default 500.
T2	long	SECS-I Protocol Timeout in milliseconds, range 200..25000, default 10000.
T3	long	SECS Reply Timeout in milliseconds, range 1000..120000, default 45000.
T4	long	SECS-I Inter-Block Timeout in milliseconds, range 200..25000, default 10000.
T5	long	HSMS Connect Separation Timeout - the delay between re-connection attempts in milliseconds, range 1000..240000, default 10000
T6	long	HSMS Control Transaction Timeout in milliseconds, range 1000..240000, default 5000
T7	long	HSMS Not Selected Timeout in milliseconds, range 1000..240000, default 10000
T8	long	HSMS Network Intercharacter Timeout, default value 5000.  This value is not used - there is no T8 property. .
TRACE	long	Used as a bitfield to control diagnostic trace information for SECS port activity which is passed to the application in the SecsTrace event.  By setting specific bits, the corresponding output is turned on.  General Tracing: (TraceType = trace)  Bit        Output Description  0x0001     Read and write calls 0x0002     state changes including connection attempts  Receive Tracing: (TraceType = rtrace)  Bit        Description for Received Messages  0x0100     Header binary dump  0x0200     Header interpretation  0x0400     Stream and Function description 0x0800     Message data binary dump  0x0004     The Message as TSN  Send Tracing: (TraceType = strace)  Bit        Description for Sent Messages  0x1000     Header binary dump 0x2000     Header interpretation 0x4000     Stream and Function description 0x8000     Message data binary dump 0x0008     The Message as TSN
TraceDataIsCompressed TraceDataIsSaved TraceDataSaveDir TraceDataSaveMaxDayFiles TraceDataZipCmd Public Function SetTraceSaving(save As Boolean, compress As Boolean,  maxDayFiles As Integer, saveDir As String, zipCmd As String) As RcResult	Boolean Boolean String Integer String	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 function is used to reconfigure the logging feature with the various properties being set atomically in one call. The individual properties set by the SetTraceSaving function are provided as read-only properties.  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 SECS interface.  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.exe -m tracetxt.zip. This command causes the data file from the previous day to be moved into the tracetxt.zip archive, creating the archive if it does not exist.   The compression logic appends the day file name to the configured command before execution.  Only trusted persons should be allowed to configure the compression command because of the security considerations.  The RcResult return value of SetTraceSaving() is used as follows.  If the rc value is less than 0 the arguments were not acceptable and an error message is provided as the result String.  If the rc value is 0, the call succeeded.  If the rc value is greater than 0, the call succeeded with an advisory message as the result String.  For example, a message occurs if compression is set true but there is a maximum of only 1 file, so there is no distinct file for the previous day to compress.
TracewinMaxWidth	Integer	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.  The VB listbox control seems to have a hardcode limit of about 1000 characters per line.  Range 800..120000, default 800.
UseS13	Boolean	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.

 

SecsEquip Events

Event Handler and Argument Data	Description
All event handlers - NOTES	The VB SecsEquip uses the single main application thread for event handling.  It is important to not "live" inside of event handling code, but to return control to the caller.  Do not call MsgBox in your application, or similar functions that do not provide for proper event dispatching during idle time.  When a MsgBox is displayed, your application does not respond to socket input.  If you have a Status Variable whose value is determined by the VarValueRequest event callback, the SECS interface cannot send an event report using the variable if your GUI is showing a MsgBox.  It is proper and recommended to use VB modal forms instead of MsgBox calls.
Public Event ParameterChange(varname As String, newValue As String)	This event notifies you of host initiated Equipment Constant Variable (ECV) changes.  The new value is within the limits you have configured.
Public Event SecsMessage(stream As Integer, func As Integer, send_reply As Boolean,   transactionID As Long, TSN_data As String, header As String)	See the MessageTypeAdd method described in the next section to see how to receive SECS messages in your application.  This mechanism is demonstrated for Remote Commands and for Terminal Services in the example application.
Public Event SecsTrace(traceType As String, text As String)	This 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.
Public Event ServerError(message As String)	The SecsEquip control reports Tcl programming errors that are trapped in the SECS Server process as ServerError events.  An example would be trying to send an improperly formatted SECS message.  These error events will happen during development but should be rare once the code is debugged.
Public Event SpoolingAlert(msgid As String)	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.  The latter two values are not seen in normal circumstances.
Public Event StateChange(varname As String, newValue As String)	This event notifies your application of state value changes. Possible varname values include  state - the State property value changed clock_offset - this value is the number of seconds added to the system clock to provide CLOCK variable values for the host.  If the value differs from 0, the host has used S2F31 to set the clock.  Your logic can work with host specified time values by adjusting the system time using this offset value, or by reading the CLOCK variable using VariableGet().  We recommend that you avoid this complexity by instructing your customers to use NTP time synchronization and that you disable S2F31 using MessageTypeRemove(). comm_state - the CommState property value changed control_state - the ControlState property value changed dataset_download - a process program has been downloaded from the host using Stream 13 transfer messages.  The newValue argument is a two item list, the ppid, and the pathname to the newly received file.  Use the ListElement or ListSplit method to parse the list.  See the discussion of downloaded files in the description of function ProcessProgramLargeRequest. dataset_upload - a process program was successfully transmitted to the host using Stream 13 transfer messages.  The newValue argument is the ppid. event - this value changes when a data collection event is posted either by your logic calling the EventPost method, or by the built-in SECS server logic.  The newValue argument is a two item list, the CEID of the event, and a 1 or 0 indicating whether an event report message was sent or not.  A report is not sent or spooled if communication is disabled, or if the event type is disabled, or if the control state is offline.  Also, when spooling is active, the event report may not be spooled. recipe_delete - the name of a recipe that is being deleted by the host, or being replaced with a downloaded version using Stream 7 transfer messages. recipe_download - the name of a recipe that has just been received from the host using Stream 7 transfer messages. recipe_upload - the name of a recipe that has just been uploaded to the host using Stream 7 transfer messages. spooling_state - the SecsEquip spooling state, ACTIVE or INACTIVE SpoolCountActual - the number of SECS messages currently spooled SpoolCountTotal - the total number of messages spooled and/or discarded SpoolMax - the configured maximum number of spooled messages SpoolStreamFns - the list of S<s>, S<s>F<f> message types that configured for spooling Your application gets notified of the initial values of these items when the SecsEquip connection type is initialized.
Public Event VarValueRequest(varID As Integer, ByRef varvalue As String)	This event occurs when the SECS interface needs to know the value of a Status or Data Value variable in order to answer a host query or to format the data of an event report.  See the VariableAdd method.

SecsEquip Methods

METHOD	DESCRIPTION
General Comments	Most of the List manipulation methods are implemented by the DMH.ocx, and exposed for your convenience by the SecsEquip control. If you have questions on the specific methods that are not answered by the documentation, take a look at the method's source code.
Sub AlarmAdd(ALID As Integer, ALTX As String) Sub AlarmAddEx(ALID As Integer, ALTX As String, alarmSetCEID As Integer,  alarmClearCEID As Integer)	Add an alarm type definition.  Newly created alarms are enabled.  The simpler AlarmAdd method 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 method. If the AlarmsShareEvents property is true, use only AlarmAdd and do not specify the set and clear event IDs.  Use any ALID value from 1000 to 3999.  If the AlarmsShareEvents property is false and you are using AlarmAdd, 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 40 ASCII characters.  The ALTX should not contain single quote characters. The extended form, AlarmAddEx(), 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 AlarmAddEx() 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.
Sub AlarmEnable(ALID As Integer, is_enabled As Boolean)	Enable or disable reporting of an Alarm type (S5F1).
Function AlarmIsEnabled(ALID As Integer) As Boolean	Test if the reporting of an alarm type is enabled
Function AlarmIsSet(ALID As Integer) As Boolean	Test if the alarmed state is currently set
Sub AlarmSet(ALID As Integer, is_set As Boolean)	Set or Clear the alarmed state of an alarm.
Function BinToInt(binValue As String) As Integer	Converts a SECS B (Binary  - Semi "10") data value usually formatted as a hexadecimal string to an integer value.
Sub CommDisable()	Disable SECS communication.  The SecsEquip is initialized without communication enabled so using this method only makes sense after CommEnable has been called.
Sub CommEnable()	Enables SECS communication.  The CommState property value will change and StateChange events will be received.  These changes are the asynchronous indications for success or failure to establish communication.  When your equipment is configured for the Active HSMS role, field personnel will want to display the trace window with the 0x0002 TRACE property bit set in order to see detailed information on the status of communication attempts.
Function ConnectTypeHsmsActive(host_or_ip As String, port As Integer) As Integer	This method is an alternative to setting the underlying property values to specify an active HSMS connection type, and calling ConnectTypeSet().
Function ConnectTypeHsmsPassive(port As Integer) As Integer	This method is an alternative to setting the underlying property values to specify a passive HSMS connection type, and calling ConnectTypeSet().
Function ConnectTypeSerial(comDevice As String, baudrate As Integer)	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.
Sub DebugDMHStatus(Show As Boolean)	This method causes the DMH message system status window to either be shown or dismissed.
Sub DebugInspect()	This method can be used to exec the Inspect introspection debugger.
Sub DebugTableWindow(Show As Boolean)	This method causes the Datahub table management GUI to be shown or dismissed.
Sub DebugTclConsole(Show As Boolean)	This method causes a console window for the SECS Server to be shown or dismissed.
Sub DebugTraceWindow(Show As Boolean)	This method is used to display a window which updates to show SECS message traffic and state information for the SecsEquip.   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.  The example application features the tracewin class and instantiates a native form window with similar function.  Including the form window in the administration area of your equipment GUI is desirable to help field personnel diagnose communication problems.
Sub EventAdd(CEID As Integer, is_reported As Boolean, description As String, Optional EventName as String)	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.
Sub EventEnable(CEID As Integer, is_enabled As Boolean)	Event reports are enabled for an event type when first created.  You can use this method to control whether an event report is enabled.
Function EventIsEnabled(CEID As Integer) As Boolean	Test if reporting of an event type is currently enabled.
Sub EventPost(CEID As Integer) Sub EventPostByName(EventName as String)	These methods are used to announce when an event has occurred.  Make sure that the variables whose values are stored in the SECS Server table, and which may be used in event reports, are set to their  current 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.
Function EventRenumber(EventName As String, newCEID As Integer) As Integer	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: 0 The event already has the desired ID, or the event was renumbered successfully. 1 The newCEID was in in-use so the existing event was renumbered to a "temporary" ID. 2 or more The return value is the number of events of this name that were found.  The extra table records were deleted and the surviving table record has the desired ID or was renumbered successfully.  This condition is not ordinarily expected. -1 The eventName does not identify an existing event. -2 The method did not succeed from an unexpected error such as a timeout. -3 The connection type has not been set and table records do not exist for renumbering.
Function Init( _   Optional Name As String = vbNullString, _   Optional dmhGroup As String = "GEM") As Long	This method is similar to a class constructor and should be called before making other method calls.  The Name argument becomes the name of a global data item and a Tcl command in the SECS Server process.  It needs to not coincide with a keyword in Visual Basic or the Tcl programming language, and also be distinct from common local variable names.  The default value of Name is taken from the (Name) property of the control instance.  Programmatically, this is obtained as Extender.Name.   The example application uses the Name value, secs.  The name should be a single alphanumeric token.   We recommend you use the value secs so you can copy our example code, or that you use a very distinct name like XYZGemTester. The dmhGroup argument becomes the DMH message system group name used by the SecsEquip and SECS Server process.  The groupname chosen needs to be unique among other DMH server instances on the computer where the SecsEquip 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 SecsEquip 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
Function ListAppend(ByRef List As String, _   e1 As Variant, Optional e2 As Variant, _   Optional e3 As Variant, Optional e4 As Variant, _   Optional e5 As Variant, Optional e6 As Variant) As Long	This method is used to add one to six list elements to text that is formatted as a list.  It is a good programming practice to use ListAppend or ListJoin to build a list, in order to make sure that imbedded white space or other special characters are properly delimited with curly braces or escaped with backslashes.  The call returns a success return code of 0.  The input List argument is modified by reference.
Function ListElement(List As String, index1 As Long, _   Optional index2 As Long = -1, _   Optional index3 As Long = -1) As String	This function is similar to the lindex function of Tcl.  It will parse text formatted as a list and return the specified element.  Indexing starts from 0.  Arguments index2 and index3 may be used to indicate that parsing of the list 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 lists.  Error 50008 is raised if an invalid list is parsed.
Function ListJoin(elements() As String) As String Function ListJoinV(ByRef elements As Variant) As String	Joins together strings as list elements forming a result string that is a list.  Braces are added as needed to delimit empty elements, or to delimit special character sequences involving backslashes , square brackets, etc.  ListJoinV is designed for use with the Array command: mylist = ListJoinV(Array("element 1", "element 2", "etc"))
Function ListSplit(TclList As String, _    ByRef elements() As String, _    Optional ByRef errorInfo As String) As Long	ListSplit( ) parses a string formatted as a list into an array of string elements.  The function understands the list notation usage of quotes, braces and backslash sequences.  Not all strings are valid lists.  The return value is 0 on success. Failure occurs when there are unmatched braces, unmatched quotes, or non-whitespace following braces or quotes. The number of string elements found can be determined by (Ubound(elements) - Lbound(elements) + 1)
Sub MessageTypeAdd(stream As Integer, func As Integer)	Call this method to have SECS messages of the specified type processed by your event handler code when the SecsEquip is in online control, and the message is received from the host.  You can provide for new SECS message types, or you can replace the existing SecsEquip handling of particular messages.  Use the SendReply, SendS9, and SendAbort methods to send reply messages.
Sub MessageTypeRemove(stream As Integer, func As Integer)	This method is used to cancel SECS message handlers that you have setup using MessageTypeAdd or to cancel the handling of particular messages during the online control state by the built-in SecsEquip logic.  For example, you may wish to turn of 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.
Sub ParameterAdd(varID As Integer, _   varname As String, _   description As String, _   value_TSN As String, initialValue As String, _   minValue As String, maxValue As String, defaultValue As String, _   Optional units As String = "")	This method is used to add Equipment Constant Variable definitions (ECVs).  With the default range checking active, use varID values that are between 1000 to 2999.  Use a unique value for each parameter.  The value_TSN argument is the Tcl SECS notation type code for the ECV value such as such as F4 for floating point, or A:80 for an ASCII string up to 80 characters long..  Call ParameterSet when the ECV value is changed by your GUI or your logic so that the SECS interface can issue the proper GEM events to the host, and so it knows the current value.  If the host changes a Parameter value, your application is notified with the ParameterChange event. With ASCII types, indicate the maximum number of characters, n, that you wish to allow the host to set, by using a type code of the form A:n.  The value of n can be as large as 60000. 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.
Function ParameterGet(varID As Integer) As Variant	This method is used to get the current value of an ECV.  The return value is a Null variant if there is an error, otherwise the return value is a string.
Sub ParameterSet(varID As Integer, newValue As String)	This method is called if your application wants to update the value of an ECV.  The SECS interface saves the new value in a table entry, updates the ECIDChangeName variable, and issues the 4020 GEM event if the value actually changes.
Sub ParametersRestore()	Restores the saved values of the parameters (Equipment Constant Variables).  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.
Function ProcessProgramDownload(ppid As String) As RcResult Public Type RcResult     rc As Integer     result As String End Type	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.
Function ProcessProgramLargeRequest(ppid As String) As RcResult Public Type RcResult     rc As Integer     result As String End Type	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 ProcessProgramDir for use, possibly overwriting an earlier version. If the transfer does not complete successfully, there is additional status information is the SECS server table ei_dataset_xfer.   It is possible to query this table or subscribe to data changes of this table to better integrate transfer status information. Possible error results include values of the ACKC7 reply to S7F41 and the following: 1 permission not granted 4 PPID not found 6 other error -6  error when sending S7F41 or receiving the S7F42 reply -13 PP transfers are disabled when spooling is active -14 A large PP receive is already in progress for ppid -15 Stream 13 transfers are disabled either from configuration or initialization failure -16 PPID is not usable as a restricted filename -17 error when parsing the S7F42 reply
Function ProcessProgramLargeSend(filename As String) As RcResult Public Type RcResult     rc As Integer     result As String End Type	This method initiates the upload of a process program to the host using the message types of Stream 13 which are designed for large data set transfers.  Using these messages is more complex than the usual Stream 7 transfer messages so they are less commonly supported.  The filename argument value is both the process program identifier and the file name that is used by the equipment for the process program file.  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
Function ProcessProgramUpload(ppid As String) As RcResult Public Type RcResult     rc As Integer     result As String End Type	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.
Sub 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.
Sub 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.  A connection type should be set and the variables and event types should be defined before calling this method.
Sub SendAbort(stream As Integer, primaryFunction As Integer)	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.
Sub SendReply(stream As Integer, _   func As Integer, _   transactionID As Long, _   TSN_data As String)	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.
Sub SendS9(func As Integer, header As String)	This method is used to send a Stream 9 error message response to a received message - it is sent in lieu of a normal reply.  The SecsEquip software takes care of many of the possible error conditions automatically, including, 1- bad Device ID, 3 - bad stream, 5 - bad function, and 9 - T3 timeout.  You will not receive a message type, unless you register for it.  Therefore, you will mostly send the function value 7 to indicate improper data.
Public Function SendSecsMsg(stream As Integer, _   func As Integer, _   reply_wanted As Boolean, _   TSN_data As String, _   wait4reply As Boolean) As String Public Function SendSecsMsgRcResult( _   stream As Integer, _   func As Integer, _   reply_wanted As Boolean, _   TSN_data As String, _   wait4reply As Boolean) As String Public Type RcResult     rc As Integer     result As String End Type	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 methods differ in how the return value data is presented.  The SendSecsMsg() return value is a string which is structured as a two element list consisting of an integer return code and a string result.  The string result is typically parsed with the ListElement() or  ListSplit() methods.  The SendSecsMsgRcResult() returns the same data already parsed into a structure that has an integer return code and a result string.    The possible return values are: -1 errorMessage  - the error message starts with "ERROR" and describes the fault -2 DISABLED   - communication is disabled so the message could not be sent -3  OFF-LINE   - the control state is OFF-LINE and per GEM only S1F1, S1F13, and S9FX are sendable. -4  DISCARDED   - spooling is active and this message type is not spooled.  Usually the connection is down.  But this result can also occur for a newly established connection before the host has purged or finished unloading the spool. -5  BUSY   - an eq_send call is currently active.  You should not see this error, since by design send commands are serialized using DMH messages to the connection's command mailbox. 1  SPOOLED    Your message has been spooled for later sending.  Even if you specify waiting for the reply result you receive this instead of the reply data if the message is spooled.  We recommend you not allowing spooling of message types where you care about the reply. 0  SENT_NO_REPLY  - sent successfully no reply requested 0  SENT_NO_REPLY_WAIT  - sent successfully, a reply was indicated, not waiting for the reply was indicated.  The reply will be ignored when it arrives. 0  ReplyTsnData   -sent ok, reply requested and received. -6  TIMEOUT  - sent ok, reply requested, no reply, T3 timeout.  -7  ABORTED  - sent ok, F0 abort reply received. -9 REJECTED  - sent ok, Stream 9 error message "reply".
Function ServerLicenseCheck as Integer	This function returns an integer code for the license status when using the SecsServer.exe.  An  OEM who features SECS/GEM as an option, can test whether a valid license is installed, in which case the return value is 0.  The check does not test or validate running with a Datahub SDK installation.  Return code values are: -1 SecsServer.exe is not found. An SDK installation is not checked. 0 a valid license is installed 1 no licenses.txt found 2 the licenses.txt file contains improperly formatted data 3 no license code found for the system in the licenses.txt file 4 invalid license code found for the system in the licenses.txt file
Sub ServerSQLCmd(cmd As String)	Send an SQL command to the SECS Server process without waiting for a reply.  This method is used by the SecsEquip software and made public in case of custom requirements.
Function ServerSQLReply(cmd As String) As String	Send an SQL command to the SECS Server process and wait for the reply.  This method is used by the SecsEquip software and made public in case of custom requirements.
Sub ServerTclCmd(cmd As String)	Send a Tcl command to the SECS Server process without waiting for a reply.  This method is used by the SecsEquip software and made public in case of custom requirements.  After a SecsEquip instance has been constructed and the connection type set, the TclCmd( ) method should be used instead of this method for commands that are directed to a particular interface instance.  Why?  Doing so serializes the commands for a particular interface, and provides re-entrant execution protection.
Function ServerTclReply(cmd As String) As String	Send a Tcl command to the SECS Server process and wait for the reply message.  This call is used by the SecsEquip software and made public in case of custom requirements.  After a SecsEquip instance has been constructed and the connection type set, the TclReply( ) method should be used instead of this method for commands that are directed to a particular interface instance.
Function SetTraceSaving(save As Boolean, compress As Boolean,   maxDayFiles As Integer, saveDir As String, zipCmd As String) As RcResult	Used to control Trace Data logging.  See the description in the Properties section.
Sub SpoolPurge()	This method discards any spooled messages that are queued for the host.
Sub SpoolStop()	This method sets the messages types that are enabled for spooling to an empty string, thus, further spooling is stopped.
Sub SpoolStreamFns(Optional StreamFns As String = "NULL")	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.
Function StartupLoad(name as String) As EquipStartupData See the SecsEquip.ctl source code for the definition and data members of Public Type EquipStartupData.	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.  The ToolUI form code demonstrates use of the method.
Function StartupRestore(ByRef esd As EquipStartupData) as RcResult	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. The ToolUI form code demonstrates use of the method.
Function StartupSave(ByRef esd As EquipStartupData) as RcResult	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.  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 ConfigurationDlg form code.
Sub TclCmd(tcl As String)	This method is used to send Tcl code to the SECS server command mailbox for the connection.  It is used by the SecsEquip software and made public to support custom requirements.
Function TclReply(tcl As String) As String Function TclReplyRcResult(tcl As String) As RcResult Public Type RcResult     rc As Integer     result As String End Type	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 SecsEquip 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..
Sub 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.
Function TsnTypeIsOk(value_TSN As String) As Boolean	This method is used to check value_TSN argument values that you pass to the various Add methods.
Sub VariableAdd(varID As Integer, varname As String, description As String, _   varClass As VarClassEnum, value_TSN As String, varmethod As VarMethodEnum, _   initialValue As String, Optional units As String = "") Public Enum VarClassEnum    DVVAL = 0    SV = 1 End Enum Public Enum VarMethodEnum    TableValue = 0    EventCallback = 1 End Enum	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.  With the default checking of Id values, use varID values between 3000 and 9999.  You can choose whether to keep the value of the variable current in the SECS Server table, or to have the SECS Server read the value using the VarValueRequest event callback.  If you choose the TableValue method choice, then call VariableSet when your logic changes the value.  If you choose the EventCallback method, then you must add code to your VarValueRequest handler to supply the value.  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.
Function VariableGet(varID As Integer) As Variant	This method is used to get the current value of a variable.  It uses the same access logic that host requests use so it can test your custom value logic.  The return value is a Null variant if there is an error.
Function VariableRenumber(varname As String, newVarID As Integer) As Integer	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: 0 The variable already has the desired ID, or the variable was renumbered successfully. 1 The newVarId was in in-use so the existing variable was renumbered to a "temporary" ID. 2 or more The return value is the number of variables of this name that were found.  The extra table records were deleted and the surviving table record has the desired ID or was renumbered successfully.  This condition is not ordinarily expected. -1 The varname does not identify an existing variable. -2 The method did not succeed from an unexpected error such as a timeout. -3 The connection type has not been set and table records do not exist for renumbering.
Sub VariableSet(varID As Integer, newValue As String)	This method is used to update the value of a Status Value or Data Value variable whose current value is represented in the SECS Server ei_variable table.
Sub VariableMethodSet(varID As Integer, varmethod As VarMethodEnum)	You can use this method to indicate whether the value of a variable (SV, DVVAL) is managed in the SECS server table, or managed using the VarValueRequest event callback. See the application example.

Built-in Features

License Terms

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

Hume Integration is also pleased to offer separate runtime licenses for using the VB SecsEquip software on systems that are not licensed as development systems.  Contact Hume Integration for information on the Resale Licensing program.

Document Version