Software messaging system

[0002] The present invention relates to software programs that comprise software compliant, inter alia, with the Microsoft Component Object Model (COM) specification (and improved versions thereof, including but not limited to COM+), and in particular, to a system for minimizing modifications to modules in a software system when new functionality is added to the system, and for exchanging messages between software modules.

[0003] A software system is generally comprised of multiple modules which communicate among each other by passing messages. For a message to be passed, the programmer must designate a format for the message, and write software to allow: (a) the sending program to encode the message in that format; and (b) the receiving program to decode the message in that format. The “encoding” comprises, in essence, determining the number, data types and sequence of the parameters for the message.

[0004] It is often desirable to modify software to add new functionality. In many instances, the new functionality does not add any new data, but merely uses data that is defined elsewhere in the system. Often, this existing data exists in the messages that are passed among the pre-existing modules. Nevertheless, to add the new functionality, it is usually necessary to modify the pre-existing modules that reference the data upon which the new functionality is based, and add references to the newly written modules that implement the new functionality.

[0005] For example, consider a simple system comprising a control module and a reader module. The existing functionality of the control module is to send a “read request” message to the reader module requesting the reader module to obtain a data reading from an attached (physical) reader, and the reader module sends a message back to the control module containing the reading. Suppose the system needs to be improved to add a module for logging every command or reading generated by each module of the system. In this example, the control and reader modules would both need to be modified so they by copy the command and reading data to a log file. For such a simple system, this may not require much work. However, most real systems would include hundreds of modules and objects, and each one would require modification. This would be a significant undertaking.

[0006] One object of the invention is to provide a software architecture that allows new functionality to be added to a pre-existing software system with few, if any, changes to the pre-existing software modules, by creating a new software module that merely accesses previously defined messages exchanged among the pre-existing software modules.

[0007] Another object of the invention is to provide a technique for encoding software messages according to a common format, so that any software module may receive a message sent by any other software module and extract from it the data it needs, regardless of how much other, unnecessary data may be included in the software message.

[0008] Another object of the invention is to provide a technique for changing the way messages are routed without changing software and without re-compiling.

[0009] Another object of the invention is to provide a technique for defining types of messages that are exchanged among software modules so that a programmer can specify characteristics of a message to be sent or received using a small number of lines of code.

[0010] Another object of the invention is to provide a software system in which software modules that send and receive messages according to a common format may use a single control for encoding and decoding messages in the common format, so that a programmer needs to write a small amount of code to send or receive messages in the common format.

[0011] FIG. 1 shows the general components of a software architecture which may be combined in one embodiment of the present invention.

[0012] FIG. 2 illustrates the merging that occurs when CopyAll method of the Messaging Control is applied to two messages.

[0013] FIG. 3 shows a representative structure of the ID numbers of messages and submessages formatting according to one embodiment of the present invention.

[0014] FIG. 4 shows the operation of the receiver thread of the Router with regard to message reception.

[0015] FIG. 5 shows the interaction of the receiver thread and the sender thread with the message queue of the Router.

[0016] FIG. 6 shows a representative excerpt of the hierarchical nature of message definitions in the Keeper Registry.

[0017] The invention comprises a software architecture that can eliminate or minimize changes to pre-existing software when adding new functionality. The principle features of the system are as follows.

[0018] 1. A module called the Router. Instead of modules in a software system directly sending their messages to other modules, the modules send their messages to the Router. The Router, in turn, sends each received messages to each module that needs the particular message. The Router accesses a routing table to keep track of which modules should receive which messages. In one embodiment and as an option, individual modules may, during program execution, register and unregister requests to receive messages of various types from the Router.

[0019] 2. Because messages passed among modules are usually in a virtually unlimited variety of formats, it is desirable to provide a common, flexible message format that allows the individual software modules to send and receive any message regardless of the data contained in the message. Accordingly, the invention includes a method for encoding messages to be transmitted and decoding (or parsing) received messages. In one embodiment, the encoding method comprises a hierarchical message encoding format.

[0020] 3. A system database called the “Registry,” which allows various message types to be defined, and a module for manipulating the Registry, which together are called a “Keeper.”

[0021] 4. A common software control (the “Messaging Control”) is provided that can be included in each module of the system that uses the disclosed messaging technique. The Messaging Control interfaces with the Router. Specifically, the Messaging Control does the following:

[0022] a. Formats or “builds” all messages from the module so they are in a predetermined format. Each message may include a five-part address, comprising: ToName, ToType, FromName, FromType, and MessageType.

[0023] b. Sends all messages to the Router.

[0024] c. Receives and decodes all messages from the Router, and triggers an event in the Module in which it is embedded.

[0025] d. “Registers” message receipt requests by sending the Keeper (via the Router) specifications for the types of messages the Module wishes to receive.

[0026] e. “Unregisters” message receipt requests by sending the Keeper (via the Router) specifications for the types of messages the Module wishes to stop receiving.

[0027] One advantage to this architecture is that, when new functionality needs to be added to the software system in which some or all of the data needed exists in existing messages, few, if any changes are required to the pre-existing software modules. This is because the new functionality can be isolated to a newly developed software module. This new module merely sends to the Router a message indicating which pre-existing types of messages it wishes to receive.

[0028] The invention is particularly useful in software environments that experience frequent modifications, such as changes caused by continual improvements in hardware controlled by the software system, such as a robotic control software environment.

[0029] One embodiment of the invention comprises a software environment designed to ease the integration of robotic systems and to streamline the addition of new components. One feature of the invention is the ability to easily change the implementation of any one piece (module, also referred to as a component) without affecting other parts.

[0030] Many different things are involved in producing a system; for example, in a generic automation system, the following need to be developed:

[0031] Robot(s)

[0032] Software to control the robot(s)

[0033] Instruments and hardware (reader, hotels)

[0034] Software to communicate with instruments

[0035] Pre-run configuration and parameter specification

[0036] Communication software between scheduled tasks and the instruments

[0037] Run-time interface

[0038] Data collection software

[0039] To integrate these components into an automated system, they all must be able to interact. Without protocols to define interrelations, each system requires custom code making it different from all other systems and difficult to update. The present system attempts to regulate the interactions between components by defining a common interface, and isolating modules behind this interface.

[0040] The pieces in the above list fall into categories and each category takes on responsibilities. Instruments communicate with a module, which has a Messaging Control software component which facilitates its interaction with other modules. FIG. 1 shows the functions of different components in such a representative system, as well as two instruments and a data log file, which are external to the system. (In contrast, in a prior art system, each of the executive module, instrument driver 1 module, instrument driver 2 module, run time status module and data logger module might all have arrows between each other, indicating that all message are exchanged directly among these modules. Also the Router and Messaging Control (MC) would not be present.)

[0041] The various parts of the system are separate and independent of each other; they are each written to perform a certain function (e.g., device communication, user interface, data logging, etc.) without tight cohesion to another module. In effect, each module is like a black box with a set of inputs and outputs; to create a system, the appropriate black boxes are assembled and connected to each other. If a particular piece of the system needs to be modified, only its black box is changed. Any number of data consumer modules may be “connected” to the output of a module; similarly, any number of modules may provide inputs to a module.

[0042] In order to provide functionality, each module cannot operate on a completely independent basis, and communication between modules is well defined. Messages can be sent between modules to trigger an action, or as a reply to a previous message. Individual modules register which types of messages they wish to receive. When a message is sent, it is routed to all of the modules which have requested it.

[0043] One embodiment of the present invention parallels some fundamental operating systems concepts. The idea of a central kernel leads the system to have a Router which is connected to at least two modules (similar to a process which has protected memory). A Messaging Control (MC in FIG. 1) embedded in each module provides a messaging interface to the other modules (somewhat akin to Windows messages). Newer operating systems have moved to a system database concept where programs register any services they provide and keep track of configuration information. One embodiment of the present invention implements this concept through a module called the Keeper which communicates to a database called the Registry where module options and other system-related information is kept (similar to Windows RegEdit and Windows Registry). When integrating a new system, almost all of the configuration information may be stored here. Modules are brought together and then configured in the Registry so as to perform properly. Configuration settings are made in the Registry (e.g. COM ports or digital I/O settings) along with defining ‘connections’ between module inputs and outputs.

[0044] The module called the “Executive” could be several different things: an interpreter that reads data files, a custom front end accepting real-time user input, a program that has a hard-coded set of actions to take, etc. The important point is that the Executive is the driving force behind the system; somehow it decides what needs to be done (such as reading a plate in a robotic system) and issues the appropriate commands. It is not, however, the Executive's responsibility to deal with the details of communicating with the hardware (in this case a reader), logging data and displaying it for the user. It assumes that the system designer will put in place modules to deal with those things; it deals only with its own high-level responsibilities. The same philosophy holds true with each module in the system. The reader module only needs to handle communication and configuration of its associated hardware; while it does produce data and status information, it is not responsible for saving it, presenting it to the user or whatever else the system designer may wish. The module simply packages it in a standard format and sends it out. It is up to the system designer to see to it that there are appropriate modules to handle the data (i.e. consumers). If the system does not need to handle the data, no module is configured to listen to or collect the output, so the data is simply thrown away.

[0045] A conventional Executive module may interpret a data file and monitor the other modules when the system is running. The first thing that happens is that the two major data consumers in our example are loaded (the Data Logger and Run-Time Status Module). The Data Logger, upon being loaded, will tell the router that it wishes to receive all data messages, and the Run-Time Status Module will tell the Router that it wants to receive all status messages. Then these modules will just sit and wait for their respective messages. At this point the Executive loads and begins to parse its code file; in the code file it finds the commands that it needs to send out and which modules to send them to. It loads all of the modules that it will be sending commands to and waits for them to initialize. In this case, the Instrument 1 (reader) and Instrument 2 (plate handler) modules are loaded. The Reader and plate handler will both tell the Router to send them all command messages, and begin waiting for commands to arrive. When the Executive comes to a command to be sent to the Reader, the Executive tells the Router to send the Executive all command completion messages from the Reader; the Executive is “listening” for the completion of its command. It then sends out the command and begins waiting. The Reader, having previously requested that it be sent commands, receives the command message from the Executive. The Reader module proceeds to carry out the command, communicating to the Reader hardware through a serial line or other medium. While it is carrying out the command, the Reader produces several messages. First, it produces a status message when it starts carrying out the command; the message, in essence, says that the Reader is now busy carrying out the command. The status module receives this message and displays the information for the user. Later, when the Reader has finished reading the plate, it sends out a data message with the data that it has gathered. The Data Logger receives the data and logs it to a file or places it in a database. The Reader also sends out a status message to the effect that it is no longer busy; again, the Run-Time Status module picks the message up and displays the information for the user. Finally, the Reader sends out the command completion message which the Executive has been waiting for. The Executive receives the message and continues on to the next command.

[0046] It should be noted that any of the modules in this system could be replaced if the functions needed by the system change. Clearly, one could not replace the Reader module with a Data Logger; the Data Logger has a different functionality set. Here is where the system designer must figure out what functionality is needed, and which modules will provide it. For instance, if a user wanted data logged to a database, a flat file, and a remote Internet site, the system designer need only add the modules that provide this functionality. The rest of the system is untouched and unaware of the change.

[0047] The Messaging Control

[0048] The Messaging Control (an OCX) comprises a common message handing control that provides the module writer with a means to communicate with other modules via messages. (A “message” as used herein and in the claims, is a hierarchically organized collection of string-value pairs. When a software module sends a message to an instance of an software object, the module decodes the message and performs the appropriate action. Generally, this action is to call one of the object's methods.) communication between executing software programs which is used to facilitate the execution of the software program. A software message is not, for example, a message sent via email.) The control has functions that allow the module writer to create messages, place data in messages, send out messages, request messages and save messages for later use. It also includes an event that is triggered when a previously requested message arrives.

[0049] In one embodiment, the software system is a modular system, and modules do not generally worry about exactly which modules receive their messages. For instance, a reader module will produce data, but it does not necessarily care where it goes. Similarly, the Reader does not have to care where its command messages come from. These decisions will be made by the person putting together a system; one might decide that the data from a particular module is of no use, or conversely, decide that it should be sent to several different modules. The Messaging Control, along with the Keeper module, allow for this.

[0050] The present system can be analogized to writing a letter and then giving it to your personal postal worker, telling him, “Send this to my relatives.” Now, this postal worker has been given information as to who your relatives are, and he can make copies of the letter and put an address label on each one; he can then put them in the mail and be assured that they will arrive in the hands of the appropriate people. Perhaps at some point in the future, the set of people termed “my relatives” changes (someone marries into the family). It is your personal postal worker's responsibility to realize that fact and the next time you send a letter to “my relatives” he will include the new person in the mailing. Similarly, if someone dies in the family, your personal postal worker does not send him any more letters.

[0051] The Router is analogous to the Post Office and the Messaging Control is analogous to the personal postal worker. The Messaging Control gets directions on where to send messages from the Keeper module (a central record keeping module). In one embodiment, each module in the system has a branch in the Keeper registry with a number of different leaves that come off of it; modules of the same type (e.g., two MultiPette modules) do not share a branch. Each has its own. One of these leaves (%Messaging) is set aside to hold message translations. This Messaging Control uses these message translations to take the name that you use (e.g., “My Relatives”) and translate it into an address that the Router (the post office) uses to get the message to all the appropriate parties.

[0052] Some representative entries in a %Messaging leaf node are as follows:

[0053] Data=*:*:%MN:%MT:Device Data

[0054] Device Command=%MN:%MT:*:*:Device Command

[0055] Device Command Reply=%RN:%RT:*:*:Device Command Reply

[0056] In one embodiment, the entries, called “message translations” are in the form:

[0057] For example:

[0058] <Translation Name>=<To Name>:<To Type>:<From Name>:<From Type>:<Msg Type>

[0059] The message Translation Name is the name that the module writer uses to refer to that message translation (i.e. type of message). The “message attributes,” (fields) on the right specify message characteristics, such as the addressing information; this is the kind of addressing information that the Router accepts. This includes, for example, the name and type of the module that the message is intended for, the name and type of the module that is sending the message and finally, a message type. The message type tells what is in the message (data, a command, status info, etc.). Note the fact that while one might address a message for a particular module, any module can request that message and receive it. In a similar way, the return address (the from name and from type) can be anything; they do not necessarily need to refer to the module that actually sent the message (e.g., impersonation of a module is possible).

[0060] When a module is requesting a message, the * character means “matches anything.” The translation EveryMessage=*:*:*:*:*, when requested, will match every message in the system. It is important to note that, in the preferred embodiment, when sending a message, the * character does not mean “matches everything”. Instead, it is simply interpreted as a star character.

[0061] %MN is a macro and refers to the module's own name (“current Module Name”). %MT refers to the module's type (“current Module Type”). These two are for convenience; they can just as easily be replaced by the actual name and type. %RN and %RT are a little different. They refer to the name and type of the module that is being replied to (“Reply to Name” and “Reply to Type”). That is, in one embodiment, when a module receives a command and wants to reply back to the sender of the command, these two fields get filled in by the Messaging Control with the “From Name” and “From Type” fields of the message being replied to. When a module gets a message that it will want to reply to, it tells the Messaging Control to save it; the Messaging Control will give the module a number that identifies the saved message. Later, when the module writer wants to reply, he can simply hand that number to the Messaging Control along with the message name to reply with. This “macro” capability makes it easier for a programmer to specify message characteristics.

[0062] When the Messaging Control receives a message, it searches the list of translations for one that matches; it starts from the bottom of the list and goes up. The first requested translation that matches is the only one used when receiving a message; translations which are not requested or which are ignored are always skipped in this search.

[0063] If two translations have exactly the same set of fields on the right side of the equal sign, then the translation names are essentially aliases for each other. If you request one, it has exactly the same effect as requesting the other. Ignoring one has exactly the same effect as ignoring the other. Although this should not cause run-time problems, having translations with exactly the same set of fields on the right side of the equal sign can be confusing and is not recommended.

[0064] The Messaging Control

[0065] The Messaging Control shields the module writer from the details of exactly how messages are passed. All that a user of the control needs to know is that when a new message arrives, the RcvMsg event will fire. At that time the programmer can get information out of the message, which is formatted according to a common message address format, using methods of the Messaging Control. A message can contain strings and other messages. Accordingly, a message may comprise a tree with strings being leaf nodes and sub-messages being branches. When a message is received, its root level is the current message. To get strings (data values) from the current message use GetString, providing a zero (0) as the message Id (identifying the current message) and a key string that identifies which string to retrieve. The Messaging Control will parse the message and retrieve the message data value associated with the key, regardless of the physical sequence of the data value in the message. base To get a sub-message use GetSubmsg, again providing a zero (0) as the message Id and a key string identifying the sub-message; this method will return a number identifying the sub-message. This number can then be used to identify the sub-message in calls to the various methods of this OCX (e.g., wherever IMsgID is used as a parameter). This ability to use extract message contents (sub-messages) using a key string, such that a sub-message can be extracted regardless of its physical sequence in the message, is the essence of the “common message format” of the present invention. As noted above, in one embodiment, the sub-messages are extractable from a tree format, although it is not mandatory that a tree format be used. Root messages and sub-messages are treated exactly the same (an ID for either type in most methods may be provided) except when it comes to deletion. A root message is one which is not a sub-message of any other message. When one deletes a root message using DeleteMsg all of its sub-messages are also deleted. To get rid of a sub-message, use RemoveKey.

[0066] In one embodiment, the naming of modules, keys and message translations are limited in the following ways:

[0067] Module names and module types may contain any character except \ (backslash), null, | (vertical bar), #, carriage return, or linefeed, but they may not be the single character * (asterisk). In addition, they may not begin with % (percent sign).

[0068] Keys may contain any character except null, | (vertical bar), \ (backslash), carriage return, and linefeed. In addition, only system defined keys may begin with a % sign (this is a convention).

[0069] Message translation names may contain any character except null, | (vertical bar), : (colon), #, carriage return, or linefeed, but they may not be the single character * (asterisk). In addition, only system defined translations may begin with a % sign.

[0070] In general, the characters to avoid are: \, null, |, #, %, carriage return, linefeed, and *.

[0071] When communicating with a specific module (as opposed to broadcasting), it is important that a module know that its messages were in fact received by intended recipient module. For instance, when the Executive sends a command to a module it is important that the Executive know that the message arrived; if it does not arrive, it is possible that the module is malfunctioning. To simplify this, the Messaging Control supports return receipts. A field (%Return) in the outgoing message is added that specifies the message type that should be used as a return receipt; when the message arrives, the Messaging Control of the receiving module will detect that this field is in the root of the message and send an immediate reply. The sending module will wait for this reply, timing out if it takes too long. Most of the time, return receipts are not needed since the system modules do not usually care where their messages go. When they are needed, the Messaging Control property “bConfirmDelivery” should be set to True. The next send command will automatically add the %Return field and wait for the reply. If the Messaging Control property bAutoResetConfirmationOnSend is True (the default) the “bConfirmDelivery” property will automatically get set to False again after the send command.

[0072] To facilitate the saving of messages to disk or other media, the GetMsgAsStringV and LoadMsgFromStringV methods are provided. They allow one to serialize a message into a variant safe array of bytes. This array can then be written to disk and later reloaded. This is only provided to allow for the saving of messages; one should not attempt to parse the information because the format may change. Modifying the string will have unpredictable results.

[0073] Strings contained in messages may have embedded nulls (to allow for binary data); all OLE strings are passed with a length prefix, allowing one to avoid using a null terminator. Care should be taken when using C++ because almost all C string operations assume a null terminated string; this includes the wrappers for OLE controls made by VC++. When including binary data in a message, it is recommended that the V method be used rather than AddString. AddStringV allows the data to be passed in as a variant safe array of bytes rather than a length-prefixed string. It will be appreciated that AddString and AddStringV comprise software means for building a message to be sent, such that the keys and their associated data values may be inserted into a message in any order. The sequence of the data values is dynamically constructed during execution of the software system. Accordingly another software module decoding a received message need only supply the key associated with the desired data value, and the data value may be retrieved (e.g., by the GetString method) regardless of the physical order the data value may be within the message.

[0074] System keys exist off of the root of messages and are named starting with a % (percent sign).

[0075] The %Return string field is added to a message when the sender wants a return receipt. It contains the message type to use when sending the return receipt. The ToName and ToType fields of the return receipt should be set to the FromName and FromType fields of the original message as well. These fields are automatically used by the OCX. If the bAutoConfirm property is set to False, it is up to the module to examine this field and generate return receipts as appropriate.

[0076] In an incoming message, this %Address sub-message has a key for each part of the address of the message: ToName, ToType, FromName, FromType and MsgType. When sending a message, in very rare cases one might want to override a translation; to do this, the %Address sub-message should be created, and a Override sub-message should be created under it. Within the Override sub-message, any fields to be overridden should be included (e.g., ToName, FromType, etc.).

[0077] When a message is sent, the sending Messaging Control will place a timestamp (%Time Stamp) at the root of the message. The timestamp is a 64 bit floating point number that is converted to a string. Days are represented by whole number increments starting with Dec. 30, 1899, midnight as time zero. The is the standard OLE date form; products such as Excel and Access will be able to convert this value into a human readable date and time.

[0078] Programming Examples

[0079] The following examples are be presented using Object Pascal (Delphi) syntax and Visual Basic syntax. It is assumed that a Messaging Control OCX object exists and is named “SILAS”.

[0080] Registering

[0081] Once the Messaging Control has been created, registering a module is done by calling RegisterModule with a name and type. The name should be one that is in the Keeper registry. Modules are often given a name on the command line when the Keeper launches them; the type is generally hard-coded into the module.

[0082] Delphi Example

[0083] {The first command line parameter is ParamStr(1) in Delphi then call RegisterModule}

[0084] SILAS.RegisterModule(ParamStr(1),‘Device’);

[0085] Visual Basic Example

[0086] ‘Get the entire command line with the Command$ function in VB.

[0087] CmdLn$=Command$

[0088] ‘Getting the first command line parameter is a little harder with ‘VB because no built-in parser for the command line exists. The ‘following example function can be used to parse the command line.

[0089] Function ParseCommand(tokenNum As Integer, cmd$) As String

[0090] Dim i, tokN As Integer

[0091] Dim c$, tok$

[0092] i=1: tokN=0: c$=″″: tok$ =″″

[0093] While i<=Len(cmd$)

[0094] c$=Mid(cmd$, i, 1)

[0095] While c$<>″″ And c$<>vbTab And i<=Len(cmd$)

[0096] tok$ =tok$ & c$

[0097] i=i+1

[0098] c$=Mid(cmd$, i, 1)

[0099] Wend

[0100] tokN=tokN+1

[0101] If tokN=tokenNum Then

[0102] ParseCommand=tok$

[0103] Exit Function

[0104] Else

[0105] tok$=″″

[0106] i=i+1

[0107] End If

[0108] Wend

[0109] ParseCommand=″″

[0110] End Function

[0111] ‘Call ParseCommand to get first parameter, then register with it SILAS.RegisterModule(ParseCommand(1, CmdLn$), “Device”).

[0112] Once the Messaging Control is registered, it will attempt to talk to the Keeper module to get the message translations for this module. Once it is successful or has given up, the Initialized event will fire. Nothing else involving SILAS should be done until this event fires. One should check both the return value of the RegisterModule call, and the ISuccess parameter of the Initialized event. If either is negative, then an error has occurred.

[0113] When the module is done working in SILAS it should call UnregisterModule to unregister. The module may continue to manipulate message after calling this function, but it should not send, request, ignore or receive any messages.

[0114] Requesting and Ignoring Messages

[0115] In order to get any messages from other modules, a module must first request them. This is done by a call to RequestMsg with the name of the message translation that corresponds to the messages you want:

[0116] Delphi Example

[0117] if SILAS.RequestMsg(‘Data’)>0 then

[0118] {The message translations in the registry must be messed up—fatal error}

[0119] Similarly, once you no longer want a particular message one needs to tell the Messaging Control OCX to ignore it:

[0120] if SILAS.IgnoreMsg(‘Data’)>0 then

[0121] {The message translations in the registry must be messed up—fatal error}

[0122] Visual Basic Example

[0123] If SILAS.RequestMsg(“Data”)>0 Then

[0124] ‘The message translations in the registry must be messed up—‘fatal error

[0125] Similarly, once you no longer want a particular message one needs to tell the Messaging Control OCX to ignore it:

[0126] If SILAS.IgnoreMsg(“Data”)>0 Then

[0127] ‘The message translations in the registry must be messed up—‘fatal error

[0128] When the Messaging Control OCX receives a message, it searches the list of translations for one that matches; it starts from the bottom of the list and goes up. The first requested translation that matches is the only one used when receiving a message; translations which are not requested or which are ignored are always skipped in this search.

[0129] Receiving a Message

[0130] Once a module has requested a message, the RcvMsg event may fire at any time to inform the module that a message has arrived:

[0131] Delphi Example

[0132] procedure TfrmMain.RcvMsg(Sender: TObject;

[0133] const sMsgName: string);

[0134] begin

[0135] {Find out what kind of message it is}

[0136] if sMsgName=‘Existence Query’ then

[0137] begin

[0138] . . . {do something with it}

[0139] end

[0140] else if sMsgName=‘Data’ then

[0141] . . .

[0142] end;

[0143] Visual Basic Example

[0144] Private Sub SILAS_RcvMsg(ByVal sMsgName As String)

[0145] ‘Find out what kind of message it is

[0146] If sMsgName=“Existence Query” Then

[0147] . . . ‘do something with it

[0148] Elself sMsgName=“Data” Then

[0149] . . .

[0150] End If

[0151] End Sub

[0152] Getting Strings from the Current Message

[0153] All data in a message is retrieved by providing a key that identifies it:

[0154] Delphi Example

[0155] {Get the command name from the current message (identified by 0)}

[0156] sCommandName:=SILAS.GetString(0,‘Command Name’);

[0157] if sCommandName=‘Read’ then

[0158] {Perform the read}

[0159] Visual Basic Example

[0160] ‘Get the command name from the current message (identified by 0)

[0161] sCommandName=SILAS.GetString(0, “Command Name”)

[0162] If sCommandName=“Read” Then

[0163] ‘Perform the read

[0164] If the key given is not in the message, an empty string is passed back. If you must differentiate between a missing key and empty strings, use the StringExists method.

[0165] Saving Messages

[0166] It is often useful to be able to save a message for later use (usually to reply to it):

[0167] In Delphi: ISavedMessage:=SILAS.SaveCurrentMsg( );

[0168] In Visual Basic: ISavedMessage=SILAS.SaveCurrentMsg

[0169] From that point on, one may refer to that message using the number supplied by the method (ISavedMessage). One may do anything with the saved message that can be done with the current message; simply use the number provided instead of 0, for example:

[0170] In Delphi:

[0171] sCommandName:=SILAS.GetString(ISavedMessage,‘Command Name’);

[0172] In Visual Basic:

[0173] sCommandName=SILAS.GetString(ISavedMessage, “Command Name”)

[0174] Working with Sub-messages

[0175] Messages can contain other messages (sub-messages). This is similar to a tree with branches (sub-messages) and leaves (strings); GetSubmsg is like looking at a branch:

[0176] In Delphi: ISubmessage:=SILAS.GetSubmsg(0,‘Parameters’);

[0177] In Visual Basic: ISubmessage =SILAS.GetSubmsg(0, “Parameters”)

[0178] Once a sub-message is gotten, one may simply treat it like any other message, for example:

[0179] In Delphi: sCommand:=SILAS.GetString(ISubmessage,‘Command Name’);

[0180] In Visual Basic: sCommand =SILAS.GetString(ISubmessage, “Command Name”)

[0181] If there are multiple levels of sub-messages, one needs to get each in turn; for instance, consider a message structured like so:

[0182] If one wanted to get the Wavelength parameter for Read Two, one would do this:

[0183] Delphi Example

[0184] IparamMsg:=SILAS.GetSubmsg(0,‘Parameters’);

[0185] IReadTwo:=SILAS.GetSubmsg(IParamMsg,‘Read Two’);

[0186] sReadTwoWavelength:=SILAS.GetString(IReadTwo,‘Wavelength’);

[0187] Visual Basic Example

[0188] IparamMsg=SILAS.GetSubmsg(0, “Parameters”)

[0189] IReadTwo =SILAS.GetSubmsg(IParamMsg, “Read Two”)

[0190] sReadTwoWavelength=SILAS.GetString(IReadTwo, “Wavelength”)

[0191] Once a root message is deleted, its sub-messages will also be deleted, and the ID's used to reference them will be invalid. If one needs a sub-message later, but not its root message, create a blank message (CreateMsg) and copy the sub-message (CopyAll). At that point, the sub-message is its own root message and will stay around until explicitly deleted. To save the ‘Parameters’ sub-message of the above example, do the following:

[0192] In Delphi:

[0193] ISavedSubMsg:=SILAS.CreateMsg( );

[0194] SILAS.CopyAll(SILAS.GetSubmsg(0,‘Parameters’), ISavedSubMsg);

[0195] In Visual Basic:

[0196] ISavedSubMsg=SILAS.CreateMsg

[0197] SILAS.CopyAll SILAS.GetSubmsg(0, “Parameters”), ISavedSubMsg

[0198] Building and Sending Messages

[0199] The Messaging Control OCX allows one to build up a message field by field and then send it. Here's how the message used above was created (error checking has been omitted):

[0200] Delphi Example

[0201] {create a new message}

[0202] IOutMsg:=SILAS.CreateMsg( );

[0203] {add the Command key with the string “Read” as the command}

[0204] SILAS.AddString(IOutMsg, ‘Command’,‘Read’);

[0205] {Create the Parameters sub-message}

[0206] IParamsMsg:=SILAS.AddSubmsg(IOutMsg, ‘Parameters’);

[0207] {create Read One sub-message}

[0208] IReadOne:=SILAS.AddSubmsg(IParamsMsg,‘Read One’);

[0209] {Add data to Read One}

[0210] SILAS.AddString(IReadOne,‘Wavelength’,‘450’);

[0211] SILAS.AddString(IReadOne,‘Dispense’,‘False’);

[0212] {create Read Two sub-message}

[0213] IReadTwo:=SILAS.AddSubmsg(IParamsMsg,‘Read Two’,‘True’);

[0214] {Add data to Read Two}

[0215] SILAS.AddString(IReadTwo,‘Wavelength’,‘950’);

[0216] SILAS.AddString(IReadTwo,‘Dispense?’,‘True’);

[0217] Visual Basic Example

[0218] ‘create a new message

[0219] IOutMsg =SILAS.CreateMsg

[0220] ‘add the Command key with the string “Read” as the command

[0221] SILAS.AddString IOutMsg, “Command”, “Read”

[0222] ‘Create the Parameters sub-message

[0223] IParamsMsg =SILAS.AddSubmsg(IOutMsg, “Parameters”)

[0224] ‘create Read One sub-message

[0225] IReadOne =SILAS.AddSubmsg(IParamsMsg, “Read One”)

[0226] ‘Add data to Read One}

[0227] SILAS.AddString IReadOne, “Wavelength”, “450”

[0228] SILAS.AddString IReadOne,”Dispense”, “False”

[0229] ‘create Read Two sub-message

[0230] IReadTwo =SILAS.AddSubmsg(IParamsMsg, “Read Two”, “True”)

[0231] ‘Add data to Read Two

[0232] SILAS.AddString IReadTwo, “Wavelength”, “950”

[0233] SILAS.AddString IReadTwo,“Dispense?”, “True”

[0234] After the message is built, sending it is just a matter of specifying where it needs to go (note that ‘Command’ in this example refers to a translation name, not a key or sub-message):

[0235] In Delphi: SILAS.SendMsgTo(IOutMsg,‘Command’,‘SMax’);

[0236] In Visual Basic: SILAS.SendMsgTo IOutMsg, “Command”, “Smax”

[0237] There are several different ways to specify where a message should go. The above method (SendMsgTo) addresses the given message directly to the module specified. This method is only used when it is unreasonable to have a translation for each module that the message will be sent to (e.g., an executive module has a single command translation and uses the SendMsgTo method to direct the messages to a particular module). If there are only a few different modules that need to be communicated with, the regular send method (SendMsg) is preferable because the translations can be changed without needing changes in the module. The final method of sending a message is in reply to another message (SendReply); this is the most often used method for device modules. All messages that the module produces in response to a command would be sent using this method (including Data, Events, Touches, Status, etc.). Generally, the only time that a device module will use SendMsg or SendMsgTo is if it is controlling a subordinate module or something happens spontaneously.

[0238] When one is done with messages that have been created or saved, one should delete them (using DeleteMsg). Messages created will remain until explicitly deleted. One does not need to delete sub-messages, because they will be deleted when their parent message is deleted. One also does not need to delete the current message, because it is automatically deleted at the end of the RcvMsg event; if you will need it later, save it (using SaveCurrentMsg).

[0239] Sending a reply message requires that one reply during the RcvMsg event (specifying the current message with a 0) or save the message and use that saved message number at some later time:

[0240] Delphi Example

[0241] procedure TfrmMain.SilasRcvMsg(Sender: TObject;

[0242] const sMsgName: string);

[0243] var

[0244] IOutMsg, ICommand: integer;

[0245] begin

[0246] {Find out what kind of message it is, i.e., which translation it first matches from the Keeper (remember bottom-up matching)}

[0247] if sMsgName =‘Existence Query’ then

[0248] begin

[0249] {build a reply message that will be automagicly deleted}

[0250] IOutMsg:=SILAS.CreateMsgToSend( );

[0251] {Reply using 0 to specify the current message}

[0252] SILAS.SendReply(IOutMsg, ‘Existence Query Reply’,0)

[0253] end

[0254] else if sMsgName=‘Command’ then

[0255] {it's a command—save it so we can reply when we're done}

[0256] ICommand:=SILAS.SaveCurrentMsg( );

[0257] . . . {finish looking for names we care about}

[0258] . . . {finish doing whatever else this module may need to do}

[0259] {After finishing the command, send a reply}

[0260] SILAS.SendReply(IOutMsg, ‘Command Reply’, ICommand);

[0261] {delete the command message}

[0262] SILAS.DeleteMsg(ICommand);

[0263] end;

[0264] Visual Basic Example

[0265] Private Sub SILAS_RcvMsg(ByVal sMsgName As String)

[0266] Dim IOutMsg As Integer, ICommand As Integer

[0267] ‘Find out what kind of message it is, i.e., which translation it

[0268] ‘first matches from the Keeper (remember bottom-up matching)

[0269] If sMsgName=“Existence Query” Then

[0270] ‘build a reply message that will be automagicly deleted

[0271] IOutMsg=SILAS.CreateMsgToSend

[0272] ‘Reply using 0 to specify the current message

[0273] SILAS.SendReply IOutMsg, “Existence Query Reply”, 0

[0274] Elself sMsgName=“Command” Then

[0275] ‘it's a command—save it so we can reply when we're done

[0276] ICommand=SILAS.SaveCurrentMsg

[0277] . . . ‘finish looking for names we care about

[0278] End If

[0279] . . . ‘finish doing whatever else this module may need to do

[0280] ‘After finishing the command, send a reply

[0281] SILAS.SendReply IOutMsg, “Command Reply”, ICommand

[0282] ‘delete the command message

[0283] SILAS.DeleteMsg ICommand

[0284] End Sub

[0285] Re-using Messages

[0286] Sometimes it is useful to take parts of a message you have received and put them into a message that you are sending (e.g., send the whole command message to the event logger so it can handle it however it wants). It is also useful to re-use a message that will be sent repeatedly with small modifications (e.g., a status message). For this purpose there are several different ways to copy from one message to another:

[0287] Delphi Example

[0288] {Copy the whole current message to the outgoing message}

[0289] SILAS.CopyAll(0, IOutMsg);

[0290] {Copy a sub-message to the root of the outgoing message}

[0291] SILAS.CopyAll(ISubMsg, IOutMsg);

[0292] {Copy a single key from one message to another}

[0293] SILAS.CopyTo(ISavedMsg, ‘Command’, IOutSubmsg, ‘Command’);

[0294] Visual Basic Example

[0295] ‘Copy the whole current message to the outgoing message

[0296] SILAS.CopyAll 0, IOutMsg

[0297] ‘Copy a sub-message to the root of the outgoing message

[0298] SILAS.CopyAll ISubMsg, IOutMsg

[0299] ‘Copy a single key from one message to another}

[0300] SILAS.CopyTo ISavedMsg, “Command”, IOutSubmsg, “Command”

[0301] Note that if one copies a message onto another message, the two messages are merged; the string values of the source message will overwrite those of the destination message for all keys which are the same between the two messages. Keys which are unique to either message are not modified. FIG. 2 illustrates the merging that occurs when CopyAll is applied to two messages.

[0302] Enumeration

[0303] Sometimes one does not know what keys a message contains. In order to find out, you need to use the enumeration functions GetFirstStringPosition, GetNextStringKey, GetFirstSubmsgPosition, and GetNextSubmsgKey.

[0304] Delphi Example

[0305] IPos:=SILAS.GetFirstStringPosition(0);

[0306] while IPos < >0 do

[0307] begin

[0308] sKey:=SILAS.GetNextStringKey(0, IPos); // IPos is updated here

[0309] . . . // do something with the key

[0310] end;

[0311] IPos:=SILAS.GetFirstSubmsgPosition(0);

[0312] while IPos < >0 do

[0313] begin

[0314] sKey:=SILAS.GetNextSubmsgKey(0, IPos); // IPos is updated here

[0315] . . . // do something with the key

[0316] end;

[0317] If you wanted to get all of the strings from a message, you could do something like this:

[0318] IPos:=SILAS.GetFirstStringPosition(0);

[0319] while IPos < >0 do

[0320] begin

[0321] sKey:=SILAS.GetNextStringKey(0, IPos);

[0322] sAllStrings:=sAllStrings+SILAS.GetString(0, sKey);

[0323] end;

[0324] ISubMsgPos:=SILAS.GetFirstSubmsgPosition(0)

[0325] while ISubMsgPos < >0 do

[0326] begin

[0327] sSubMsgKey:=SILAS.GetNextSubmsgKey(0, ISubMsgPos);

[0328] ISubMsgKey:=SILAS.GetSubmsg(0, sSubMsgKey);

[0329] IPos:=SILAS.GetFirstStringPosition(ISubMsgKey);

[0330] while IPos < >0 do

[0331] begin

[0332] sKey:=SILAS.GetNextStringKey(ISubMsgKey, IPos);

[0333] sAllStrings:=sAlIStrings+SILAS.GetString(ISubMsgKey, sKey);

[0334] end;

[0335] end;

[0336] Visual Basic Example

[0337] IPos=SILAS.GetFirstStringPosition(0)

[0338] While IPos < >0

[0339] sKey:=SILAS.GetNextStringKey(0, IPos) ‘IPos is updated here

[0340] . . . ‘do something with the key

[0341] Wend

[0342] IPos=SILAS.GetFirstSubmsgPosition(0)

[0343] While IPos < >0

[0344] sKey=SILAS.GetNextSubmsgKey(0, IPos) ‘IPos is updated here

[0345] . . . ‘do something with the key

[0346] Wend

[0347] If you wanted to get all of the strings from a message, you could do something like this:

[0348] IPos=SILAS.GetFirstStringPosition(0)

[0349] While IPos < >0

[0350] sKey=SILAS.GetNextStringKey(0, IPos)

[0351] sAllStrings=sAllStrings & SILAS.GetString(0, sKey)

[0352] Wend

[0353] ISubMsgPos=SILAS.GetFirstSubmsgPosition(0)

[0354] While ISubMsgPos < >0

[0355] sSubMsgKey=SILAS.GetNextSubmsgKey(0, ISubMsgPos)

[0356] ISubMsgKey=SILAS.GetSubmsg(0, sSubMsgKey)

[0357] IPos=SILAS.GetFirstStringPosition(ISubMsgKey)

[0358] While IPos < >0

[0359] sKey=SILAS.GetNextStringKey(ISubMsgKey, IPos)

[0360] sAllStrings=sAliStrings & SILAS.GetString(ISubMsgKey, sKey)

[0361] Wend

[0362] Wend

[0363] Confirming Delivery

[0364] Sometimes, when one sends a message it is important to be sure that it actually arrived; if the module you are sending the message to has failed for some reason, one does not want the module to crash. In one embodiment, the Messaging Control OCX automatically supports confirmation of deliveries. Since most messages do not require confirmed delivery, in one embodiment, the programmer must set a property (bConfirmDelivery) immediately before doing the send; the Messaging Control OCX will automatically reset it to False after you send the message:

[0365] Delphi Example

[0366] {Confirm delivery}

[0367] SILAS.bConfirmDelivery:=True;

[0368] {Send message—check return value; if nonzero, we timed out waiting for the return receipt (or some other error occurred)}

[0369] if SILAS.SendMsg(IMsgId,‘SMax-Command’) < >0 then

[0370] {The SMax module must be dead!}

[0371] else

[0372] {bConfirmDelivery has been automatically reset to false—we will not wait for a return receipt on this send}

[0373] SILAS.SendMsg(‘Status’);

[0374] Visual Basic Example

[0375] ‘Confirm delivery

[0376] SILAS.bConfirmDelivery=True

[0377] ‘Send message—check return value; if nonzero, we timed out ‘waiting for the return receipt (or some other error occurred)

[0378] If SILAS.SendMsg(lMsgid, “SMax-Command”) < >0 Then

[0379] ‘The SMax module must be dead!

[0380] Else

[0381] ‘bConfirmDelivery has been automatically reset to false—we

[0382] ‘will not wait for a return receipt on this send

[0383] SILAS.SendMsg “Status”

[0384] End If

[0385] In one embodiment, calling SendMsg with bConfirmDelivery set to True can result in reentrancy if you receive a message or other event while the Messaging Control OCX is waiting for the delivery confirmation.

[0386] Modules that listen to messages not intended for them need to set the bAutoConfirm property to False. This must be done so that the module does not confirm delivery of a message not meant for it. Instead, the module should call SendDeliveryConfirmation for messages meant for it:

[0387] 7.22.

[0388] if sMsgName=‘Command To Me’ then

[0389] begin

[0390] SILAS.SendDeliveryConfirmation(0);

[0391] . . .

[0392] end

[0393] else if sMsgName=‘Commands for someone else’ then

[0394] // do not send the delivery confirmation here

[0395] begin

[0396] . . .

[0397] end

[0398] else if sMsgName=‘Existence Query’ then

[0399] begin

[0400] SILAS.SendDeliveryConfirmation(0);

[0401] SILAS.SendReply(SILAS.CreateMsgToSend,

[0402] ‘Existence Query Reply’,0);

[0403] end;

[0404] Visual Basic Example

[0405] If sMsgName=“Command To Me” Then

[0406] SILAS.SendDeliveryConfirmation 0

[0407] . . .

[0408] Elself sMsgName=“Commands for someone else” Then

[0409] ‘do not send the delivery confirmation here

[0410] . . .

[0411] Elself sMsgName=“Existence Query” Then

[0412] SILAS.SendDeliveryConfirmation 0

[0413] SILAS.SendReply(SILAS.CreateMsgToSend, _“Existence Query Reply”, 0)

[0414] End If

[0415] Errors and Exceptions

[0416] There are three levels of exceptions that the Messaging Control OCX may raise: Common, Rare and Fatal. There are three corresponding properties on the Messaging Control OCX: bRaiseExceptions, bRaiseRareExceptions, and bRaiseFatalExceptions. When bRaiseExceptions is set to True, Common errors will result in an exception being raised. If it is not set, then the error will be indicated by the return value of the method being called. The other two properties affect their associated set of errors in a similar manner. The exceptions raised will include a descriptive message indicating the nature of the error. When exceptions are turned off, the error text can be retrieved by calling GetErrorText with the error ID number.

[0417] Delphi Example

[0418] try

[0419] SILAS.SendMsg(IMsg, ‘Non-existent Translation’);

[0420] except

[0421] On xE : Exception do

[0422] MessageDlg(‘Error encountered:’+xE.Message,mtError,[mbOK],0);

[0423] end; {end of subroutine}

[0424] Visual Basic Example

[0425] On Error Goto ErrorHandler

[0426] SILAS.SendMsg IMsg, “Non-existent Translation”

[0427] Exit Sub

[0428] ErrorHandler:

[0429] SilasMsgBox.SilasMsgBox “Error encountered:” & Str(Err.Number)_& “ generated by ” & Err.Source & vbCrLf & Err.Description,_vbOkOnly, “Error”

[0430] End Sub

[0431] Translations

[0432] Normally the Messaging Control OCX will retrieve all of its translations from the Keeper when it registers. However, if the bRetrieveTranslations property is set to False prior to registration, the Messaging Control OCX will not retrieve its translations from the Keeper. One must still wait for the Initialized event even if you are not retrieving translations. The method AddTranslation is provided for adding a single translation. Also, the method AddTranslations is provided for adding many at a time.

[0433] Delphi Example

[0434] SILAS.bRetrieveTranslations:=False;

[0435] SILAS. RegisterModule(‘AllWatcher’, ‘Watcher’);

[0436] . . .

[0437] procedure OnSilasInitialized(Sender: Tobject; ISuccess: integer)

[0438] begin

[0439] // add the command translation

[0440] SILAS.AddTranslation(‘Command’, ‘*’, ‘*’, ‘*’, ‘*’, ‘Command’);

[0441] // add the status and data translations—use a string

[0442] // formatted as in the %Messaging branches of the keeper

[0443] SILAS.AddTranslations(‘Status=*:*:*:*:Status’+#13#10+‘Data=*:*:*:*:Data’)

[0444] . . .

[0445] end;

[0446] Visual Basic Example

[0447] SILAS.bRetrieveTranslations=False

[0448] SILAS.RegisterModule “AllWatcher”, “Watcher”

[0449] . . .

[0450] Private Sub SILAS_lnitialized(ByVal ISuccess As Long)

[0451] ‘add the command translation

[0452] SILAS.AddTranslation “Command”, “*”, “*”, “*”, “*”, “Command”

[0453] ‘add the status and data translations—use a string

[0454] ‘formatted as in the %Messaging branches of the keeper

[0455] SILAS.AddTranslations “Status=*:*:*:*:Status” & vbCrLf & _“Data=*:*:*:*:Data”

[0456] . . .

[0457] End Sub

[0458] Also, the module can verify that it has a translation by calling TranslationExists. For instance, a device module will have code similar to the following in its Initialized event:

[0459] Delphi Example

[0460] if SILAS.TranslationExists(‘Command’)=0 then

[0461] {raise custom exception (assumed to be already defined)}

[0462] Raise EMissingTranslation.Create(‘Translation Command is missing.’);

[0463] Visual Basic Example

[0464] If SILAS.TranslationExists(“Command”)=0 Then

[0465] ‘raise raw exception (could define an exception creator)

[0466] Err.Raise 1001, App.Title, “Translation Command is missing.”

[0467] Addressing Information

[0468] The address attached to a particular message is held in a sub-message off of the root called “%Address”. Generally, this information is not needed; the OCX will provide one with the name of the message in the RcvMsg event. The set of names of messages that a module will receive will not change, but the individual elements of the address may (depending on how a system integrator decides to connect modules together).

[0469] The address components are found under the following keys under the %Address sub-message (no spaces between words): ToName, ToType, FromName, FromType, and MsgType

[0470] Streaming Messages (e.g. file I/O)

[0471] Messages can be converted into a stream of bytes so that they can be saved to disk or sent over communications media other than the SILAS router.

[0472] Delphi Example

[0473] To write a message to a stream, use code similar to the following:

[0474] procedure WriteMsg(Stream: TStream; nMsg: integer);

[0475] var

[0476] vCodeMsg: variant;

[0477] nCodeMsgSize: integer;

[0478] pVarBuffer: pointer;

[0479] begin

[0480] // get the message as a variant

[0481] vCodeMsg:=SILAS.GetMsgAsStringV(nMsg);

[0482] // get the size and put it into the stream first

[0483] nCodeMsgSize:=VarArrayHighBound(vCodeMsg, 1)−VarArrayLowBound(vCodeMsg, 1)+1;

[0484] pVarBuffer:=VarArrayLock(vCodeMsg);

[0485] WriteInteger(Stream, nCodeMsgSize);

[0486] // write out the message and clean up

[0487] Stream.WriteBuffer(pVarBuffer{circumflex over ( )}, nCodeMsgSize);

[0488] VarArrayUnlock(vCodeMsg);

[0489] VarClear(vCodeMsg);

[0490] end;

[0491] To read a message in, use code similar to the following:

[0492] function ReadMsg(Stream: TStream): integer;

[0493] var

[0494] nSize: integer;

[0495] vMSg: variant;

[0496] pVarBuffer: pointer;

[0497] begin

[0498] // get the message size

[0499] ReadInteger(Stream, nsize);

[0500] if nSize < >0 then

[0501] begin

[0502] // make an array of the appropriate size

[0503] vMsg:=VarArrayCreate([0, nSize−1],varByte);

[0504] pVarBuffer:=VarArrayLock(vMsg);

[0505] // read the message into the buffer

[0506] Stream.ReadBuffer(pVarBuffer{circumflex over ( )}, nsize);

[0507] VarArrayUnlock(vMsg);

[0508] // pass the buffer to SILAS

[0509] Result:=SILAS.LoadMsgFromStringV(vMsg);

[0510] VarClear(vMsg);

[0511] end

[0512] else

[0513] Result:=−1;

[0514] end;

[0515] Visual Basic Example

[0516] Since Visual Basic does not have streams, file input and output is used for this example. Substantially different code may be needed for other applications.

[0517] To write a message to a file, code similar to the following may be used:

[0518] Public Sub WriteMsg(File As String, nMsg As Long)

[0519] Dim pFile As Integer, Location As Integer

[0520] Dim vCodeMsg( ) As Byte

[0521] ‘Get a free file pointer and open the file

[0522] pFile=FreeFile: Open File For Binary As pFile

[0523] ‘Read message as a string (byte array)

[0524] vCodeMsg=SILAS.GetMsgAsStringV(nMsg)

[0525] ‘Loop through the entire array, putting each byte into the file

[0526] For Location=LBound(vCodeMsg) To UBound(vCodeMsg)

[0527] Put pFile, vCodeMsg(Location)

[0528] Next Location

[0529] Close pFile ‘Close the file

[0530] End Sub

[0531] To read a message in from a file, use code similar to the following:

[0532] Public Function ReadMsg(File As String) As Long

[0533] Dim pFile As Integer, Location As Integer, Char As Byte

[0534] Dim MsgByteArray( ) As Byte

[0535] ‘Get a free file pointer and open the file

[0536] pFile=FreeFile: Open File For Binary As pFile

[0537] ‘Initialize variables, assuming 0-based array indexing

[0538] Location=0: Char=255

[0539] ‘While we're not at the end of the file . . .

[0540] While Location <LOF(pFile)

[0541] ‘Get the next byte (auto-updates file position)

[0542] Get pFile, Char

[0543] ‘Make room for the new byte in the array

[0544] ReDim Preserve MsgByteArray(Location +1)

[0545] ‘Put the byte into the array

[0546] MsgByteArray(Location)=Char

[0547] ‘Update the index to match position in the file

[0548] Location=Loc(pFile)

[0549] Wend

[0550] Close pFile ‘Close the file

[0551] ‘load message into SILAS and return the message number

[0552] ReadMsg=SILAS.LoadMsgFromStringV(MsgByteArray( ))

[0553] End Function

[0554] Explanation of Prototypes

[0555] Events and methods presented below are pseudocode prototypes. The format is:

[0556] <return-type><name>(<parameter-type><parameter>, . . . )

[0557] The types and their language-dependent forms are summarized in the table below:

[0558] The passing style of parameters is not specified in the pseudocode; the passing style will be obvious to one skilled in the art when using the methods or events in a particular programming environment (i.e. VB or Delphi).

[0559] Events

[0560] RcvMsg

[0561] RcvMsg(String sMsgName)

[0562] Purpose

[0563] This event occurs each time a SILAS message arrives. It is during the processing of this event that there is a “current message.” Methods will operate on this message if the message id parameter is set to 0.

[0564] Parameters

[0565] Initialized

[0566] Initialized(long ISuccess)

[0567] Purpose

[0568] After a module calls RegisterModule and the OCX finishes initializing, this event will fire.

[0569] Note: No other SILAS interaction should take place until this event has fired.

[0570] Parameters

[0571] Properties

[0572] The properties marked as Run-Time Only will reset to their default values when SILAS is initialized; setting these properties as design-time will have no effect. bAutoConfirm

[0573] When this property is set, the OCX will automatically send a return receipt when a message arrives with a non-empty %Return field. If this is set to False, it becomes the module's responsibility to send return receipts. It is useful to have this property False if your module will be listening in on conversations between other modules; if this property were True the sending module might end up getting a return receipt from the listening module rather than the intended module. Defaults to True.

[0574] bAutoResetConfirmationOnSend—Run-Time Only

[0575] When this property is True, the OCX will automatically set the bConfirmDelivery property to False after a message is sent. Defaults to True.

[0576] bConfirmDelivery—Run-Time Only

[0577] When this property is True the OCX will automatically request and wait for a return receipt when you send a message. Defaults to False.

[0578] iConfirmTimeout

[0579] This property determines how long the OCX will wait for a return receipt in seconds. Defaults to 15.

[0580] bRetrieveTranslations—Run-Time Only

[0581] When True, the OCX automatically retrieves its translations from the Keeper. Defaults to True.

[0582] bRaiseExceptions—Run-Time Only

[0583] When True, the OCX will raise OLE dispatch exceptions when a common error occurs. See Error Codes for the list of errors. Defaults to False.

[0584] bRaiseFatalExceptions—Run-Time Only

[0585] When True, the OCX will raise OLE dispatch exceptions when a fatal error occurs. See Error Codes for the list of errors. Defaults to True.

[0586] bRaiseRareExceptions—Run-Time Only

[0587] When True, the OCX will raise OLE dispatch exceptions when a rare error occurs. See Error Codes below for the list of errors. Defaults to True.

[0588] Methods

[0589] AddString

[0590] long AddString(long IMsgID, string sKey, string sData)

[0591] Purpose

[0592] This method adds a string to the given message under the given key.

[0593] Parameters

[0594] Return Value

[0595] Nonzero on failure, 0 on success.

[0596] AddStringV

[0597] long AddStringV(long IMsgID, string sKey, variant vString)

[0598] Purpose

[0599] This method adds a string to the given message under the given key. This method is provided to allow the client to transmit binary data. This is done by packing the data into a variant array of bytes (vString).

[0600] Parameters

[0601] Return Value

[0602] Nonzero on failure, 0 on success.

[0603] AddSubmsg

[0604] long AddSubmsg(long IMsgID, string sKey)

[0605] Purpose

[0606] This method creates a sub-message under the given key in the given message. If a sub-message already exists with the given key, this method will return the ID of the pre-existing sub-message.

[0607] Parameters

[0608] Return Value

[0609] A number>0 to be used to refer to the message on success; Negative on failure.

[0610] AddTranslation

[0611] long AddTranslation(string sTranslationName,

[0612] string sToName, string sToType,

[0613] string sFromName, string sFromType,

[0614] string sMsgType);

[0615] Purpose

[0616] This method is not for normal use; translations should all be held in the Keeper and automatically retrieved by the OCX. This method adds a new message translation to the list of translation held by the OCX; these translations work exactly like those held in the registry (see The Messaging Control)

[0617] Parameters

[0618] Return Value

[0619] ‘Nonzero on failure, 0 on success.

[0620] AddTranslations

[0621] long AddTranslations(string sTranslations)

[0622] Purpose

[0623] This method is not for normal use; translations should all be held in the Keeper and automatically retrieved by the OCX. This method adds new message translations to the list of translation held by the OCX; these translations work exactly like those held in the registry

[0624] Parameters

[0625] Return Value

[0626] Nonzero on failure, 0 on success.

[0627] AddUniqueString

[0628] long AddUniqueString(long IMsgID, string sKey, string sData)

[0629] Purpose

[0630] This method adds a string to the given message under the given key. The OCX will assume that the string is not already present. This method is slightly faster than AddString when there are a small number of keys (<10) in the message. If the string is not unique, then there is no gaurantee which value will be returned when the key is later queried.

[0631] Parameters

[0632] Return Value

[0633] Nonzero on failure, 0 on success.

[0634] AddUniqueSubmsg

[0635] long AddUniqueSubmsg(long IMsgID, string sKey)

[0636] Purpose

[0637] This method creates a sub-message under the given key in the given message. The OCX will assume that the submsg is not already present. This method is slightly faster than AddSubmsg when there are a small number of keys (<10) in the message. If the submsg is not unique, then there is no gaurantee which sub-message will be returned when the key is later queried.

[0638] Parameters

[0639] Return Value

[0640] A number >0 to be used to refer to the message on success; Negative on failure.

[0641] CreateMsg

[0642] long CreateMsg( )

[0643] Purpose

[0644] This method creates a new, blank message.

[0645] Parameters

[0646] None.

[0647] Return Value

[0648] A number >0 to be used to refer to the message on success; Negative on failure.

[0649] CreateMsgToSend

[0650] long CreateMsgToSend( )

[0651] Purpose

[0652] This method creates a new, blank message. This message will be automatically deleted by the OCX once it is sent.

[0653] Parameters

[0654] None.

[0655] Return Value

[0656] A number >0 to be used to refer to the message on success; Negative on failure.

[0657] CopyAll

[0658] long CopyAll(long IFromID, long IToID)

[0659] Purpose

[0660] This method copies the full contents (including sub-messages) of one message to another.

[0661] Parameters

[0662] Return Value

[0663] Nonzero on failure, 0 on success.

[0664] CopyKey

[0665] long CopyKey(long IFromID, string sKey, long ITOID, string sNewKey)

[0666] Purpose

[0667] This method copies the given key of one message to another. If there is a string and sub-message key with the same name, both will be copied.

[0668] Parameters

[0669] Return Value

[0670] Nonzero on failure, 0 on success.

[0671] CopyMsgToKey

[0672] long CopyMsgToKey(long IMsgID, long IToID, string sNewKey)

[0673] Purpose

[0674] This method copies the given message to a key under another message.

[0675] Parameters

[0676] Return Value

[0677] Nonzero on failure, 0 on success.

[0678] DeleteMsg

[0679] long DeleteMsg(long IMsgID)

[0680] Purpose

[0681] This method deletes the given message (and all of its sub-messages). If the message ID refers to a sub-message this method will return an error. Only root messages may be deleted with this method. If you wish to delete a sub-message, use RemoveKey.

[0682] Properties

[0683] Return Value

[0684] Nonzero on failure, 0 on success.

[0685] GetErrorText

[0686] string GetErrorText(long IErrorID)

[0687] Purpose

[0688] This method retrieves the error text associated with a given error ID.

[0689] GetFirstStringPosition

[0690] long GetFirstStringPosition(long IMsgID)

[0691] Purpose

[0692] This method retrieves an integer that identifies the first string key in the given message. This number can then be passed to GetNextStringKey to retrieve the key.

[0693] Parameters

[0694] Return Value

[0695] 0 on failure or if there are no strings. Nonzero on success.

[0696] GetFirstSubmsgPosition

[0697] long GetFirstSubmsgPosition(long IMsgID)

[0698] Purpose

[0699] This method retrieves an integer that identifies the first submsg key in the given message. This number can then be passed to GetNextSubmsgKey to retrieve the key.

[0700] Parameters

[0701] Return Value

[0702] 0 on failure or if there are no submsgs. Nonzero on success.

[0703] GetNextStringKey

[0704] string GetNextStringKey(long IMsgID, long* IpEnumPosition)

[0705] Purpose

[0706] This method retrieves the next string key in the specified message and sets the given position integer to refer to the next key. The position integer will be set to 0 when there are no more keys.

[0707] Parameters

[0708] Return Value

[0709] The key on success; an empty string on error.

[0710] GetNextSubmsgKey

[0711] string GetNextSubmsgKey(long IMsgID, long* IpEnumPosition)

[0712] Purpose

[0713] This method retrieves the next submsg key in the specified message and sets the given position integer to refer to the next key. If there are no more keys, the position integer will be set to 0.

[0714] Parameters

[0715] Return Value

[0716] The key on success; an empty string on error.

[0717] GetMsgAsStringV

[0718] variant GetMsgAsStringV(Iong IMsgID)

[0719] Purpose

[0720] This method returns a full message in a variant array of bytes. This method is meant only to be used so that the user may save messages to disk or other media; you should not examine or modify the contents of the array.

[0721] Parameters

[0722] Return Value

[0723] The data on success; an empty variant on failure.

[0724] GetParentMsg

[0725] long GetParentMsg (long IMsgID, long pIParentID)

[0726] Purpose

[0727] This method returns the ID of the parent of the given message in the parameter pIParentID.

[0728] Parameters

[0729] Return Value

[0730] The 0 on success. Non-zero on failure (e.g. IMsgID is a root message).

[0731] GetString

[0732] string GetString(long IMsgID, string sKey)

[0733] Purpose

[0734] This method retrieves a string from a message.

[0735] Parameters

[0736] Return Value

[0737] The data on success; an empty string on failure.

[0738] GetStringV

[0739] variant GetStringV(long IMsgID, string sKey)

[0740] Purpose

[0741] This method retrieves a string from a message in the form of a variant array of bytes.

[0742] Parameters

[0743] Return Value

[0744] The data on success; an empty variant on failure.

[0745] GetSubmsg

[0746] long GetSubmsg(long IMsgID, string sKey)

[0747] Purpose

[0748] This method gets the ID of a sub-message under the given key in the given message. If the root message for this sub-message is deleted, the ID becomes invalid.

[0749] Parameters

[0750] Return Value

[0751] A number >0 to be used to refer to the message on success; Negative on failure . . .

[0752] IgnoreMsg

[0753] long IgnoreMsg(string sMsgName)

[0754] Purpose

[0755] This method turns off reception of the specified message.

[0756] Parameters

[0757] Return Value

[0758] Nonzero on failure, 0 on success.

[0759] LoadMsgFromStringV

[0760] long LoadMsgFromStringV(variant vMsg)

[0761] Purpose

[0762] This method loads a message from a given variant array of bytes. This variant must have been previously provided by GetMsgAsStringV; any modification may cause unpredictable results.

[0763] Parameters

[0764] Return Value

[0765] A number >0 to be used to refer to the loaded message on success;

[0766] Negative on failure.

[0767] ReadMsgFromFile

[0768] long ReadMsgFromFile(string sFilePath)

[0769] Purpose

[0770] This method loads a message from a given file. The file must have been generated from a call to WriteMsgToFile or GetMsgAsStringV.

[0771] Parameters

[0772] Return Value

[0773] A number >0 to be used to refer to the saved message on success;

[0774] Negative on failure.

[0775] RegisterModule

[0776] long RegisterModule(string sName, string sType)

[0777] Purpose

[0778] This method registers the module with the SILAS kernel. This causes the Initialized event to fire. No other methods on this OCX should be called until the Initialized event has fired.

[0779] Parameters

[0780] Return Value

[0781] Nonzero on failure, 0 on success.

[0782] RemoveKey

[0783] long RemoveKey(long IMsgID, string sKey)

[0784] Purpose

[0785] This method removes a key from a saved message; the key can specify a sub-message or a string.

[0786] Parameters

[0787] Return Value

[0788] Nonzero on failure, 0 on success.

[0789] RequestMsg

[0790] long RequestMsg(string sMsgName)

[0791] Purpose

[0792] This method requests that the given kind of message be sent to the module.

[0793] Parameters

[0794] Return Value

[0795] Nonzero on failure, 0 on success.

[0796] SaveCurrentMsg

[0797] long SaveCurrentMsg( )

[0798] Purpose

[0799] This method saves the current message for later use. The current message number is changed as a side-effect; 0 no longer refers to the current message after it is saved with this method. Note that this message must be deleted (using DeleteMsg) when you are done using it.

[0800] Return Value

[0801] A number >0 to be used to refer to the message on success; Negative on failure.

[0802] SendDeliveryConfirmation

[0803] long SendDeliveryConfirmation(long IMsgID)

[0804] Purpose

[0805] This method will send a delivery confirmation message in response to the given message if necessary (i.e., the message has a %Return field).

[0806] Parameters

[0807] Return Value

[0808] Nonzero on failure, 0 on success.

[0809] SendMsg

[0810] long SendMsg(long IMsgID, string sMsgName)

[0811] Purpose

[0812] This method sends the given message using the given translation name. It should only be used if the message is not caused by a previous message (such as a command); in that case, use SendReply instead.

[0813] Parameters

[0814] Return Value

[0815] Nonzero on failure, 0 on success.

[0816] SendMsgTo

[0817] long SendMsgTo(long IMsgID, string sMsgName, string sToName)

[0818] Purpose

[0819] This method sends the given message using the given translation name to the given module. Essentially, this function does the same thing as SendMsg, except that the ToName field of the translation will be replaced with sToName.

[0820] Parameters

[0821] Return Value

[0822] Nonzero on failure, 0 on success.

[0823] SendReply

[0824] long SendReply(long IMsgID, string sMsgName, long ISavedID)

[0825] Purpose

[0826] This method sends the given message using the given translation name in reply to the given message. This method should always be used when an output is caused by a particular message (usually a command or query).

[0827] Parameters

[0828] Return Value

[0829] Nonzero on failure, 0 on success.

[0830] String Exists

[0831] long StringExists(long IMsgID, string sKey)

[0832] Purpose

[0833] This method checks for the existence of a string key under the given message. Use this to differentiate between a key with an empty string as its value and a key which is not there. (GetString does not make the distinction)

[0834] Parameters

[0835] Return Value

[0836] Returns 1 if the string was found. Retruns 0 if the string was not found.

[0837] Returns negative number on error.

[0838] Translation Exists

[0839] long TranslationExists(string sTranslationName);

[0840] Purpose

[0841] This method checks to see if the given translation is in the set of translations currently loaded by the OCX. If bRaiseRareExceptions is set to True, then this method will raise an exception if the translation does not exist.

[0842] Parameters

[0843] Return Value

[0844] If the translation exists, the return value is 1. If the translation does not exist, the return value is 0, unless bRaseRareExceptions is set to True, in which case an exception is raised.

[0845] UnregisterModule

[0846] long UnregisterModule( )

[0847] Purpose

[0848] This method unregisters the module. After this method is called, the module will not receive messages.

[0849] Return Value

[0850] Nonzero on failure, 0 on success.

[0851] WaitFor

[0852] long WaitFor(string sMsgName, integer ITimeout)

[0853] Purpose

[0854] This method waits up to ITimeout seconds for the given message to come in. Note that this method does not request the specified message, you must do that yourself before calling this method. In effect, this method does a ProcessMessages loop (DoEvents in Visual Basic) until the requested SILAS message comes in. While the loop is going on (the method has not returned), other events may occur (mouse clicks, SILAS messages, etc.). This means that if this method is called from the handler for the OnRcv event and a SILAS message comes in before the message you are waiting on, the OnRcv event handler will be reentrantly called. It is safe to call WaitFor reentrantly (i.e., in the middle of another WaitFor call).

[0855] The function will return after the given timeout occurs, even if the message has not been received. The function may not return immediately on timeout; the only guarantee is that if a timeout occurs, it will process no more than one message before returning. IMPORTANT: If WaitFor successfully returns, it changes the current message (ID=0) to the message that it was waiting for and just received.

[0856] NOTE: This function is for convenience in situations where there will be a very short wait; the same effect can be obtained without reentrancy by saving your state and exiting your event handler (when you are ready to wait). When the requested message comes in, the event handler will again be called and you can pick up where you left off.

[0857] Parameters

[0858] Return Value

[0859] 0 if the message was received, 1 if it was not. Returns a negative value if the message name is invalid.

[0860] WriteMsgToFile

[0861] long WriteMsgToFile(long IMsgID, string sFilePath)

[0862] Purpose

[0863] This method writes a message to a given file.

[0864] Parameters

[0865] Return Value

[0866] 0 on success, negative on failure.

[0867] Error Codes

[0868] The primary activity of the Router is the routing of messages. It takes in messages from modules and dispatches them to all of the modules that have requested them. In one embodiment, it may also be responsible for informing modules when the messages that they provide are needed.

[0869] Data Structures

[0870] Text to Integer Map

[0871] For increased performance, all of the text strings used to describe a message (From Name, From Type, To Name, To Type and Message Type) and module names are mapped to integers for comparison operations. The text to integer map maps all of the strings currently seen to numbers; new entries in the map are added as new strings are seen.

[0872] Message Item

[0873] A message item is the internal representation of a message sent by one of the modules; it is also the means of communication between the Receiver thread and the sender threads. It exists only in the message queue. The structure of the item follows.

[0874] Message Description

[0875] Item Type

[0876] This field identifies the nature of the Message Item; it can take on the following values:

[0877] >0 regular message

[0878] 0 dummy message

[0879] −1 Request message

[0880] −2 Ignore Request message

[0881] Item Filled Event

[0882] If this item is set, it is not the dummy item. The Item Filled event is only reset if the item is the dummy item. Since all new items placed in the queue start out as an empty dummy item and then get filled in, this event signals when the item is ready to be processed. This allows sender threads to efficiently wait for a new item.

[0883] Integer Description

[0884] The message destination/routing is represented by five integers that represent the five strings that describe a message (From Name, From Type, To Name, To Type, Message Type) as obtained from the text to integer map.

[0885] String Description

[0886] Also included are the strings to be used when a sender thread actually posts the message to a module (From Name, From Type, To Name, To Type, Message Type).

[0887] Message Content

[0888] The means used to communicate the data in a message is a file mapping. The content of a message is the name of the file mapping and the size of the file mapping. A handle to the file mapping is also included (it is held open until all sender threads have seen the message; the last one closes the handle).

[0889] Sender Module

[0890] This is the integer that corresponds to the name of the module that sent the message (obtained from the text to integer map). This is set to 0 for messages that do not need to identify the sender (regular messages).

[0891] Touch Count

[0892] Records the number of sender threads that still need to “touch” the item.

[0893] Touch Count Mutex

[0894] Only one thread may change or read the touch count of an item at a time; it must hold this mutex to do so. This protects against two threads trying to delete the same item.

[0895] Message Queue

[0896] The message queue contains all of the message items that have not yet been fully processed and one dummy item. The dummy item is always at the head of the message queue; it is differentiated from the other messages by the fact that it has an item type of 0 and its ItemFilled event is reset. The queue is a singly linked list (tail→head); pointers to the head and tail are maintained.

[0897] Threads

[0898] The Router has two different types of threads that work together to carry out routing:

[0899] Receiver Thread (1)

[0900] This thread is the primary thread of execution. It handles receiving messages and all registry functions.

[0901] Registration

[0902] The Receiver records the registration information. This includes module names, module types and the interfaces for each. It also launches a Sender Thread for each registration. It gives the new thread a pointer to the head of the message queue so it can start processing messages.

[0903] Message Reception

[0904] When the receiver thread gets a message it creates a new dummy item and puts it at the head of the message queue (immediately after the current dummy item). It then fills in the fields of the current dummy item, opens the file mapping included in the message to guarantee that it will continue to exist until all of the modules have had a chance to get it, and places a handle to the mapping in the dummy item. It then sets the Touch Count of the dummy item to the total number of active threads (so they can all touch it before it is deleted). Finally, it changes the Item Type of the current dummy item to the item type for a regular message and signals its ItemFilled event. This process is shown in FIG. 4.

[0905] Message Requesting

[0906] When a module wishes to start receiving a certain type of message, the receiver thread places a Request message in the message queue (in the same manner that it places regular messages there). The Request message tells the appropriate Sender Thread to start passing messages of the given type on to its attached module.

[0907] Message Blocking

[0908] When a module no longer needs a certain type of message, it tells the Receiver, and the Receiver places an Ignore Request message into the message queue in the usual manner. That message tells the appropriate Sender Thread to stop passing on the given type of message.

[0909] Sender Threads

[0910] The sender threads each wait on a terminator event whenever they are sleeping. When the terminator for a particular thread gets set, terminates gracefully, deleting any allocations it has made, releasing the interface to the module it services and closing the terminator event; they do not touch the queue or any items in it when terminated. The receiver thread is responsible for cleaning up of the queue. To this end, the sender threads maintain a pointer to the item that they are currently processing; the receiver thread also has access to the pointer and uses it to clean up after the thread is terminated.

[0911] Startup

[0912] There is one Sender Thread per registration entry. Each time RegisterModule is called, a Sender Thread is launched to handle it. The thread is provided with the module name and interface that it is to service, and a pointer to the head of the queue. It begins to search the message queue for messages that it needs to pass on. Before it processes an item in the queue is performs an efficient wait on the ItemFilled event for the item. If the item is not the dummy item, the wait ends immediately. If it is the dummy item, the wait will not end until the dummy item is replaced by a new message; at that time the receiver thread will set the ItemFilled event and the sender thread will continue processing.

[0913] All Messages

[0914] When the thread is finished processing a message, it decrements the touch count and compares it zero. If it matches, then all of the threads have had a chance to see the message and it needs to be deleted. The thread closes the file mapping handle for the message, closes the handles and removes it from the queue.

[0915] Regular Messages

[0916] When a Sender finds a regular message in the queue it compares it with all of the messages it is supposed to pass on to its module. If it matches one, the Sender Thread calls the module with the message. The thread holds no mutexes when it sends the message and it immediately checks the termination event upon returning from the call. If there is an exception during the call to the module, the sender thread posts a message to the receiver thread requesting that the sender thread be removed (i.e., unregister the thread's module); it then waits for the terminator event. Under certain circumstances, though, the thread will continue to attempt to send the message after an exception occurs.

[0917] Request Messages

[0918] These messages are sent when a module wishes to start receiving messages of the given type. The thread compares the module name included with the message item to the one the thread was registered under. If it matches, the thread adds the given type to its list of messages to pass on.

[0919] Ignore Request Messages

[0920] These messages are sent when a module wishes to stop receiving messages of the given type. The thread compares the module name included with the message to the one the thread was registered under. If it matches, the thread removes the given type to its list of messages to pass on; if it isn't there, it does nothing. Only exact matches are removed.

[0921] General Operation

[0922] The receiver thread creates a Sender Thread for each module registration it gets. It then puts Request messages into the message queue for each kind of message that the module has requested be sent to it. The sender threads then update their lists of messages to pass on. As the Receiver gets messages, it places them into the queue. The sender threads examine and deal with the messages as they get to them, calling out the their associated modules as necessary. The last thread to examine a message removes it from the queue. The foregoing process is shown in FIG. 5.

[0923] The Messaging Control (also referred to as “the OCX”) provides a means for the Router to communicate with each module in a system, and for each module to communicate with the Router. In cooperation with the Keeper, the OCX controls where a module's outputs go and where its inputs come from. The OCX abstracts the module programmer away from other modules in the system. This allows module programmers to concentrate on the functionality of the module, rather than what other modules may control it or consume its output. The OCX notifies the module when a new message arrives, allows the user to manipulate messages (saving, creating, modifying, etc.) and send out messages. In one embodiment, the Messaging Control OCX is written using Visual C++4.2 with the DLL version of MFC (MFC42U.DLL). It is a Unicode program, with Windows NT as the target platform.

[0924] The Messaging Control will be embedded in each software module that uses the technique of the present invention. While it is believed that it will normally be advantageous to always use the Messaging Control to pass messages among modules in a software system, the invention and claims do not require that each and every module always use the Messaging Control (and Router) to exchange messages. Those of skill in the art will appreciate that the Messaging Control and use of the Router adds some amount of processing overhead, and it is possible that there may be modules for which it is important to minimize execution time. This will always be a trade-off, as conventional messaging techniques between software modules may be faster, but do not afford the ease of software maintenance and other advantages provided by the present invention. Nevertheless, for those software modules that do incorporate a Messaging Control as contemplated hereby, the following pseudocode provides an explanation of how code may be written.

[0925] The Messaging Control fires an event each time a message is received. Here is what the event handler would normally look like in a module:

[0926] procedure OnSilasMessage(sMessageName: string)

[0927] begin

[0928] if sMessageName=‘Command’ then

[0929] ReadPlate(0)//0 here identifies the current message

[0930] else if sMessageName=‘Action Config’ then

[0931] ShowActionConfig

[0932] else if sMessageName=‘Unload’ then

[0933] UnloadModule

[0934] end;

[0935] When the module is loading it will also execute code similar to the following in order to inform the router that it wants certain messages:

[0936] SILAS.RequestMsg(‘Command’);

[0937] SILAS.RequestMsg(‘Action Config’);

[0938] SILAS.RequestMsg(‘Unload’);

[0939] From the point of view of a module, a message is structured like a tree. Each node in the tree has a set of strings associated with it and a set of submessages (children). Messages and submessages are identified by ID numbers; all methods that operate on specific messages or submessages require that this ID be provided as shown in FIG. 3. For instance, referring to FIG. 3, to get a string from the “Read Two” branch, one would use the number 11 to identify it:

[0940] Rome.GetString(11,‘Wavelength’)

[0941] The number that is associated with a particular branch is obtained by providing the number identifying its parent and a string key:

[0942] Rome.GetSubmsg(MsgID, ‘Parameters’)

[0943] The current message has a constant identifier (0), and when it is saved, a new number is provided to identify it. Similarly, when a message is created, the module is given the number with which to reference it. The numbers are generated on the fly, and when the message is transmitted, the numbers used by the receiver will likely differ.

[0944] Internal Representation

[0945] Internally, messages are represented in essentially the same manner as they are presented externally. A tree structure is maintained for each message. Initially, only the root node of a message has a number associated with it; when the module asks for a reference number for a particular node that doesn't have one yet, it is generated.

[0946] All of the numbers associated with the nodes are included in an ID→Message node map (hash table). This allows any node at any level of the tree to be found by a single number. The reference numbers are not themselves direct pointers to the nodes because for safety the OCX would have to validate them (look them up in a hash table) anyway.

[0947] All nodes on all message trees are structured identically; there is no difference between a node at the second level of the tree and the twenty-second level. However, the root nodes are differentiated by the fact that they have no parent. Each node has two maps (hash tables): The Key→String map and the Key→Submessage map. In both cases the key is a string. The submessage map contains pointers to the submessages (nodes) associated with the keys.

[0948] Node Data:

[0949] Representation During Transmission

[0950] To send a message tree to another module the OCX must package it into a contiguous chunk of memory (a file map) as this is the preferred means of communication. A pre-order traversal of the tree is performed; the data for each node visited is written out as follows (the character I (vertical bar) will represent null (0)):

[0951] <Node Name>|<# of Children>|<Data Length>|<Node Data>

[0952] <Node Name>|<# of Children>|<Data Length>|<Node Data>

[0953] . . .

[0954] (Note: no CR-LF is included between nodes—it is added here for clarity)

[0955] Internally “Node Data” is formatted similarly:

[0956] <Key>|<String Length>|<String>

[0957] <Key>|<String Length>|<String>

[0958] <Key>|<String Length>|<String>

[0959] (Note: no CR-LF is included between key-string pairs—it is added here for clarity)

[0960] Message Manipulation

[0961] As noted above, the Messaging Control OCX provides a rich set of methods for manipulating a message.

[0962] Assigning Numbers

[0963] The module will refer to messages and submessages by a numeric identifier; for the modules purposes, every message node has a unique number. Internally, a node only gets a number when it is needed (i.e., when the module requests it). All nodes can be reached by enumerating the root nodes (which always have ID's) and then traversing the message tree of each root message.

[0964] To generate unique numbers, the OCX maintains a counter that is incremented each time a new number is needed. A check is made to see if the number is in use (looking it up in the hash table); if it is in use, the counter is incremented again. This continues until an unused number is found. (Note: here, incrementing includes wrapping the value such that it is always in the range (1, 2{circumflex over ( )}31−1)).

[0965] Creation and Deletion

[0966] The Current Message

[0967] The current message is held separately from all of the other messages held by the OCX. For simplicity in accessing messages, the number 0 will exist in the ID→Message map when there is a current message; its entry will contain a pointer to the root node of the most recently received message. When there is no current message, there will be no entry for 0 in the ID→Message map. The current message will be created when a message is received and deleted when the module's RcvMsg event handler finishes, or the user calls WaitFor, whichever occurs first. If a WaitFor call succeeds, the current message will be the message that the module was waiting for; if it fails, there will be no current message. The status of the current message will not change after the OCX automatically waits for a return receipt (i.e., the return receipt does not become the current message).

[0968] Other Messages

[0969] Other messages may be created by saving the current message or by building from scratch. After the current message is saved, two numbers will reference the message: 0 and the number assigned to it. This will be true until the RcvMsg event ends or WaitFor is called, after which time only the assigned number will reference it. Any message which is not the current message will only be deleted when the module explicitly requests it or the module unregisters.

[0970] String Retrieval

[0971] When a module wishes to retrieve a string from a message, the appropriate message is found using the reference number and key supplied. If either is invalid, an error code is returned. All strings are internally held in MFC CStrings. Because data strings (not keys) may contain null characters, in one embodiment, it is important that no routines be used that assume null-termination. Fields that are used by the OCX (system keys) may never contain null characters. This simplifies the OCX, since it only manipulates the data associated with system keys; all other data is only handed to the module. It is known that in MFC 4.2, a CString with embedded nulls can be turned into a BSTR with embedded nulls using CString::SysAllocString. The OCX will use this method of returning a string to a module.

[0972] String Storage

[0973] When a module wishes to add a string to a message, the appropriate message is found using the reference number supplied. If the ID is invalid, an error code is returned. The MFC 4.2 implementation of Invoke converts BSTRs (length prefixed strings) into a LPCTSTR pointing at the string portion of the BSTR. In order to copy this into a new CString for storage, the length of the string must be determined. Since the string may contain null characters, one must examine the length prefix. This means that the OCX will look at the 4 bytes previous to the string; the validity of this operation is dependent on the MFC 4.2 implementation. The MFC 4.2 copy constructor for the CString does not assume a null terminated string, which allows the data strings to be copied freely. The validity of this operation is dependent on the MFC 4.2 implementation.

[0974] Message Copying

[0975] Copying a message (and its submessages) requires that the full tree under that message be reproduced. The ID numbers for the new submessages will be set to a negative number rather than copied.

[0976] Message Deletion

[0977] When a message is deleted the full tree under that message will be deleted. The message ID of each node of the message tree will be removed from the ID map.

[0978] Enumeration

[0979] The module will be able to enumerate all of the strings and submessages at any particular level of the message. The enumeration facilities of the MFC CMapStringToString and CMapStringToPtr will be used. A POSITION will be held for each map (hash table), indicating the status of its enumeration.

[0980] Message Storage

[0981] To allow a module to store a message on disk or other media outside of the OCX's control, the OCX will, on request, provide a string representation of a message. It will also allow the creation of a message from a string (i.e., reverse the process). This will be done in the same way that a message is sent through the router; it will be converted into a chunk of memory and then into a BSTR. When a message is created from a string, the usual method of building a message tree will be used.

[0982] The Interface to the Router

[0983] Registration

[0984] When the module makes a call to RegisterModule, the OCX must first find the Router. The Router registers itself as the active object of type “Rome.Kernel”. It is simply a matter of using standard OLE functions (CLSIDFromProgID and GetActiveObject) to get an IDispatch interface (the OLE Automation interface) on the Router. Once that is done, the OCX needs to do the actual registration. This requires that the OCX provide the Router with an interface to use when the Router needs to notify the OCX of a new message; this is done by making a call to the RegisterModule method of the Router interface.

[0985] Router to OCX

[0986] The Router communicates to modules by executing standard methods on them; the module must have a function that the kernel can call (using OLE) whenever a message arrives or something else happens. Currently, there are only two standard methods that must exist with special id's:

[0987] [id(1)] void PostMsg(BSTR ToName, BSTR ToType, BSTR FromName, BSTR FromType, BSTR MsgType, BSTR FileMapName, long MapLength);

[0988] [id(2)] void MsgWanted(BSTR ToName, BSTR ToType, BSTR FromName, BSTR FromType, BSTR MsgType, boolean Wanted);

[0989] PostMsg is used to notify the OCX that a message has arrived; its parameters specify the addressing information and the map that contains the contents of the message (in the form of a Win32 file map).

[0990] OCX to Router

[0991] The Router registers itself as the currently active Rome.Kernel object; this allows the OCX to find it. The Kernel has a set of methods for registering, requesting messages and sending messages.

[0992] Translations

[0993] In one embodiment, the Kernel uses a five part address to route messages:

[0994] ToName, ToType, FromName, FromType, MsgType

[0995] The OCX presents the module writer with the ability to specify an address using a one part address (the message name). This address is then translated to a five part address (or several of them) when the message is sent through the kernel. This allows the routing of a module's messages to change without changes to the module's code.

[0996] The translations are stored in the Keeper module in a branch named “%Messaging”. There is one such branch for each module. When the OCX is registering the module (during RegisterModule) it queries the Keeper for these translations; if the Keeper does not respond, the OCX will time out and fire the Initialized event with an error code.

[0997] Since the Keeper must communicate through the Router using the same OCX as the rest of the modules, the OCX provides a property and method specifically for the Keeper. The property (bRetrieveTranslations) allows a module to stop the OCX from querying the Keeper for translations. The method (AddTranslation) allows the module to add a translation; in this way, the Keeper can use the normal OCX and provide hard-coded translations for itself.

[0998] Message Reception

[0999] Several technical issues come into play when it comes to how the OCX will process a message and present it to the module.

[1000] File Maps

[1001] Win32 allows one to create a file map (the contents of a file mapped into a linear address space so one can simply view the file as memory) on the page file and give it a name. The name given to it is valid in any process space; this is the way the Router passes data between modules. A file map is of fixed size (can't be grown or shrunk) once created. To overcome this, the OCX uses several features of Win32 memory management. The OCX will reserve a chunk of memory (using the reserve flag); then, as the map is filled in, the map will be committed piece by piece. The initial reservation will be a guess; if the message turns out to be too big (i.e., the system runs out of space in the middle of building it), a new guess will be made (double the old one) and the previous memory map will be copied to the new, bigger one. Future guesses will be at the larger size. It is also important to note that a memory mapped file only exists while some process holds a reference to it. The OCX will name its file maps in the following way:

[1002] %%<Module Name><Module Type><counter>_—

[1003] If a conflict occurs (i.e. the name is already in use), the counter is incremented and another name is generated. This continues until an unused name is found. The counter is incremented after each message is sent.

[1004] OLE Method Calls

[1005] The Router uses OLE to make method calls on the OCX (PostMsg). These calls can only be made in a blocking mode; this means that the caller is blocked (sleeping) until the method finishes executing. This requires that the Kemel have multiple threads so that it can service many different modules simultaneously. The current implementation of the Kemel has a single thread per registered module; this thread services a given module, making the method calls when messages arrive.

[1006] Message Flow

[1007] When a message comes in, the PostMsg method is called by the Router. Because a file map only exists while some process holds a reference to it, it is important that the information in the file map be retrieved during the execution of the PostMsg method; the Kernel will ensure that the map exists until after the end of the PostMsg call by maintaining a reference of its own, but after that point its existence is not guaranteed.

[1008] The file map for the message is opened and the OCX builds a message tree from the contents. The file map is then closed. Because OLE calls are blocking, it is important that the RcvMsg event (which allows the module to process the message) not be fired during the execution of the PostMsg method. If it were fired then, it is possible that the module would call the WaitFor method; it would then timeout because no more messages can be received until the PostMsg method returns (allowing the thread in the Kernel to stop blocking). Problems will also occur if the module tries to unregister itself during the RcvMsg event.

[1009] A Windows™ message is then posted to the Bouncer window with a pointer to the root of the new message tree. Once that is done, the PostMsg method returns. At some time after that, the Bouncer window receives the message and calls the message handler in the OCX.

[1010] What this handler does with the message is dependent on the current state of the OCX; most of the complication comes from properly handling WaitFor calls The WaitFor method runs a Windows™ message loop, checking a flag after the processing of each message; the flag indicates whether the most recently awaited message has arrived. This is further complicated by the fact that it is possible that the user will call WaitFor in the middle of the message loop of a previous WaitFor (since regular events will occur during the loop). This is dealt with in the following manner:

[1011] A wait stack is maintained that contains the identity of each message that is currently being awaited; the item at the top of the stack is the most recent.

[1012] A held message list is maintained; this list holds messages that are awaited (i.e., indicated in a previous WaitFor call), but whose matching item on the wait stack is not at the top yet.

[1013] When a message comes in, a check will be made to see if the wait stack is empty. If it is, then the message becomes the current message and the RcvMsg event will fire. After the event is done, the current message is deleted (if it wasn't saved) and the reference to it in the message ID map is removed.

[1014] If the wait stack is not empty, the new message will be compared with the top item on the wait stack. If it matches, then it is added to the held message list and a flag is set; the flag tells the WaitFor routine that it needs to check the held message list against the message it is waiting for. When the message handler returns, the most recent WaitFor function will get control and notice that its wait is over. If the new message doesn't match the item at the top of the wait stack, it is compared with each of the other items in the wait stack. If it matches any of them, it is placed in the held message list, and the message handler returns.

[1015] Reflector Window

[1016] In order to receive a Windows™ message, there must be a window to receive it. The OCX has no visual representation, and as such has no window. To allow it to send messages to itself a hidden window is created to “reflect” messages to the control. Currently, only one message (the message indicating a message has been received) is reflected. The reflector window simply acts as a pass through for messages that it reflects; a function prototyped exactly like a regular window handler is called in the OCX (the message handler mentioned in.

[1017] Non-Blocking Waiting—WaitFor

[1018] The WaitFor method provides a way to wait for a particular message, without blocking the reception of other messages (or events). This means that using this function may cause re-entrancy. This method performs a Windows™ message loop;

[1019] after each message is processed in the usual manner, a flag is checked. When the flag is true, it tells the WaitFor routine that it needs to check the held message list against the message it is waiting for (usually set by the message handler when the awaited message is received). If the top message in the wait stack matches any of the messages in the held message list, the waitfor function stops looping, pulls the held message off the list and makes it the current message. It then returns. If the top message in the wait stack does not match any of the messages in the held list, the method will reset the flag and continue looping.

[1020] After each message is processed, the time is checked to see if the timeout period has passed; if so, the method stops processing messages and returns. When there are no messages in the queue, the method will use MsgWaitForMultipleObjects to sleep until the timeout occurs or a message comes in.

[1021] Translating Incoming Messages

[1022] The OCX will translate the 5-part addresses used by the kernel into the one word addresses used by modules. Only the first matching translation will be used; if no translation matches, the message will be ignored. The translation will occur during the execution of the PostMsg method.

[1023] Building a Message Tree

[1024] Messages are stored by performing a pre-order traversal of the message tree. To generate a message tree from a message map, the following algorithm will be used The details of the parsing are explained above.

[1025] Maintain a parent stack; this stack will contain pointers to parent nodes.

[1026] Starting from the first node in the map:

[1027] 1. Create the node and build the map of string data.

[1028] 2. If the stack is empty, this is the root node, so save a pointer to this node and skip the rest of this step.

[1029] Pop an item from the parent stack. Copy that to the parent pointer of this node. Add the name of this node to the string→child map of the parent.

[1030] 3. For each child of this node (as given in the file map) push a pointer to this node onto the parent stack.

[1031] 4. Repeat on the next node in the file map

[1032] Error Codes

[1033] All error codes will be 32-bit values. The error codes for the various methods will not overlap.

[1034] A “Keeper” is defined as a combination of: (a) a collection of message translations describing messages that may be exchanged among software modules in a software system comprising multiple modules and in which at least two of the modules utilize a common control to exchange messages; and (b) software capable of maintaining (a). At a minimum, a definition of a “message translation ” includes (i) a name of the translation (also referred to as a “translation name” or a “key”), and at least the following message attributes: (ii) the name of an intended recipient module, (iii) a type of an intended recipient module, and (iv) an identifier indicating a type of a message. In one embodiment, message attributes (ii), (iii) and (iv) may be specified by a universal match indicator, such as an asterisk (“*”), which means the particular message attribute, when used to indicate a message attribute to be received, may match anything, as described further below. There may be additional message attributes defined for each message type. For example, in one embodiment, fields may be added indicating: (v) the name of the sending module; and (vi) the type of the sending module.

[1035] In one embodiment, the collection of message translations may be stored in a registry which is accessed by the software included in the Keeper. Different collections of message translations may be grouped together. For example, in FIG. 7, there are sections for “input” message translations, “reply” message translations, and “output” message translations.

[1036] In one embodiment, the Keeper also stores and maintains other configuration settings for the software system, in a hierarchical manner analogous to the registry in Windows. The term “Registry” is used herein to refer to the database maintained by the Keeper, and does not necessarily mean the registry used by Windows or some other operating system. Nevertheless, it would be possible for one of skill in the art to store all of the information normally stored in the Registry in the Windows (or other operating system) registry. In the representative Registry, an excerpt of which is shown in FIG. 7, the top level of the hierarchy comprises a software module name for each software module. In this example, some of the software modules control communications between the software system and various pieces of robotic equipment. For example, the SMax software module includes subdirectories for Class, Executables, and Messaging. The collection of definitions of message types used by the SMax module are shown in the right hand pane. Each line in the right hand pane (except for lines beginning with #, which are comment lines) comprises a definition of a message type. In the embodiment shown in FIG. 7, each message translation has a translation name and five message attributes. The translation name, is followed by an equal sign (=), The following five message attributes are separated by colons (:), and represent: (i) the name of the intended recipient module, (ii) the type of the intended recipient module, (iii) the name of the sending module, (iv) the type of the sending module, and (v) the message type.

[1037] In one embodiment of the invention, the Keeper stores program-specific settings for each of the programs, and the Keeper software is responsible for the loading and unloading of programs, and maintains reference counting on each of the programs. When a program is no longer needed, for example, after an automated assay has completed, the Keeper software unloads the software. It should also be appreciated that other software modules or the user of the software system can also cause software modules to be loaded directly without involving the Keeper.

[1038] The specific techniques and methods that may be used to perform the tasks of the Keeper is well-known within the software programming and data storage arts, even though the Keeper comprises the particular combination of data and functions specified above as being required of the Keeper. Further details of a representative embodiment of a Keeper are as follows.

[1039] The Keeper acts as a central repository for all configuration information, providing both a user interface and a software system interface on the information that it holds. It is also responsible for loading and unloading other modules; it keeps track of which modules are currently needed and how many references there are to them. Modules are only unloaded after all references to them have disappeared (via unload requests).

[1040] Data Structure

[1041] The Tree

[1042] The Keeper may present its data in a tree or directory structure. This means that when one wishes to get at a particular piece of data, it will be specified by giving a path from the root of the tree (e.g., SMax\foo\dir). In one embodiment, relative specification of nodes on the tree is not be supported. By convention, each module in the system that comprises the Messaging Control will have a branch off the root associated with it.

[1043] Leaf Nodes

[1044] In one embodiment, branches of the tree will not hold data; only leaf nodes will contain data. Until such time as data is inserted in a node, it is considered a branch node; once data is inserted it will be considered a leaf node and cannot be converted back unless it is deleted and recreated. The data may be in the form of a Unicode string. All characters including embedded nulls may be allowed. The only limitation on the length of the data will be available disk and memory.

[1045] Special Leaf Nodes

[1046] Certain nodes in the tree may be set aside as special. These nodes are found immediately off of the branch for each module (i.e., each module has its own). In one embodiment, %Executables and %Messaging are required by the Keeper for the module to be run; the others are optional.

[1047] %Executables

[1048] This node, found immediately off of the branch of each module, contains the set of executable files, one per line with full path, that should be launched when the module is loaded. The executables will be loaded in the order given, top to bottom.

[1049] %Helpers

[1050] This node, found immediately off of the branch of a given module, lists all other modules that should be loaded along with the given module. They are given one per line and are loaded in the order given, top to bottom. If the line: %THIS is placed in the list, the executables found in %Executables will not be loaded until all helpers before the %THIS line have loaded. Modules listed after %THIS will be loaded after the executables have finished loading (responded to an existence query).

[1051] %Messaging

[1052] This node holds the message translations for the module.

[1053] %Class

[1054] Under this branch is a branch for each class that the module fits under. The contents of the leaves are undefined.

[1055] %Properties

[1056] Under this branch are entries that describe the module. The actual set of properties depends on the module. This set of properties should not be confused with the properties provided in a status message; these properties are static, those in a status message are dynamic. An example of a static property is the carrying capacity of a Transport module.

[1057] Interfaces

[1058] Data Manipulation

[1059] The Keeper interface will allow other modules, through messages, to create, copy, delete and rename both branch nodes and leaf nodes. It will also allow modules to get and set data from leaf nodes using messages. Modules may also provide a full branch structure to be appended to the tree. All operations may require a full path within the tree.

[1060] Searching

[1061] Modules will be able to identify which modules contain a certain path; for instance, to find out all modules that output Data, one would search for the path Outputs\Data. Modules may also specify what the leaf node at the end of the path must contain for the module to be included in the match list; for instance, if one wanted to find all modules that output a Data message with a Count of 3, one would give a path of Outputs\Data\Count and a leaf contents of 3.

[1062] Loading and Unloading

[1063] The Keeper interface will allow modules to load and unload other modules. To deal with the fact that multiple modules may be simultaneously trying to load or unload a particular module, the Keeper may implement reference counting on each module. Modules will remain loaded while they have references to them and be unloaded at some time after all references disappear. Modules will not be immediately unloaded; instead, they will be left loaded but unreferenced for a time. Once a certain amount of time has passed since the last reference (configurable through the user interface) or on command (via the user interface or a message) the unreferenced modules will be unloaded (using ROME messages).

[1064] User Interface

[1065] Data Manipulation

[1066] The Keeper provides a graphical interface for user editing of all information that it holds. A view of the tree and a view of the currently selected leaf node (if any) will be presented. The data in a leaf node will be presented in a text format; appropriate actions will be taken to assure that binary data is viewable as though it were text. The %Messaging node may have a viewer that shows the translations in a table format.

[1067] Loading and Unloading

[1068] The Keeper may present the user with the ability to load modules. The user may also be able to force the unloading of all unreferenced modules. It is desirable that the user be able to unload referenced modules as well; the interface to this may be hidden if possible.

[1069] Importing and Exporting

[1070] The user may be able to import and export branches of the tree. Full paths to any Registry files involved as well as full paths within the Registry files involved may be required.

[1071] Keeper Messages

[1072] The Keeper may have the following message types defined for it.

[1073] Load Module—The keeper is responsible for loading the module, verifying that it loads correctly and replying to this message with the results. The Keeper may not actually need to load the module if it is already running; in this case, the Keeper will simply increment a reference count, to keep track of how many modules expect the module to be running.

[1074] Load Finished—This message is a reply to the Load Module message. It indicates whether the instance loaded successfully.

[1075] Unload Module—This message is sent to the Keeper in order to unload a currently running module. The Keeper decrements its reference count on the module and if no references remain, it unloads the module (after a “caching” delay).

[1076] Unload Finished—This message is a reply to the Load Module message. It indicates that the instance unloaded successfully (or the reference count was decremented).

[1077] Module List Query—This message is usually sent to the Keeper to find a set of modules.

[1078] Module List Reply—This message is sent in response to a Module List Query. It lists info on all of the modules that match the criteria.

[1079] Get Module Data—This message requests registry data from the Keeper.

[1080] Module Data Reply—This message is sent in reply to a Get Module Data message. It provides the requested data.

[1081] The Keeper will respond to all received messages with appropriate error messages if an error occurs. No user interface (e.g., dialog boxes) will be brought up if the error results from a ROME message.

[1082] Those of skill in the art will readily appreciate the elegance with which the present system allows additional modules to be added to an existing software system with little or no modification to pre-existing software modules. A specific example of how code could be written is follows. First, assume a simple system comprising two modules, a controller and a reader, in which the controller instructs the reader to take a reading. It is envisioned, while not mandatory, that the controller module and the reader module would be under the control of a single operating system. Conventional programming techniques using COM suggest the following pseudocode be used:

[1083] Controller Code:

[1084] procedure ReadPlate;

[1085] var

[1086] Dev: IDeviceInterface;

[1087] begin

[1088] Dev:=CreateObject(‘Fluostar.Reader’)

[1089] Dev.ReadPlate(ID, WaveLength1, Wavelength2, Temperature Setting, Cycles)

[1090] while not Dev.FinishedReadingPlate do

[1091] wait;

[1092] end;

[1093] Reader Device Code:

[1094] procedure ReadPlate(ID, Wavelength1, Wavelength2, TempSetting, Cycles)

[1095] begin

[1096] // Make the hardware read the plate

[1097] // save the data to disk in a hardcoded format

[1098] Dev.FinishedReadingPlate=true

[1099] end;

[1100] Now, assume further that one desires to add a third module to the system to log the commands and data to a proprietary database. The changes to the foregoing code would be as follows. (The added code is in bold)

[1101] Controller Code:

[1102] procedure ReadPlate;

[1103] var

[1104] Dev: IDeviceInterface;

[1105] Logger: ILogger;

[1106] begin

[1107] Dev:=CreateObject(‘Fluostar.Reader’)

[1108] Dev.ReadPlate(ID, WaveLength1, Wavelength2, Temperature Setting, Cycles)

[1109] Logger:=CreateObject(‘Database Logger’)

[1110] Logger.LogFluoCommand(‘Fluostar.Reader’, ID, WaveLength1,

[1111] Wavelength2, Temperature Setting, Cycles)

[1112] while not Dev.FinishedReadingPlate do

[1113] wait;

[1114] end;

[1115] Reader Device Code:

[1116] procedure ReadPlate(ID, Wavelength1, Wavelength2, TempSetting, Cycles)

[1117] var

[1118] Logger: ILogger;

[1119] begin

[1120] // Make the hardware read the plate

[1121] Logger:=CreateObject(‘Database Logger’)

[1122] Logger.LogFluoData(ID, WaveLength1, Wavelength2, TempSetting, Cycles, Data)

[1123] Dev.FinishedReadingPlate=true

[1124] end;

[1125] Note that to add the logging, both pieces of code are changed. In a system comprising hundreds of modules, if logging was desired from all 100 modules, each module would need to be changed in a similar manner.

[1126] Pursuant to the present invention, the code for original two-module system would be as follows.

[1127] Controller Code:

[1128] Procedure ReadPlate;

[1129] var

[1130] nCommand: integer;

[1131] begin

[1132] // tell the SILAS Router to send the Controller all “Command Reply” message types

[1133] SILAS.RequestMsg(‘Command Reply’);

[1134] nCommand:=SILAS.CreateMsgtoSend

[1135] SILAS.AddString(nCommand, ‘Wavelength’, Wavelength1)

[1136] SILAS.AddString(nCommand, ‘Temperature’, Temperature)

[1137] SILAS.AddString(nCommand, ‘Cycles’, Cycles)

[1138] SILAS.RequestMsg(‘Command Reply’)

[1139] SILAS.SendMsg(nCommand,‘Command’)

[1140] SILAS.WaitFor(‘Command Reply’)

[1141] end;

[1142] Reader Device Code:

[1143] procedure ReadPlate(nCommand)

[1144] var

[1145] nReply, nData,i: integer;

[1146] begin

[1147] // tell the SILAS Router to send the Reader all “Command” and “Unload” message types

[1148] SILAS.RequestMsg(‘Command’);

[1149] SILAS.RequestMsg(‘Unload’);

[1150] // pull the parameters

[1151] Wavelength:=SILAS.GetString(nCommand, ‘Wavelength’)

[1152] Temperature:=SILAS.GetString(nCommand, ‘Temperature’)

[1153] Cycles:=SILAS.GetString(ncommand, ‘Cycles’)

[1154] // make the hardware read the plate

[1155] // make a data msg

[1156] nData:=SILAS.CreateMsgToSend

[1157] // copy the original command into it

[1158] SILAS.CopyMsgToKey(nCommand, nData, ‘Command’)

[1159] // throw in the 96 wells of data

[1160] for :i=1 to 96 do

[1161] SILAS.AddString(nData,‘Data Point’+i, Datapoint[i])

[1162] // tell the controller that we are done

[1163] nReply:=SILAS.CreateMsgToSend

[1164] SILAS.AddString(nReply, ‘Success?’, ‘True’)

[1165] SILAS.SendReply(nReply, ‘Command Reply’, nCommand)

[1166] end;

[1167] In the above example, the Keeper Registry would contain at least two message translation entries for the Controller module defining the translation names “Command” and “Command Reply” and their associated message attributes. Thus the following may be stored in the Registry in the Controller\%Class\%Messaging subdirectory (The #Inputs and #Outputs are comment lines):

[1168] # Inputs

[1169] CommandReply=%MN:*:%MN:*:Command Reply

[1170] # Outputs

[1171] Command=Controller:*:%MN:*:Command

[1172] The Keeper Registry would also contain, for the Reader module, translation names of “Command,” “Command Reply” and “Unload” and the associated message attributes in the Reader\%Class\%Messaging subdirectory:

[1173] # Inputs

[1174] Command=%MN:*:*:*:Command

[1175] Unload=%MN:*:*:*:Unload

[1176] # Outputs

[1177] Command Reply=%MN:*:%MN:*:Command Reply

[1178] The Controller code sends a message using the “Command” message translation via the line “SILAS.SendMsg(nCommand, ‘Command’)”, and the Reader module, after getting a reading, sends a message using the “Command Reply” translation name via the line: “SILAS.SendReply(nReply, ‘Command Reply’, nCommand).” In both cases, the message is received by the Router (which in this example has the module name SILAS), which in turn, sends the messages to any module that may have requested to receive messages matching, for example, the filter conditions represented by the “Command” or “Command Reply” message attributes.

[1179] To add a third module to the system to log the commands and data to a proprietary database, neither the Controller Code nor the Reader code would require modification. Instead, a new Logger module would merely contain commands such as the following:

[1180] At some time previous to the messages being sent (e.g., when the logger starts up, or at the start of a run), the logger would request the appropriate messages to be logged:

[1181] SILAS. RequestMsg(‘EveryMessage’)

[1182] . . .

[1183] When a command message comes in, the following procedure might be called:

[1184] procedure LogCommand(nCommand)

[1185] begin

[1186] // pull the destination name from %Address\ToName

[1187] Module=SILAS.GetString(SILAS.GetSubmsg(nCommand, ‘%Address’), ‘ToName’)

[1188] // pull the parameters

[1189] Wavelength:=SILAS.GetString(nCommand, ‘Wavelength’)

[1190] Temperature:=SILAS.GetString(nCommand, ‘Temperature’)

[1191] Cycles:=SILAS.GetString(ncommand, ‘Cycles’)

[1192] TimeStamp:=SILAS.GetString(ncommand, ‘Cycles’)

[1193] // write out a comma-delimited list of the parameters and the time to a file

[1194] Writeln(CommandLogFile, Module+‘,’+Wavelength +‘,’+Temperature+‘,’+Cycles+‘,’+TimeStamp)

[1195] end;

[1196] In addition, an entry could be made in the Keeper defining a “EveryMessage” message type in the LogCommand\%Class\%Messaging subdirectory as follows:

[1197] # Inputs

[1198] EveryMessage=*:*:*:*:*

[1199] Those of skill of the art will appreciate that the above data logging procedure may comprise the common message handling control merely be referencing SILAS.RequestMsg and SILAS.GetString in the lines. Accordingly, it is not necessary for the source code of the common message handling control to be repeated in each software module, although it is necessary that each software module that accesses the control and the control itself be under the control of a common operating system. Moreover, it will be appreciated that the SILAS.RequestMsg reference is operable to update the routing table to indicate that the added module should receive messages having a message attributes that match the message attributes defined by the “EveryMessage” message type. In the above example, where all *'s are used as message attributes for the EveryMessage translation name, every future message will match the “EveryMessage” message type, so the Router will send every message to this logging module. Accordingly, it will be appreciated that the message attributes of a translation name specify a filter condition against which the Router compares each message to determine the modules to which each message should be sent. As noted above, a module may use the Router.RequestMsg(TRANSLATIONNAME) message to request that the Router send the module future messages whose message attributes match the message attributes of the translation name specified in the RequestMsg message.

[1200] It will further be appreciated that the present invention provides software messaging control means for dynamically defining and building a message according to a common message format, as shown, for example, by the use of the AddString method described above, wherein data element names and values are supplied to the common messaging control. Moreover, the present invention provides software messaging control means for receiving, from the software module in which the software messaging control it is included, a data element name for data contained in a received message, and means for parsing the received message and providing the software module with the data corresponding to the data element name. Examples of this are the invocation of the GetString and GetSubmsg methods shown above. Because the GetString and GetSubmsg methods can retrieve message contents by keys, the retrieval of these message contents does not require the programmer to know the sequence of the of the desired message data element within the entire message.

[1201] Although a specific embodiment of the invention has been disclosed with reference to a preferred embodiment, it will be understood by those of skill in the art that changes in form and details may be made without departing from the spirit and scope of the invention. The present invention is in no way limited to the details disclosed herein. Accordingly, the present invention is to be defined and limited solely by the scope of the claims.

[1202] For example, while a software system may include modules that utilize a common message handling control to exchange messages, it is not required that each and every module in the system use the control. For example, there may be one or more groups of software modules that, in operation, are executed with higher frequency than other software modules. Because the message handling system described herein adds some amount of processing overhead, it may be appropriate to utilize conventional, direct addressed messaging techniques for these modules, instead of the disclosed message handling system. Furthermore, many commercial software system a built using third-party software components. Often, such pre-existing components will not be configured by the manufacturer to utilize the message handling system disclosed herein. Such systems are not precluded from being within the scope of the claims.