Introduction

The component software consists of prototype applications to demonstrate both the equipment and equipment client roles described in the standard, along with Tcl language source code. The source code is customized and extended in order to deploy a production application for particular equipment. The EDA component software can be integrated with a SECS/GEM interface that has been developed using any vendor's toolset or with a SECS/GEM interface developed using the Hume Datahub SDK.

Installation

• edaequip (edaequip.exe on Windows platforms) - An application which implements the Equipment or server role of Interface A.
• edaclient (edaclient.exe on Windows platforms) - An application which implements the Host role of Interface A - the receiver of equipment data.

The terminology of client and server can be somewhat confusing with Interface A since both sides of the interface implement the HTTP server protocol to receive data from the other side, and both sides use the HTTP client protocol to initiate messages. The Equipment role is deemed the server since this side of Interface A serves process data and events to multiple clients.

For development, the EDA software extends the software base provided by the Hume Datahub SDK with new capabilities for using XML, SOAP, HTTP, and SEMI standard EDA messages. The component software also uses other packages found in the Hume Datahub SDK that are optionally installed. If you use the Hume Package Installation tool to install the EDA component, you are guided in selecting the needed prerequisites. The following software packages are needed:

• The Hume Datahub SDK core software.
• The Incr Tcl, Incr Tk, and Iwidgets packages option which extends the core software to include Object-Oriented programming commands.
• The Humelib package which is a library shared by the Hume Components.
• The Tcl xml version 2.6 package. This package is a patched and re-arranged version of the freely available xml and expat packages from Zveno Pty Ltd. Hume Integration has fixed memory leaks and made the package compatible with Starkits.
• Last but not least, the EDA component is installed to create the additional package library directory eda1.0.

Demonstration Applications

The edaclient application is designed to initiate messages to a single equipment instance at a time. You are expected to run multiple instances of the application, typically on multiple computer systems, to exercise the equipment's ability to support multiple simultaneous clients. Because the edaclient receives messages through an HTTP interface, it can actually receive EDA messages from any number of equipment servers simultaneously. So it is possible to use a single instance of the edaclient application, and in sequence activate Data Collection Plans with multiple equipment instances, and then collect the resultant data messages at the single edaclient instance.

As described in the standard, SEMI envisions that equipment supporting Interface A will also support a SECS interface. The two kinds of equipment interfaces are not necessarily interdependent - there is no need to deploy a SECS interface in order to have a fully functional Interface A. We think that there are situations where deploying only Interface A without a SECS interface makes sense, and the vision of Interface A only existing as a complement to the SECS interface will be revised. Opinions aside, the demonstration programs feature Interface A capability without SECS interfaces. The programs are intended to inspire confidence in the evaluator that Interface A technology is tangible, and that well designed, working software tools to deploy the new standard are available from Hume Integration Software. For the equipment provider, the Hume developed Interface A server software can be integrated into a controller system which may feature a SECS interface based on any software tools, not just the SECS/GEM software available from Hume. For the equipment integrator, the Hume developed Interface A client software provides all of the needed integration elements including HTTP protocol support, a full-fledged XML parser, and connectivity solutions for a wide variety of programming environments across various operating system platforms.

The Edaequip Application

The edaequip program embeds a functional HTTP (web) server.   If you configure an actual directory name for the httpd root directory, that directory and its contents are served by the web server and can be browsed by standard web browsers from anywhere on your network.  Its ok to configure a non-existent directory for the httpd root directory to avoid serving real files; the EDA interface will still function.  In most cases you will not configure the httpd interface value - the entryfield is usually left blank.  If you have multiple network cards, you can choose which network interface to serve by specifying its hostname or IP address as the httpd interface value.  You can also configure the httpd interface to the special value localhost.  The localhost hostname makes the EDA server interface visible only to software running on your own computer system, and your system will not be reachable from the network.

An important web server parameter is the httpd port integer value.  The value 80 is the default for the HTTP protocol. A particular port can be used by only one server at a time. In other words, unique port values need to be assigned to every TCP/IP socket server on a computer system. There is no problem having multiple instances of servers running as long as they serve unique ports. Application software is usually assigned port values greater than 1024 to avoid conflicts with system software. You will not be able to use the value 80 if you do not have system level privileges on the computer system.  In that case, it is recommended that a value greater than 5000 be used after examining the /etc/services file or reviewing the output of the operating system netstat command for possible conflicts.

The web server feature in not enabled until you press the Enable button.  This gives you a chance to configure a suitable directory and port before going online.  An Interface A client connects to your web server by specifying a URL that appears to be a document reference.  You are able to specify an arbitrary document name for the Url Document configuration value; the default value is EDA.xml.  When you press the Enable button, the status field labeled Served Url located just below the button shows the actual served URL that the client can use to connect to your EDA server instance.  You may change the httpd root directory, the httpd port, or the Url Document at any time by editing the field values and then pressing the Enable button again to have your new values take effect.  The change is nearly instantaneous.

Interface A has the notions of To and From address designations in the EDA message headers.  For both the edaequip and the edaclient program, you are able to configure unique values used as your own From address when initiating messages.   Unless you have a reason otherwise, we suggest you configure these fields to be the URL value that is used to connect to your program instance.  In fact, if you delete the current value so that the field is blank, the value gets set to your URL value when your HTTP server interface is enabled.

The edaequip user interface also provides entry fields to configure the data items making up the Equipment ID structure, namely Supplier, Model and ImmutableID.  From the standpoint of the current software, these are just arbitrary strings that are passed in messages.

The edaequip application implements the simple retry behavior specified in the standard when it is not able to successfully transfer a message to a client.  HTTP is a synchronous protocol; there is a reply expected in response to every message sent.  The Reply Timeout is the interval of time allowed for a client response to be received successfully.  If a response is not received, the logic will attempt a resend after delaying for the configurable Retry Interval value.  There is also a Retry Max Attempts integer value that is configured to set the number of attempts to be used when failure is encountered.  You are able to specify different values of these timeout and retry parameters for each client, or you may specify that the shared default values are used for a client by setting that client's values to the special value 0. The configured values in the framed window labeled Default Sending Configuration are the values used as default values for all clients that do not have their own non-zero configured values.

EDA Event Data messages have a Locator data element which is intended to help identify the context of the data.  You are able to configure the Locator data element using the entryfield labeled Event Location.

For demonstration purposes, the edaequip application relies on manual configuration of a set of Data Collection Plans.  The program logic creates example plan names if you have not configured and saved your own set.  A real Interface A application is integrated with the equipment controller(s) and the list of defined Data Collection Plans is determined programmatically.  The standard EDA messages do not show the client descriptions of the defined plans - the client only sees the plan names.  Also, the standard message definitions cannot properly handle plan names that imbed white space.

The main part of the edaequip user interface is a tabbed notebook window.  If the mouse selection button is clicked on the tab labeled Clients a different window pane is shown where the configuration of clients is displayed in a table.  New client records can be added by pressing the Add... button.  The To Address of each client record must be unique because this is how the clients are distinguished when client messages are received.  An implication of this behavior is that you must configure each client application instance to have a unique header From Address in order to have them all successfully communicate with your edaequip instance.  You can optionally specify a proxy host and proxy port if these are needed to reach the client HTTP server for messages initiated by the edaequip.  The editing dialog allows you to choose either the ok or disabled state value for a client.  If the state value is set to ok, it means that messages can be sent to the client.  If the state value is set to disabled it means that the logic should not attempt to send any messages to the client.  You cannot configure the state values of busy or down.  These values are set by the running software to manage sending to the client.  The state of down is assigned after the retry and timeout periods have been exhausted when attempting to send a message.  The logic does not attempt to send further messages to a client whose state value is down.  The client remains in the down state until that client has sent a message to the server, or until the user has reconfigured the client state value.

If you wish to save the current server configuration, use the Save menu action under the File menu.  Your configuration will be saved as files of SQL statements in the current working directory.  A saved configuration is loaded  automatically at the next program start.

The edaequip has other features to vary the displayed trace data of messages sent and received, or to save the displayed data to the file system.  There are also menu items to send example messages to clients.  You are encouraged to explore these features.  The EdaEnabled, EdaDisabled, and EdaError messages are broadcast messages - they are sent to every client that is not down or disabled.  The other message types are sent to a single selected client.
 

Host/Client Application

The entryfields in the window frame labeled Equipment Target Configuration are used to specify the Url and other items for your chosen EDA server.  Before you press the Enable button to have your HTTP server go online, you will need to review the configuration of the httpd port and make sure it is a unique and acceptable value, and make sure that you are satisfied with the other web server parameters.
 

Interface A Development

Here is an overview of the classes, the class names are linked to detailed information.

eda

The eda class is comprised of software that is common for both the equipment and the equipment client roles. For example, parsing XML and using an httpd server are done by both roles.

edaequip

The edaequip class has the logic needed to deploy the EDA equipment role. The class uses in-memory SQL tables to manage multiple clients.

edaclient

The edaclient class is designed to communicate with EDA equipment and play the client (host) EDA role.

Edatrace

This class provides the aggregate GUI widget that displays trace information in two scrolled text fields, one for Send & Reply tracing, and one for Receive tracing. The colors and fonts used are all configurable. The widget also provides the ability to save the displayed information to the file system.

ehttp

The ehttp class is used to execute the client-side of the HTTP protocol, either version 1.0 or 1.1. The class has diagnostic and tracing features that the EDA software makes use of.

ehttpd

The ehttpd class is used to provide the server-side of the HTTP protocol. It can serve common file types such as HTML pages and image files. The class has a URL callback feature that enables having custom software such as the EDA software provide the data of a requested document. The class also has excellent tracing and diagnostic features to support embedded use.

Incr Tcl Class Reference

Synopsis

none - instantiate edaclient or edaequip instead

This is a base class that has data and methods which are used for both the EDA server and client roles.

http_version

The class can be told to use either HTTP 1.0 or 1.1 by setting this variable to the desired version. The EDA standard specifies 1.1 and this is the default.

httpd_addr

You can optionally specify which network interface should be used for the HTTP server function either as a TCP/IP hostname or as an IP address. Use this option to specify the desired interface when you have more than one TCP/IP network address, or you want to restrict the serving to your own system by specifying localhost. When the field is blank, the default behavior is operating system dependent but usually makes the server visible on the first TCP/IP network interface and on the localhost interface. For some operating systems, the served port is reachable on all network interfaces.

httpd_doc

This item is the document name that is served by the HTTP server for the purpose of being a target for EDA communication. The document does not have to exist. The default value is EDA.xml

httpd_port

This is the TCP/IP port value that is used to receive EDA messages. The value 80 is the default for the HTTP protocol. A particular port can be used by only one server at a time. In other words, unique port values need to be assigned to every TCP/IP socket server on a computer system. There is no problem having multiple instances of servers running as long as they serve unique ports. Application software such as the edaclient is usually assigned port values greater than 1024 to avoid conflicts with system software.

httpd_root

The root of the file system to be served. A non-existent directory can be named if you do not wish to serve documents. Do not specify a directory containing private data files, or having private files in any subdirectory.

soap_nsid

The SOAP namespace identifier used for outgoing messages.  Defaults to "soap".  The value "SOAP-ENV" is also commonly used.

TRACE

This field is used as a bitfield to control the output of diagnostic information. The bit values have the following meanings:

0x0001

status messages

0x0100

Received HTTP header data

0x0800

Received HTTP query data

0x1000

Sent HTTP header data

0x8000

Sent HTTP content data

boolean value

This method maps any of the allowed boolean formats in Tcl such as true or 1 to the values 1 or 0 which are useable for EDA boolean values. It can also be used in the opposite direction to map any of the allowed EDA boolean values to 1 or 0.

dateTime {ts16 {}}

When called with no argument, the method returns a standard dateTime value for the current time. The method can also convert a localtime 16 value to an XML dateTime value.

fmtEqIDMessageBody type SupModId {nv_args {}} {sanitize 1}

The method returns a formatted XML string for the EDA message structures that contain an EquipmentID as the first item. The type argument is the message type such as IsEdaEnabled. The SupModId is a list of three elements, the Supplier, Model, and ImmuteableID. The nv_args is an optional argument to pass in a list of alternating tagnames and values to be appended to the message after the EquipmentID. If the nv_args contains nested tagnames and values, then the sanitize argument must be set to 0 to prevent escaping the nested tag angle brackets as if they were intended to be simply part of the data value.

fmtEquipmentID SupModID

The calling argument is a list of three elements, the Supplier, Model, and ImmutableID. The return value is a formatted XML string for an EquipmentID data structure.

fmtFault faultcode faultstring {detail {}}

This method returns a formatted XML string for a SOAP Fault data structure.

fmtMessageHeader To From {CorrelationId {}}

This method returns a formatted XML string for the MessageHeader structure.

fmtSoapEnvelope header body

This method returns a formatted XML string where the EDA message header and body are wrapped in SOAP Header and SOAP Body tags and then wrapped together in a SOAP Envelope tag.  The identifier used for the SOAP namespace is the configurable value of soap_nsid.

getFrom

This method returns the default From header data element which is the result of executing getURL.

getURL

This method returns the served URL for the HTTP receiving interface.

httpd_doc_set

This method is called automatically when you configure the httpd_doc value. It updates the HTTP server so that the desired document is served.

httpd_enable on

This call is used to enable or disable the HTTP server interface depending on if the on argument is 1 or 0.

httpd_respond

This method is replaced in derived classes. The method is executed by the HTTP server logic as a callback when there is a request for the EDA URL.

httpd_trace

This method is replaced in derived classes. The method is executed by the HTTP server logic to pass trace information.

SOAPhttpHeader action

This method supplies the SOAPAction header string that appears as an HTTP header for the specified message type.

tsdiff ts_start {ts_end {}}

Returns a floating point value for the number of seconds between two XML dateTime values or between the current time and a single dateTime value. The input format for XML dateTime values is restricted to the format provided by the dateTime method.

xml_desanitize xml

This method replaces & escape sequences which are used with XML to pass characters which have special meaning such as < back to the non-escaped characters. The method is called by the xml_sanitize method so that you can call the xml_sanitize method more than once without converting &amp; to &amp;amp; etc.

xml_desoap cache {update_struct 1} {copy_struct 0}

The method xml_parse described next is used to parse an XML string into an array. After parsing, the xml_desoap method can be called to remove the SOAP tags from the parsed result, to determine the EDA message type and write it as the array element __msgtype__, and to update the array element __struct__ which describes the message structure. The revised __struct__ element describes the simplified message structure that remains after the SOAP tags have been removed. If the optional argument copy_struct is set true, and the update_struct argument is true, the original message structure before the SOAP tags removal is copied to the array element __struct0__. The return value of the xml_desoap method is 1 if the input xml was standard and had the expected SOAP tags. The return value is 0 if the SOAP tags were not found. In this description, SOAP tags refers to the tags, <soap>:Envelope, <soap>:Header, and <soap>:Body where <soap> is the namespace identifier used for the SOAP namespace.   To understand this method and xml_parse in detail, it is suggested that you interactively execute them from the command prompt, and examine the result array cache using the info_data command. The method xtest8 is an example of using the parsing calls which features output to the console.

xml_parse xml

This method is called to parse an XML formatted string into an array. The name of the array is the return value of the method call. When you are done using the result array, you must unset it to recover the memory used for the array. Elements are added to the array which show the nesting of XML tags as the tag names concatenated with periods. For example, parsing the IsEdaEnabled message results in an array element with a subscript that is similar to soap:Envelope.soap:Body.IsEdaEnabled.EquipmentID.Supplier along with other similar array elements. The xml_desoap method described above removes the SOAP tags and simplifies the parse result so that the example subscript becomes IsEdaEnabled.EquipmentID.Supplier. The xml_parse method also writes an array element __struct__ which shows the structure of the XML input. For example, the __struct__ array element for an IsEdaEnabled message is similar to {soap:Envelope {soap:Header {MessageHeader {To} {From}}} {soap:Body {IsEdaEnabled {EquipmentID {Supplier} {Model} {ImmutableID}}}}}.


XML can have tag sequences that are repeated more than once. For example, there could be multiple values for the same measured parameter in an EdaData message. The parsing logic converts repeated values to a Tcl list of values. You can determine how many instances of a tagged value are in the input message by looking at the list length of the output array value, or by analyzing the __struct__ array element value.

EDA Param elements defined by the standard have the property that a tag for the type of data element (eg., IntVal, FloatVal, ...) is part of the tag sequence leading to the characters representing the element's value. The standard proscribes:

...<Value><FloatVal>43.56</FloatVal></Value>...

This property means that you cannot know the tag sequence leading to a value without knowing the data type tag being used. Fundamentally with XML strings all the data is passed as character string data, so this obsession with data type seems to be an anachronism. Hume Integration to the rescue - the xml_parse method has logic to rearrange Value tag sequences so that the array element for the Value tag shows the value and a new tag ValueType shows the tag used to indicate the data type. The parse result is as if the standard was:

...<Value>43.56</Value><ValueType>FloatVal</ValueType>...

This means that you can use the array of parse results, and find Param values at the same subscript irrespective of whether the sender tagged the value as FloatVal, DoubleVal, IntVal, or some other storage type.

xml_sanitize

This method is used by the methods that create formatted XML messages to escape characters such as < and & which may occur in your data and have special meaning to XML.

xtest8

The eda class has several methods such as this one which test or demonstrate various aspects of the XML parsing logic. It is suggested that the developer look over the source code and interactively execute some of these methods.

Synopsis

package require edaclient
edaclient::supervisor
edaclient objname [-option_name option_value]*
objname methodname [method_argument]*

This class is designed to target a single equipment URL at a time playing the Interface A client (host) role. You can have multiple instances of the class running in the same Tcl process to target multiple equipment instances simultaneously. The edaclient class inherits from the eda class so the options and methods of the eda class are useable for an edaclient instance.

client_From

This value specifies the string value that is used in the EDA message headers as the From field for this client instance. If the value is left as an empty string, the logic will use the instance's receiving URL.

eq_SupModId

This value is a three element list specifying the target equipment's EquipmentID data structure fields, the Supplier, the Model, and the ImmutableID.

eq_To

This value specifies the message header To value which is used when sending messages to the target equipment.

eq_autofix_config

This option value is used as a boolean to determine whether the eq_To, and the eq_SupModId values should be automatically corrected with values that are parsed from received messages. The default value is 1.

eq_reply_timeout

The interval of time specified in milliseconds allowed for a reply from the target equipment for a successful send-and-reply transaction. Defaults to 20000.

eq_url

The URL of the target equipment. You must have this value configured correctly in order to communicate with the target equipment. The default value is http://localhost:80/EDA.xml.

getFrom

This method replaces the base eda version to allow for the user configuring the client_From option.

http_trace

This method is called by the ehttp software to pass back trace information. If the Tk GUI exists, the method passes the data into the Edatrace widget.

httpd_respond

This method is called by the ehttpd software when an EDA message is received. The logic oversees parsing the message and calling a message specific method of the name rsp_msgtype to pass the message data into the application.

httpd_trace

This method is called by the ehttpd software to pass back trace information. If the Tk GUI exists, the method passes the data into the Edatrace widget.

rsp_EdaData cache To From

This method gets called when an EdaData message is received from the target equipment. The XML message has been parsed, the SOAP tags have been removed, and the parse results are found in the array whose name is passed as the cache argument.

rsp_EdaDisabled cache To From

Similar to rsp_EdaData, above.

rsp_EdaEnabled cache To From

Similar to rsp_EdaData, above.

rsp_EdaError cache To From

Similar to rsp_EdaData, above.

supervisor

This method is called to start any interfaces that are configured for starting in the eda_client_startup table. If no rows are found in the table, a row is added with default data. This logic is so the edaclient application starts an interface if its data file does not exist.

tracewin

This method is invoked to create and show the Tk interface window for the client.

xact_ActivatePlan PlanID UntilDeactivated

This method does a roundtrip send-and-reply transaction to activate a Data Collection Plan. The return value is a two element list, return code and value. In the usual success case, the return code is 0 and the value is the IsActivated value from the reply message. See xact_generic below, for error return codes.

xact_DeactivatePlan {PlanID ALL}

This method does a send-and-reply transaction to deactivate a Data Collection Plan. The return value is a two element list, return code and value. In the usual success case, the return code is 0 and the value is the DeactivatedPlanIds value from the reply message. See xact_generic below, for error return codes.

xact_GetActivePlanIds

This method does a send-and-reply transaction to query the activated Data Collection Plans for this client. The return value is a two element list, return code and value. In the usual success case, the return code is 0 and the value is the ActivePlanIds value from the reply message. See xact_generic below, for error return codes.

xact_GetDefinedPlanIds

This method does a send-and-reply transaction to query the defined Data Collection Plans. The return value is a two element list, return code and value. In the usual success case, the return code is 0 and the value is the DefinedPlanIds value from the reply message. See xact_generic below, for error return codes.

xact_IsEdaEnabled

This method does a send-and-reply transaction to ask if EDA is enabled. The return value is a two element list, return code and value. In the usual success case, the return code is 0 and the value is the IsEnabled value from the reply message. See xact_generic below, for error return codes.

xact_generic action resulttag {nv_args {}}

This method oversees the generic transaction of sending an EDA command message, obtaining a reply within a timeout interval, and parsing a desired result item from the reply message. The return value is a two element list; an integer code, and a string value. If the transaction succeeds, the code is 0 and the string value is the resulttag value. A non-zero code indicates failure, and the string value has a diagnostic message. Here are the possible failure codes:

1

ehttp::geturl has returned an error possibly because of a malformed URL

2

A reply was not received or the equipment HTTP server returned an HTTP error code

5

The reply was not proper XML.

6

The reply was not a soap message.

7

The soap message reply did not contain the result tag.

8

The soap message reply did not contain the result tag and diagnostic error information was found in the reply.

xact_reply_parse

Used by xact_generic

xact_reply_wait

Used by xact_generic

Synopsis

package require edaequip
edaequip::supervisor
edaequip objname [-option_name option_value]*
objname methodname [method_argument]*

This class is used to provide the equipment role of SEMI Interface A. To integrate this software into a production application, pay particular attention to the methods whose names start with ii_. This prefix has the meaning of integration interface. By coding your own version of these methods, you will make your equipment respond to the commands that are received through Interface A. In addition, you will need to provide for sending data and event messages as determined by the activated Data Collection Plans. The methods whose names begin with eg are examples of creating different EDA message types that equipment inititates. The example application edaequip is able to send an example message of every currently defined EDA type. The method broadcast is used to send the same message to every client. Certain EDA message types are broadcast such as the EdaEnabled message. The method postmsg is used to send an EDA message to a single client. As long as a client's Data Collection Plan is still active, your equipment should continue to post data messages selected by the plan. If the client becomes unresponsive, all of his activated plans will be deactivated. This occurs after a series of retry attempts spanning a series of waiting periods, so it is common that there may be more than one data message queued for delivery to the client. Your logic will know to stop posting messages for a plan from any of the following inputs:

1. The plan is no longer listed in the eda_client_active_dcp table so it was deactivated. Your logic could know this by querying the table at the time of sending, or by subscribing to changes in the table data.
2. You have customized the ii_DeactivatePlan method and your logic was executed when the method was invoked to deactivate the particular plan for the particular client.

eq_From

This value specifies the string value that is used in the EDA message headers as the From field for this equipment instance. If the value is left as an empty string, the logic will use the instance's receiving URL.

ImmutableID

This string value should be set to a unique value. It is part of the EquipmentID data structure.

IsEnabled

This variable is used as a boolean to determine whether the Interface A is enabled by the stock ii_IsEdaEnabled method. Its value is provided in response to the IsEdaEnabled client request. An integrator can choose to update this variable's value or to customize the ii_IsEdaEnabled method.

Locator_default

Certain EdaData messages have a Locator value which is intended to be an identifier for an equipment component based on its position in the tool hierarchy. See paragraph 7.7.3.3.1 in the standard PR8/3563. This option provides a configured value which can be used as a default value.

log_period

The log_period is a configurable interval of time specified in milliseconds for completed messages to be held in the eda_send_log table. There needs to be a provision for deleting aged messages from this table so that memory usage remains bounded. The edaequip application does not delete logged messages, it is designed for the user to delete them by pressing a button on the GUI. A real application needs to have programmed deletion of the logged messages, and using this value with the Tcl after command is suitable.

Model

This string value gets passed as part of the EquipmentID data structure.

reply_timeout_default

This value represents the time interval in milliseconds that is allowed for successfully receiving a reply from a client. The value is a default value that is used unless there is a non-zero configured value for the particular client.

retry_interval_default

This value represents the time interval in milliseconds that the equipment waits before initiating another send attempt when the previous send has failed. The value is actually a default value that is used when there is not a positive value configured for a client.

retry_max_default

This value is the maximum number of times the sending logic will retry to send a message to a client. The value is a default that is used if there is not a positive value configured for the client.

Supplier

This string value gets passed as part of the EquipmentID data structure.

broadcast msgtype {nv_args {}}

This method is used to send the same message to every client. Standard broadcast message types include EdaDisabled, EdaEnabled, and EdaError. The methods EdaDisabled, EdaEnabled, and PerformanceWarning are examples of using the broadcast method to send these message types.

EdaDisabled

Sends the EdaDisabled message to all clients.

EdaEnabled

Sends the EdaEnabled message to all clients.

egEdaErrorBody

Creates an example EdaError message body.

egEventReportBody

Creates an example Event body.

EgExEventBody

Creates an example exception event (ExEvent) body. The Interface A standard has further muddied the water by adding SOAP faults, HTTP errors, ExEvents, and EdaErrors to the E5/E30 notions of alarms and events. The standard indicates alarms are to be sent as ExEvent data structures, and EDA interference with tool operation is sent as an EdaError. Therefore we offer this guidance. If an error condition relates to the equipment and is independent of the Interface A software use the ExEvent data structure. Only use the EdaError if the error condition directly relates to the Interface A software.

fmtEdaDataBody Events

This method prepares an XML EdaData string by adding the EdaData tags and the EquipmentID structure to zero or more Event or ExEvent sequences concatenated as a single string argument.

fmtEdaErrorBody ErrorCode {ErrorType {}} {ErrorDesc {}} {ErrorTime {}}

Formats error information into the XML EdaError string. If the optional arguments are defaulted, the logic attempts to look up the error description in the common array ErrorCodes

fmtEventBody EventID Locator Data {EventTime {}} {Context {}} {Extension {}}

Formats event data into an XML Event string.

fmtEventReportBody EventID name_vals

A simpler call to create an XML Event string with some Data Param values. The name_vals argument is a list of alternating name and values which are formatted as floating point Data Param elements.

fmtExEvent ErrorCode Locator ExType ExDesc {ExState none} {ExTime {}} {Severity {}} {Data {}} {Extension {}}

Formats exception event data into an XML ExEvent string.

fmtParam Name Value {type FloatVal} {Locator {}} {MeasTime {}} {Extension {}}

Formats parameter data into an XML Param string.

fmtResponseBody type {nv_args {}} {Error {}}

Generic logic to format the XML reply for any of the client data management commands. The type argument is the response message type such as IsEdaEnabledResponse. The caller passes in the name and value items for response body as an alternating list, nv_args. The caller can optionally pass in Error data as a 1, 2, or 4 element list. See the logic of fmtResponseError.

fmtResponseError Error {skip_tag 0}

Formats error item data to create the XML Error structure. The caller can pass in varying amounts of data and have the logic supply the remaining items. If the Error list length is 1, it is assumed to be an ErrorCode and the description is looked up in the ErrorCodes array. If the length is 2, the first item is the ErrorCode as before, and the second argument is taken as a value to be substituted in the looked-up error description. If the list length of Error is 4, the logic assumes the caller is passing the fields ErrorTime ErrorType ErrorCode and ErrorDesc in that order. The logic ordinarily adds the surrounding XML Error tag, but this is suppressed by setting the skip_tag argument to 1.

getFrom

This method replaces the base class version with provision for the user setting eq_From. The result string is used as the From and To header address for the equipment instance.

http_send_callback token

This method is called asynchronously by the ehttp software after completion of sending or completion by failure.

http_trace token bit data

This method is called by the ehttp software to pass trace information.

httpd_respond url httpd_cache

This method is called by the ehttpd software when an HTTP request has been received for the equipment's URL. Inbound EDA commands are received by this method. The logic oversees parsing the message and calling a message specific method of the name rsp_msgtype to pass the message data into the application

httpd_trace

This method is called by the ehttpd software to pass trace information.

ii_ActivatePlan From dcp_id persistent

This method is called to activate a Data Collection plan for a particular client. The response logic has already validated that the plan is defined and that the client is configured and valid. The stock version manages the state of plans in the SQL table eda_client_active_dcp. The method should return 1 if the plan was successfully activated or 0 if not.

ii_DeactivatePlans From plans

This method is called to deactivate a list of one of more plans for a client. If the client indicated the keyword ALL the response logic has already converted this to the list of active plans by calling ii_GetActivePlanIds. The method should deactivate the indicated plans and set the return value to the list of deactivated plans.

ii_GetActivePlanIds From

This method returns a list of the active plans for the client identified by the From header value.

ii_GetDefinedPlanIds

This method returns a list of all of the defined Data Collection Plans.

ii_IsDefinedPlan dcp_id

This method is used to determine if a data collection plan ID is valid. The method returns 1 if the plan is defined, else 0.

ii_IsEdaClientRecognized From

This method returns 1 if the client identified by the From header value is properly configured and allowed to manage plans. A newly discovered client is not allowed to manage plans until his record in the SQL table eda_client is updated and his send_state value is set to ok.

ii_IsEdaEnabled

This method is called to determine the answer to the client request IsEdaEnabled. The method should return 1 to indicate that the EDA interface is enabled, else 0.

PerformanceWarning

Creates an example EdaError message for the situation of the EDA activity adversely affecting equipment performance.

postmsg client_id msgtype body {ts_send {}}

This procedure adds the header and soap envelope to an EDA message and sends it to a specified client.

rsp_ActivatePlan cache To From

This method is called by httpd_respond to oversee handling of the ActivatePlan message.

rsp_DeactivatePlan cache To From

This method is called by httpd_respond to oversee handling of the DeactivatePlan message.

rsp_GetActivePlanIds cache To From

This method is called by httpd_respond to oversee handling of the GetActivePlanIds message.

rsp_GetDefinedPlanIds cache To From

This method is called by httpd_respond to oversee handling of the GetDefinedPlanIds message.

rsp_IsEdaEnabled cache To From

This method is called by httpd_respond to oversee handling of the IsEdaEnabled message.

supervisor

This method is called to start any interfaces that are configured for starting in the eda_server_startup table. If no rows are found in the table, a row is added with default data.

tracewin

This method is invoked to create and show the Tk Interface A GUI for the equipment.

Synopsis

package require eda
Edatrace objname [-option_name option_value]*
objname methodname [method_argument]*

The Edatrace class is used to create the trace information display widget that is a prominent feature of the GUI in the edaequip and edaclient applications. The widget combines two scrolledtext widgets with some buttons to enable saving and managing the trace display. Most of the options for the scrolledtext widget are also options for this widget, which allows you to easily customize colors and fonts.

buttonfont

The font used for the buttons.

buttonheight

The height of the buttons.

buttonwidth

The common width of the buttons.

color_status

The color used to show status data. Defaults to DimGrey.

color_recvHdr

The color used to show received HTTP header data. Defaults to SlateBlue1.

color_recvData

The color used to show received HTTP content data. Defaults to blue.

color_sentHdr

The color used to show sent HTTP header data. Defaults to OliveDrab.

color_sentData

The color used to show sent HTTP content data. Defaults to green4.

wanttime

Defaults to true, determines whether the current time is displayed with status data.

http_trace statevar bit data

This method gets called to add more data to the Send & Reply Trace.

httpd_trace statevar bit data

This method gets called to add more data to the Receive Trace.

save component {pathname {}} {mode w}

A method invoked by the buttons to save the displayed data.

saveas component {mode w}

A method invoked by the buttons to save the displayed data.

Table Schema

eda_client Table - Basic client data

eda_client_active_dcp Table - Activated Data Collection Plans

eda_client_startup Table - Configuration of Client startup instances

eda_datacoll_plan Table - Data Collection Plans

eda_schema Table - Table schema descriptions

eda_send_log Table - Logging of sent EDA messages

eda_send_Q Table - In process EDA messages

eda_server_startup Table - Configuration of edaequip startup instances

Document Version

This document covers the Hume Integration Software developed Interface A Component which is available for the Tcl 8.4/Tk 8.4 environment on the Windows XP/2000 and UNIX/POSIX platforms.