Software messaging system6668284Abstract A software architecture includes a router that receives all messages from modules in a software system. Each message is associated with one of several pre-defined message translations, including message attributes, which are maintained by a Keeper database. Individual modules may send messages to the Router requesting that they receive messages having message attributes that match specified criteria. A common messaging control is encodes each message according to a hierarchical format so that any module receiving a message can decode the message and receive data elements from it without knowledge of the precise structure or sequence of data elements in the message. Claims What is claimed is: Description FIELD OF THE INVENTION
translation = message : message : message : message : message
name attribute attribute attribute attribute attribute
1 2 3 4 5
For example: <Translation Name>=<To Name>:<To Type>:<From Name>:<From Type>:<Msg Type> 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). 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. %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. 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. 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. The Messaging Control 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. In one embodiment, the naming of modules, keys and message translations are limited in the following ways: Module names and module types may contain any character except .backslash. (backslash), null, .vertline. (vertical bar), #, carriage return, or linefeed, but they may not be the single character * (asterisk). In addition, they may not begin with % (percent sign). Keys may contain any character except null, .vertline. (vertical bar), .backslash. (backslash), carriage return, and linefeed. In addition, only system defined keys may begin with a % sign (this is a convention). Message translation names may contain any character except null, .vertline. (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. In general, the characters to avoid are: .backslash., null, .vertline., #, %, carriage return, linefeed, and *. 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. 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. 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. System keys exist off of the root of messages and are named starting with a % (percent sign). 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. 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.). 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. Programming Examples 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". Registering 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. Delphi Example {The first command line parameter is ParamStr(1) in Delphi then call RegisterModule} SILAS.RegisterModule(ParamStr(1),`Device`); Visual Basic Example `Get the entire command line with the Command$ function in VB. CmdLn$=Command$ `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. Function ParseCommand(tokenNum As Integer, cmd$) As String Dim i, tokN As Integer Dim c$, tok$ i=1: tokN=0: c$="": tok$ ="" While i<=Len(cmd$) c$=Mid(cmd$, i, 1) While c$<>"" And c$<>vbTab And i<=Len(cmd$) tok$ =tok$ & c$ i=i+1 c$=Mid(cmd$, i, 1) Wend tokN=tokN+1 If tokN=tokenNum Then ParseCommand=tok$ Exit Function Else tok$="" i=i+1 End If Wend ParseCommand="" End Function `Call ParseCommand to get first parameter, then register with it SILAS.RegisterModule(ParseCommand(1, CmdLn$), "Device"). 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. 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. Requesting and Ignoring Messages 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: Delphi Example if SILAS.RequestMsg(`Data`)>0 then {The message translations in the registry must be messed up--fatal error} Similarly, once you no longer want a particular message one needs to tell the Messaging Control OCX to ignore it: if SILAS.IgnoreMsg(`Data`)>0 then {The message translations in the registry must be messed up--fatal error} Visual Basic Example If SILAS.RequestMsg("Data")>0 Then `The message translations in the registry must be messed up--`fatal error Similarly, once you no longer want a particular message one needs to tell the Messaging Control OCX to ignore it: If SILAS.IgnoreMsg("Data")>0 Then `The message translations in the registry must be messed up--`fatal error 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. Receiving a Message Once a module has requested a message, the RcvMsg event may fire at any time to inform the module that a message has arrived: Delphi Example procedure TfrmMain.RcvMsg(Sender: TObject; const sMsgName: string); begin {Find out what kind of message it is} if sMsgName=`Existence Query` then begin . . . {do something with it} end else if sMsgName=`Data` then . . . end; Visual Basic Example Private Sub SILAS_RcvMsg(ByVal sMsgName As String) `Find out what kind of message it is If sMsgName="Existence Query" Then . . . `do something with it Elself sMsgName="Data" Then . . . End If End Sub Getting Strings from the Current Message All data in a message is retrieved by providing a key that identifies it: Delphi Example {Get the command name from the current message (identified by 0)} sCommandName:=SILAS.GetString(0,`Command Name`); if sCommandName=`Read` then {Perform the read} Visual Basic Example `Get the command name from the current message (identified by 0) sCommandName=SILAS.GetString(0, "Command Name") If sCommandName="Read" Then `Perform the read 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. Saving Messages It is often useful to be able to save a message for later use (usually to reply to it): In Delphi: ISavedMessage:=SILAS.SaveCurrentMsg( ); In Visual Basic: ISavedMessage=SILAS.SaveCurrentMsg 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: In Delphi: sCommandName:=SILAS.GetString(ISavedMessage,`Command Name`); In Visual Basic: sCommandName=SILAS.GetString(ISavedMessage, "Command Name") Working with Sub-messages 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: In Delphi: ISubmessage:=SILAS.GetSubmsg(0,`Parameters`); In Visual Basic: ISubmessage =SILAS.GetSubmsg(0, "Parameters") Once a sub-message is gotten, one may simply treat it like any other message, for example: In Delphi: sCommand:=SILAS.GetString(ISubmessage,`Command Name`); In Visual Basic: sCommand =SILAS.GetString(ISubmessage, "Command Name") If there are multiple levels of sub-messages, one needs to get each in turn; for instance, consider a message structured like so: If one wanted to get the Wavelength parameter for Read Two, one would do this: Delphi Example IparamMsg:=SILAS.GetSubmsg(0,`Parameters`); IReadTwo:=SILAS.GetSubmsg(IParamMsg,`Read Two`); sReadTwoWavelength:=SILAS.GetString(IReadTwo,`Wavelength`); Visual Basic Example IparamMsg=SILAS.GetSubmsg(0, "Parameters") IReadTwo =SILAS.GetSubmsg(IParamMsg, "Read Two") sReadTwoWavelength=SILAS.GetString(IReadTwo, "Wavelength") 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: In Delphi: ISavedSubMsg:=SILAS.CreateMsg( ); SILAS.CopyAll(SILAS.GetSubmsg(0,`Parameters`), ISavedSubMsg); In Visual Basic: ISavedSubMsg=SILAS.CreateMsg SILAS.CopyAll SILAS.GetSubmsg(0, "Parameters"), ISavedSubMsg Building and Sending Messages 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): Delphi Example {create a new message} IOutMsg:=SILAS.CreateMsg( ); {add the Command key with the string "Read" as the command} SILAS.AddString(IOutMsg, `Command`,`Read`); {Create the Parameters sub-message} IParamsMsg:=SILAS.AddSubmsg(IOutMsg, `Parameters`); {create Read One sub-message} IReadOne:=SILAS.AddSubmsg(IParamsMsg,`Read One`); {Add data to Read One} SILAS.AddString(IReadOne,`Wavelength`,`450`); SILAS.AddString(IReadOne,`Dispense`,`False`); {create Read Two sub-message} IReadTwo:=SILAS.AddSubmsg(IParamsMsg,`Read Two`,`True`); {Add data to Read Two} SILAS.AddString(IReadTwo,`Wavelength`,`950`); SILAS.AddString(IReadTwo,`Dispense?`,`True`); Visual Basic Example `create a new message IOutMsg =SILAS.CreateMsg `add the Command key with the string "Read" as the command SILAS.AddString IOutMsg, "Command", "Read" `Create the Parameters sub-message IParamsMsg =SILAS.AddSubmsg(IOutMsg, "Parameters") `create Read One sub-message IReadOne =SILAS.AddSubmsg(IParamsMsg, "Read One") `Add data to Read One} SILAS.AddString IReadOne, "Wavelength", "450" SILAS.AddString IReadOne,"Dispense", "False" `create Read Two sub-message IReadTwo =SILAS.AddSubmsg(IParamsMsg, "Read Two", "True") `Add data to Read Two SILAS.AddString IReadTwo, "Wavelength", "950" SILAS.AddString IReadTwo,"Dispense?", "True" 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): In Delphi: SILAS.SendMsgTo(IOutMsg,`Command`,`SMax`); In Visual Basic: SILAS.SendMsgTo IOutMsg, "Command", "Smax" 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. 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). 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: Delphi Example procedure TfrmMain.SilasRcvMsg(Sender: TObject; const sMsgName: string); var IOutMsg, ICommand: integer; begin {Find out what kind of message it is, i.e., which translation it first matches from the Keeper (remember bottom-up matching)} if sMsgName =`Existence Query` then begin {build a reply message that will be automagicly deleted} IOutMsg:=SILAS.CreateMsgToSend( ); {Reply using 0 to specify the current message} SILAS.SendReply(IOutMsg, `Existence Query Reply`,0) end else if sMsgName=`Command` then {it's a command--save it so we can reply when we're done} ICommand:=SILAS.SaveCurrentMsg( ); . . . {finish looking for names we care about} . . . {finish doing whatever else this module may need to do} {After finishing the command, send a reply} SILAS.SendReply(IOutMsg, `Command Reply`, ICommand); {delete the command message} SILAS.DeleteMsg(ICommand); end; Visual Basic Example Private Sub SILAS_RcvMsg(ByVal sMsgName As String) Dim IOutMsg As Integer, ICommand As Integer `Find out what kind of message it is, i.e., which translation it `first matches from the Keeper (remember bottom-up matching) If sMsgName="Existence Query" Then `build a reply message that will be automagicly deleted IOutMsg=SILAS.CreateMsgToSend `Reply using 0 to specify the current message SILAS.SendReply IOutMsg, "Existence Query Reply", 0 Elself sMsgName="Command" Then `it's a command--save it so we can reply when we're done ICommand=SILAS.SaveCurrentMsg . . . `finish looking for names we care about End If . . . `finish doing whatever else this module may need to do `After finishing the command, send a reply SILAS.SendReply IOutMsg, "Command Reply", ICommand `delete the command message SILAS.DeleteMsg ICommand End Sub Re-using Messages 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: Delphi Example {Copy the whole current message to the outgoing message} SILAS.CopyAll(0, IOutMsg); {Copy a sub-message to the root of the outgoing message} SILAS.CopyAll(ISubMsg, IOutMsg); {Copy a single key from one message to another} SILAS.CopyTo(ISavedMsg, `Command`, IOutSubmsg, `Command`); Visual Basic Example `Copy the whole current message to the outgoing message SILAS.CopyAll 0, IOutMsg `Copy a sub-message to the root of the outgoing message SILAS.CopyAll ISubMsg, IOutMsg `Copy a single key from one message to another} SILAS.CopyTo ISavedMsg, "Command", IOutSubmsg, "Command" 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. Enumeration 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. Delphi Example IPos:=SILAS.GetFirstStringPosition(0); while IPos < >0 do begin sKey:=SILAS.GetNextStringKey(0, IPos); // IPos is updated here . . . // do something with the key end; IPos:=SILAS.GetFirstSubmsgPosition(0); while IPos < >0 do begin sKey:=SILAS.GetNextSubmsgKey(0, IPos); // IPos is updated here . . . // do something with the key end; If you wanted to get all of the strings from a message, you could do something like this: IPos:=SILAS.GetFirstStringPosition(0); while IPos < >0 do begin sKey:=SILAS.GetNextStringKey(0, IPos); sAllStrings:=sAllStrings+SILAS.GetString(0, sKey); end; ISubMsgPos:=SILAS.GetFirstSubmsgPosition(0) while ISubMsgPos < >0 do begin sSubMsgKey:=SILAS.GetNextSubmsgKey(0, ISubMsgPos); ISubMsgKey:=SILAS.GetSubmsg(0, sSubMsgKey); IPos:=SILAS.GetFirstStringPosition(ISubMsgKey); while IPos < >0 do begin sKey:=SILAS.GetNextStringKey(ISubMsgKey, IPos); sAllStrings:=sAlIStrings+SILAS.GetString(ISubMsgKey, sKey); end; end; Visual Basic Example IPos=SILAS.GetFirstStringPosition(0) While IPos < >0 sKey:=SILAS.GetNextStringKey(0, IPos) `IPos is updated here . . . `do something with the key Wend IPos=SILAS.GetFirstSubmsgPosition(0) While IPos < >0 sKey=SILAS.GetNextSubmsgKey(0, IPos) `IPos is updated here . . . `do something with the key Wend If you wanted to get all of the strings from a message, you could do something like this: IPos=SILAS.GetFirstStringPosition(0) While IPos < >0 sKey=SILAS.GetNextStringKey(0, IPos) sAllStrings=sAllStrings & SILAS.GetString(0, sKey) Wend ISubMsgPos=SILAS.GetFirstSubmsgPosition(0) While ISubMsgPos < >0 sSubMsgKey=SILAS.GetNextSubmsgKey(0, ISubMsgPos) ISubMsgKey=SILAS.GetSubmsg(0, sSubMsgKey) IPos=SILAS.GetFirstStringPosition(ISubMsgKey) While IPos < >0 sKey=SILAS.GetNextStringKey(ISubMsgKey, IPos) sAllStrings=sAliStrings & SILAS.GetString(ISubMsgKey, sKey) Wend Wend Confirming Delivery 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: Delphi Example {Confirm delivery} SILAS.bConfirmDelivery:=True; {Send message--check return value; if nonzero, we timed out waiting for the return receipt (or some other error occurred)} if SILAS.SendMsg(IMsgId,`SMax-Command`) < >0 then {The SMax module must be dead!} else {bConfirmDelivery has been automatically reset to false--we will not wait for a return receipt on this send} SILAS.SendMsg(`Status`); Visual Basic Example `Confirm delivery SILAS.bConfirmDelivery=True `Send message--check return value; if nonzero, we timed out `waiting for the return receipt (or some other error occurred) If SILAS.SendMsg(lMsgid, "SMax-Command") < >0 Then `The SMax module must be dead! Else `bConfirmDelivery has been automatically reset to false--we `will not wait for a return receipt on this send SILAS.SendMsg "Status" End If 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. 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: 7.22. if sMsgName=`Command To Me` then begin SILAS.SendDeliveryConfirmation(0); . . . end else if sMsgName=`Commands for someone else` then // do not send the delivery confirmation here begin . . . end else if sMsgName=`Existence Query` then begin SILAS.SendDeliveryConfirmation(0); SILAS.SendReply(SILAS.CreateMsgToSend, `Existence Query Reply`,0); end; Visual Basic Example If sMsgName="Command To Me" Then SILAS.SendDeliveryConfirmation 0 . . . Elself sMsgName="Commands for someone else" Then `do not send the delivery confirmation here . . . Elself sMsgName="Existence Query" Then SILAS.SendDeliveryConfirmation 0 SILAS.SendReply(SILAS.CreateMsgToSend, _"Existence Query Reply", 0) End If Errors and Exceptions 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. Delphi Example try SILAS.SendMsg(IMsg, `Non-existent Translation`); except On xE : Exception do MessageDlg(`Error encountered:`+xE.Message,mtError,[mbOK],0); end; {end of subroutine} Visual Basic Example On Error Goto ErrorHandler SILAS.SendMsg IMsg, "Non-existent Translation" Exit Sub ErrorHandler: SilasMsgBox.SilasMsgBox "Error encountered:" & Str(Err.Number)_& " generated by " & Err.Source & vbCrLf & Err.Description,_vbOkOnly, "Error" End Sub Translations 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. Delphi Example SILAS.bRetrieveTranslations:=False; SILAS. RegisterModule(`AllWatcher`, `Watcher`); . . . procedure OnSilasInitialized(Sender: Tobject; ISuccess: integer) begin // add the command translation SILAS.AddTranslation(`Command`, `*`, `*`, `*`, `*`, `Command`); // add the status and data translations--use a string // formatted as in the %Messaging branches of the keeper SILAS.AddTranslations(`Status=*:*:*:*:Status`+#13#10+`Data=*:*:*:*:Data`) . . . end; Visual Basic Example SILAS.bRetrieveTranslations=False SILAS.RegisterModule "AllWatcher", "Watcher" . . . Private Sub SILAS_lnitialized(ByVal ISuccess As Long) `add the command translation SILAS.AddTranslation "Command", "*", "*", "*", "*", "Command" `add the status and data translations--use a string `formatted as in the %Messaging branches of the keeper SILAS.AddTranslations "Status=*:*:*:*:Status" & vbCrLf & _"Data=*:*:*:*:Data" . . . End Sub 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: Delphi Example if SILAS.TranslationExists(`Command`)=0 then {raise custom exception (assumed to be already defined)} Raise EMissingTranslation.Create(`Translation Command is missing.`); Visual Basic Example If SILAS.TranslationExists("Command")=0 Then `raise raw exception (could define an exception creator) Err.Raise 1001, App.Title, "Translation Command is missing." Addressing Information 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). The address components are found under the following keys under the %Address sub-message (no spaces between words): ToName, ToType, FromName, FromType, and MsgType Streaming Messages (e.g. file I/O) 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. Delphi Example To write a message to a stream, use code similar to the following: procedure WriteMsg(Stream: TStream; nMsg: integer); var vCodeMsg: variant; nCodeMsgSize: integer; pVarBuffer: pointer; begin // get the message as a variant vCodeMsg:=SILAS.GetMsgAsStringV(nMsg); // get the size and put it into the stream first nCodeMsgSize:=VarArrayHighBound(vCodeMsg, 1)-VarArrayLowBound(vCodeMsg, 1)+1; pVarBuffer:=VarArrayLock(vCodeMsg); WriteInteger(Stream, nCodeMsgSize); // write out the message and clean up Stream.WriteBuffer(pVarBuffer , nCodeMsgSize); VarArrayUnlock(vCodeMsg); VarClear(vCodeMsg); end; To read a message in, use code similar to the following: function ReadMsg(Stream: TStream): integer; var nSize: integer; vMSg: variant; pVarBuffer: pointer; begin // get the message size ReadInteger(Stream, nsize); if nSize < >0 then begin // make an array of the appropriate size vMsg:=VarArrayCreate([0, nSize-1],varByte); pVarBuffer:=VarArrayLock(vMsg); // read the message into the buffer Stream.ReadBuffer(pVarBuffer , nsize); VarArrayUnlock(vMsg); // pass the buffer to SILAS Result:=SILAS.LoadMsgFromStringV(vMsg); VarClear(vMsg); end else Result:=-1; end; Visual Basic Example 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. To write a message to a file, code similar to the following may be used: Public Sub WriteMsg(File As String, nMsg As Long) Dim pFile As Integer, Location As Integer Dim vCodeMsg( ) As Byte `Get a free file pointer and open the file pFile=FreeFile: Open File For Binary As pFile `Read message as a string (byte array) vCodeMsg=SILAS.GetMsgAsStringV(nMsg) `Loop through the entire array, putting each byte into the file For Location=LBound(vCodeMsg) To UBound(vCodeMsg) Put pFile, vCodeMsg(Location) Next Location Close pFile `Close the file End Sub To read a message in from a file, use code similar to the following: Public Function ReadMsg(File As String) As Long Dim pFile As Integer, Location As Integer, Char As Byte Dim MsgByteArray( ) As Byte `Get a free file pointer and open the file pFile=FreeFile: Open File For Binary As pFile `Initialize variables, assuming 0-based array indexing Location=0: Char=255 `While we're not at the end of the file . . . While Location <LOF(pFile) `Get the next byte (auto-updates file position) Get pFile, Char `Make room for the new byte in the array ReDim Preserve MsgByteArray(Location +1) `Put the byte into the array MsgByteArray(Location)=Char `Update the index to match position in the file Location=Loc(pFile) Wend Close pFile `Close the file `load message into SILAS and return the message number ReadMsg=SILAS.LoadMsgFromStringV(MsgByteArray( )) End Function Explanation of Prototypes Events and methods presented below are pseudocode prototypes. The format is: <return-type><name>(<parameter-type><parameter>, . . . ) The types and their language-dependent forms are summarized in the table below:
Pseudocode Delphi VB
Type Type Type
string string String
integer integer Integer
long integer Long
long* pointer Long
variant variant Variant OR
Array
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). Events RcvMsg RcvMsg(String sMsgName) Purpose 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. Parameters
sMsgName The name of the message that just arrived. Corresponds
to the name on the left side of a message translation.
Initialized Initialized(long ISuccess) Purpose After a module calls RegisterModule and the OCX finishes initializing, this event will fire. Note: No other SILAS interaction should take place until this event has fired. Parameters
LSuccess Indicates whether the module has successfully
initialized or has failed to initialize.
when < 0 an error has occurred
when = 0, the module has been initialized
correctly
Properties 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 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. bAutoResetConfirmationOnSend--Run-Time Only When this property is True, the OCX will automatically set the bConfirmDelivery property to False after a message is sent. Defaults to True. bConfirmDelivery--Run-Time Only When this property is True the OCX will automatically request and wait for a return receipt when you send a message. Defaults to False. iConfirmTimeout This property determines how long the OCX will wait for a return receipt in seconds. Defaults to 15. bRetrieveTranslations--Run-Time Only When True, the OCX automatically retrieves its translations from the Keeper. Defaults to True. bRaiseExceptions--Run-Time Only 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. bRaiseFatalExceptions--Run-Time Only 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. bRaiseRareExceptions--Run-Time Only 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. Methods AddString long AddString(long IMsgID, string sKey, string sData) Purpose This method adds a string to the given message under the given key. Parameters
IMsgID Indicates the message to add a string to
sKey The key to the string
sData The string to add
Return Value Nonzero on failure, 0 on success. AddStringV long AddStringV(long IMsgID, string sKey, variant vString) Purpose 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). Parameters
IMsgID Indicates the message to add a string to
sKey The key to the string
vString The data to add. Must be a variant array of bytes
(VT_UI1)
Return Value Nonzero on failure, 0 on success. AddSubmsg long AddSubmsg(long IMsgID, string sKey) Purpose 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. Parameters
LmsgID Indicates which message to add to
Skey Indicates what key to put the new sub-message under
Return Value A number>0 to be used to refer to the message on success; Negative on failure. AddTranslation long AddTranslation(string sTranslationName, string sToName, string sToType, string sFromName, string sFromType, string sMsgType); Purpose 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) Parameters
sTranslationName The name to be used to refer to the translation.
sToName Name of the addressee
sToType Type of the addressee
sFromName Name of the sender
sFromType Type of the sender
sMsgType The type of message
Return Value `Nonzero on failure, 0 on success. AddTranslations long AddTranslations(string sTranslations) Purpose 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 Parameters
sTranslations The translations to add in the same format as found in
the % Messaging branches of the Keeper.
Return Value Nonzero on failure, 0 on success. AddUniqueString long AddUniqueString(long IMsgID, string sKey, string sData) Purpose 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. Parameters
IMsgID Indicates the message to add a string to
sKey The key to the string
sData The string to add
Return Value Nonzero on failure, 0 on success. AddUniqueSubmsg long AddUniqueSubmsg(long IMsgID, string sKey) Purpose 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. Parameters
IMsgID Indicates which message to add to
sKey Indicates what key to put the new sub-message under
Return Value A number >0 to be used to refer to the message on success; Negative on failure. CreateMsg long CreateMsg( ) Purpose This method creates a new, blank message. Parameters None. Return Value A number >0 to be used to refer to the message on success; Negative on failure. CreateMsgToSend long CreateMsgToSend( ) Purpose This method creates a new, blank message. This message will be automatically deleted by the OCX once it is sent. Parameters None. Return Value A number >0 to be used to refer to the message on success; Negative on failure. CopyAll long CopyAll(long IFromID, long IToID) Purpose This method copies the full contents (including sub-messages) of one message to another. Parameters
IFromID Indicates which message to copy from
IToID Indicates which message to copy to
Return Value Nonzero on failure, 0 on success. CopyKey long CopyKey(long IFromID, string sKey, long ITOID, string sNewKey) Purpose 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. Parameters
IFromID Indicates which message to copy from
sKey The key to copy
IToID Indicates which message to copy to
sNewKey Indicates what key to put the data into.
Return Value Nonzero on failure, 0 on success. CopyMsgToKey long CopyMsgToKey(long IMsgID, long IToID, string sNewKey) Purpose This method copies the given message to a key under another message. Parameters
IMsgID Indicates which message to copy from
IToID Indicates which message to copy to
sNewKey Indicates what key to put the data into.
Return Value Nonzero on failure, 0 on success. DeleteMsg long DeleteMsg(long IMsgID) Purpose 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. Properties
IMsgID Indicates the message to delete.
Should not refer to a sub-message
Return Value Nonzero on failure, 0 on success. GetErrorText string GetErrorText(long IErrorID) Purpose This method retrieves the error text associated with a given error ID. GetFirstStringPosition long GetFirstStringPosition(long IMsgID) Purpose 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. Parameters
IMsgID Indicates which message to enumerate.
Return Value 0 on failure or if there are no strings. Nonzero on success. GetFirstSubmsgPosition long GetFirstSubmsgPosition(long IMsgID) Purpose 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. Parameters
IMsgID Indicates which message to enumerate.
Return Value 0 on failure or if there are no submsgs. Nonzero on success. GetNextStringKey string GetNextStringKey(long IMsgID, long* IpEnumPosition) Purpose 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. Parameters
IMsgID Indicates which message to get a key from.
IpEnumPosition Points to the position variable that refers
to the key to get. This variable will be
updated to refer to the next key when this
method returns successfully. If there are
no more keys, it will be set to 0.
Return Value The key on success; an empty string on error. GetNextSubmsgKey string GetNextSubmsgKey(long IMsgID, long* IpEnumPosition) Purpose 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. Parameters
IMsgID Indicates which message to get a key from.
IpEnumPosition Points to the position variable that refers
to the key to get. This variable will be
updated to refer to the next key when this
method returns successfully. If there are
no more keys, then this variable will be set
to 0.
Return Value The key on success; an empty string on error. GetMsgAsStringV variant GetMsgAsStringV(Iong IMsgID) Purpose 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. Parameters
IMsgID A number indicating which message to get.
Return Value The data on success; an empty variant on failure. GetParentMsg long GetParentMsg (long IMsgID, long pIParentID) Purpose This method returns the ID of the parent of the given message in the parameter pIParentID. Parameters
IMsgID A number indicating which message to get the parent of.
pIParentID The variable to hold the ID of the parent.
Return Value The 0 on success. Non-zero on failure (e.g. IMsgID is a root message). GetString string GetString(long IMsgID, string sKey) Purpose This method retrieves a string from a message. Parameters
IMsgID A number indicating which message to get the string
from.
0 = the current message
sKey Indicates which string to get.
Return Value The data on success; an empty string on failure. GetStringV variant GetStringV(long IMsgID, string sKey) Purpose This method retrieves a string from a message in the form of a variant array of bytes. Parameters
IMsgID A number indicating which message to get the string
from.
0 = the current message
sKey Indicates which string to get.
Return Value The data on success; an empty variant on failure. GetSubmsg long GetSubmsg(long IMsgID, string sKey) Purpose 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. Parameters
IMsgID Indicates which message to retrieve from
sKey Indicates what key to get the sub-message from
Return Value A number >0 to be used to refer to the message on success; Negative on failure . . . IgnoreMsg long IgnoreMsg(string sMsgName) Purpose This method turns off reception of the specified message. Parameters
sMsgName Indicates which kind of message to stop receiving.
Return Value Nonzero on failure, 0 on success. LoadMsgFromStringV long LoadMsgFromStringV(variant vMsg) Purpose 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. Parameters
vMsg Contains the data returned previously by
GetMsgAsStringV.
Return Value A number >0 to be used to refer to the loaded message on success; Negative on failure. ReadMsgFromFile long ReadMsgFromFile(string sFilePath) Purpose This method loads a message from a given file. The file must have been generated from a call to WriteMsgToFile or GetMsgAsStringV. Parameters
sFilePath Gives the path to the file to load.
Return Value A number >0 to be used to refer to the saved message on success; Negative on failure. RegisterModule long RegisterModule(string sName, string sType) Purpose 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. Parameters
sName The name of the module. Must be unique in the system.
sType The type of the module.
Return Value Nonzero on failure, 0 on success. RemoveKey long RemoveKey(long IMsgID, string sKey) Purpose This method removes a key from a saved message; the key can specify a sub-message or a string. Parameters
IMsgID Indicates which message to remove the key from.
sKey Indicates which key (and its associated data) to remove.
Return Value Nonzero on failure, 0 on success. RequestMsg long RequestMsg(string sMsgName) Purpose This method requests that the given kind of message be sent to the module. Parameters
sMsgName The name of the message to request
Return Value Nonzero on failure, 0 on success. SaveCurrentMsg long SaveCurrentMsg( ) Purpose 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. Return Value A number >0 to be used to refer to the message on success; Negative on failure. SendDeliveryConfirmation long SendDeliveryConfirmation(long IMsgID) Purpose This method will send a delivery confirmation message in response to the given message if necessary (i.e., the message has a %Return field). Parameters
IMsgID Identifies the message for which a delivery
confirmation should be sent.
Return Value Nonzero on failure, 0 on success. SendMsg long SendMsg(long IMsgID, string sMsgName) Purpose 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. Parameters
IMsgID Identifies the message being sent.
sMsgName The name of the address to put on the message
Return Value Nonzero on failure, 0 on success. SendMsgTo long SendMsgTo(long IMsgID, string sMsgName, string sToName) Purpose 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. Parameters
IMsgID Identifies the message being sent.
sMsgName The name of the address to put on the message
sToName The name of the module that the message is meant for.
This value is inserted into the ToName field of the
message address.
Return Value Nonzero on failure, 0 on success. SendReply long SendReply(long IMsgID, string sMsgName, long ISavedID) Purpose 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). Parameters
IMsgID Identifies the message being sent.
sMsgName The name of the address to put on the message
ISavedID The message that the outgoing message
is in reply to.
Return Value Nonzero on failure, 0 on success. String Exists long StringExists(long IMsgID, string sKey) Purpose 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) Parameters
IMsgID Indicates which message to check under
sKey Indicates what key you are checking
the existence of.
Return Value Returns 1 if the string was found. Retruns 0 if the string was not found. Returns negative number on error. Translation Exists long TranslationExists(string sTranslationName); Purpose 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. Parameters
sTranslationName Indicates what translation to check for.
Return Value 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. UnregisterModule long UnregisterModule( ) Purpose This method unregisters the module. After this method is called, the module will not receive messages. Return Value Nonzero on failure, 0 on success. WaitFor long WaitFor(string sMsgName, integer ITimeout) Purpose 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). 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. 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. Parameters
sMsgName The name of the message to wait for.
ITimeout The maximum number of seconds to wait
for the message.
Return Value 0 if the message was received, 1 if it was not. Returns a negative value if the message name is invalid. WriteMsgToFile long WriteMsgToFile(long IMsgID, string sFilePath) Purpose This method writes a message to a given file. Parameters
IMsgID The ID of the message to write out.
sFilePath Gives the path to the file to load.
Return Value 0 on success, negative on failure. Error Codes
Constant Code Meaning
Common Errors
ERR_MSG_DOES.sub.-- -1 The message ID given does not
NOT_EXIST exist.
ERR_MSG2.sub.-- -2 The seconds message ID
DOES_NOT.sub.-- given does not exist.
EXIST
ERR_SUBMSG.sub.-- -3 No sub-message exists
DOES_NOT.sub.-- under the given key.
EXIST
ERR_MESSAGE.sub.-- -4 The given message has no parent
HAS_NO_PARENT message; it's a root message.
ERR_MODULE.sub.-- -5 The name that you tried to register
NAME_IN_USE under is in use by another module.
Rare Errors
ERR_CANT.sub.-- -1000 An attempt was made to call
DELETE_NON- DeleteMsg on a non-root
ROOT_MSGS message. RemoveKey should be
used to get rid of sub-messages.
ERR_TRANSLA- -1001 The given translation name does
TION_NOT.sub.-- not exist in the current
FOUND set of translations.
NOTE: Case matters!
ERR_NO.sub.-- -1002 An attempt was made to save the
CURRENT_MSG current message when there was
none.
ERR_ALREADY.sub.-- -1003 An attempt was made to register
INITIALIZED while the module was already
registered.
ERR_NOT.sub.-- -1004 An attempt was made to execute
REGISTERED a method that requires
registration before the module
has registered.
ERR_VARIANT.sub.-- -1005 All variants used by this OCX
SHOULD_BE.sub.-- must be variant arrays of bytes.
A_SAFE_ARRAY It will not attempt to coerce other
types.
ERR_VARIANT.sub.-- -1006 The variant has bad array
INCORRECTLY.sub.-- bounds.
STRUCTURED
ERR.sub.-- -1007 The translation name was not
TRANSLATION.sub.-- found in the translation.
MISSING.sub.--
TRANSLATION.sub.--
NAME
ERR.sub.-- -1008 The ToName field was not found
TRANSLATION.sub.-- in the translation.
MISSING_TONAME
ERR.sub.-- -1009 The ToType field was not found
TRANSLATION.sub.-- in the translation.
MISSING_TOTYPE
ERR.sub.-- -1010 The FromName field was not
TRANSLATION.sub.-- found in the translation.
MISSING_FROM-
NAME
ERR.sub.-- -1011 The FromType field was not
TRANSLATION.sub.-- found in the translation.
MISSING.sub.--
FROMTYPE
ERR.sub.-- -1012 The MsgType field was not found
TRANSLATION.sub.-- in the translation.
MISSING.sub.--
MSGTYPE
ERR_OUT.sub.-- -1013 There is insufficient memory to
OF_MEMORY complete the current operation.
ERR_FILE.sub.-- -1014 The filename given does not
DOES_NOT.sub.-- exist.
EXIST
ERR_UNABLE.sub.-- -1015 Unable to open the given file.
TO_OPEN_FILE
ERR_UNABLE.sub.-- -1016 Unable to read from the given
TO_READ_FILE file.
ERR_UNABLE.sub.-- -1017 Unable to write to the given file.
TO_WRITE_FILE
Fatal Errors
ERR_COULD.sub.-- -2000 Failed to allocate memory for
NOT.sub.-- a new message.
CREATE_MSG
ERR_UNABLE.sub.-- -2001 Unable to find the SILAS
TO_FIND_KERNEL kernel; it may not be loaded.
ERR_UNABLE.sub.-- -2002 Could not create a hidden
TO _CREATE.sub.-- Windows(tm) window. This
WINDOW window is necessary for
communication with the
kernel.
ERR_UNRECOG- -2003 The given message is not of
NIZED_MESSAGE.sub.-- the correct version; it must
VERSION have been created by an older
or newer version of the OCX.
ERR_UNABLE.sub.-- -2004 The given message uses
TO_PARSE.sub.-- characters of a width that the
GIVEN_CHARAC- OCX cannot handle. For
TER_WIDTH example, a Unicode build of
the OCX cannot handle ANSI
messages.
ERR_MESSAGE.sub.-- -2005 The root of the given message
HAS_NO_ROOT was not found; it must be
garbled.
ERR_TRANS- -2006 No translations were found.
LATION_PAR-
SING.sub.--
FAILURE
ERR_UNABLE.sub.-- -2007 Unable to allocate memory for
TO_CREATE.sub.-- transmission of a message.
FILEMAP
ERR_UNABLE.sub.-- -2008 Unable to view allocated
TO_VIEW.sub.-- memory during transmission
FILEMAP of a message.
ERR_NOT.sub.-- -2009 That function is not
IMPLEMENTED implemented.
ERR_ILLEGAL.sub.-- -2010 The name given is not valid;
NAME
ERR_ILLEGAL.sub.-- -2011 The translation field
TRANSLATION.sub.-- given is not valid;
FIELD
Router Description 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. Data Structures Text to Integer Map 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. Message Item 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. Message Description Item Type This field identifies the nature of the Message Item; it can take on the following values: >0 regular message 0 dummy message -1 Request message -2 Ignore Request message Item Filled Event 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. Integer Description 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. String Description 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). Message Content 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). Sender Module 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). Touch Count Records the number of sender threads that still need to "touch" the item. Touch Count Mutex 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. Message Queue 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.fwdarw.head); pointers to the head and tail are maintained. Threads The Router has two different types of threads that work together to carry out routing: Receiver Thread (1) This thread is the primary thread of execution. It handles receiving messages and all registry functions. Registration 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. Message Reception 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. Message Requesting 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. Message Blocking 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. Sender Threads 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. Startup 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. All Messages 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. Regular Messages 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. Request Messages 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. Ignore Request Messages 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. General Operation 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. Messaging Control (OCX) 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. 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. 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: procedure OnSilasMessage(sMessageName: string) begin if sMessageName=`Command` then ReadPlate(0)//0 here identifies the current message else if sMessageName=`Action Config` then ShowActionConfig else if sMessageName=`Unload` then UnloadModule end; 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: SILAS.RequestMsg(`Command`); SILAS.RequestMsg(`Action Config`); SILAS.RequestMsg(`Unload`); Message Format Description 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: Rome.GetString(11,`Wavelength`) The number that is associated with a particular branch is obtained by providing the number identifying its parent and a string key: Rome.GetSubmsg(MsgID, `Parameters`) 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. Internal Representation 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. All of the numbers associated with the nodes are included in an ID.fwdarw.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. 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.fwdarw.String map and the Key.fwdarw.Submessage map. In both cases the key is a string. The submessage map contains pointers to the submessages (nodes) associated with the keys. Node Data:
Field Purpose
pParent Identifies this node's parent node;
NULL for a root node.
mStrings The data at this level of the message
mpChildren The nodes which are children of this node,
as identified by keys.
Enumeration Records the state of the enumerations
State of the strings and submessages.
ID The number that identfies the node. Nodes that
haven't been assigned ID's have a negative
value in this field.
Representation During Transmission 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)): <Node Name>.vertline.<# of Children>.vertline.<Data Length>.vertline.<Node Data> <Node Name>.vertline.<# of Children>.vertline.<Data Length>.vertline.<Node Data> . . . (Note: no CR-LF is included between nodes--it is added here for clarity)
Field Purpose
Node The unicode string key corresponding to
Name the submessage; this will be "Root"
for the root node.
# of The number of children that the node has
Children
Data A Unicode string that represents the number of
Length unicode characters in Node Data. Since there is
no terminator for Node data, this must be used to
determine where the data ends. NOTE: No digit
separators are used (i.e., no commas)
Node Data Holds the strings associated with the node.
Internally "Node Data" is formatted similarly: <Key>.vertline.<String Length>.vertline.<String> <Key>.vertline.<String Length>.vertline.<String> <Key>.vertline.<String Length>.vertline.<String> (Note: no CR-LF is included between key-string pairs--it is added here for clarity)
Field Purpose
Key The key that identifies the string
String A Unicode string that represents the number of
Length unicode characters in "String". Since
there is no terminator for "String",
this must be used to determine where it ends.
NOTE: No digit seperators are used (i.e., no
commas)
String The string associated with the given key
Message Manipulation As noted above, the Messaging Control OCX provides a rich set of methods for manipulating a message. Assigning Numbers 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. 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 31-1)). Creation and Deletion The Current Message 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.fwdarw.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.fwdarw.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). Other Messages 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. String Retrieval 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. String Storage 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. Message Copying 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. Message Deletion 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. Enumeration 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. Message Storage 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. The Interface to the Router Registration 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. Router to OCX 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: [id(1)] void PostMsg(BSTR ToName, BSTR ToType, BSTR FromName, BSTR FromType, BSTR MsgType, BSTR FileMapName, long MapLength); [id(2)] void MsgWanted(BSTR ToName, BSTR ToType, BSTR FromName, BSTR FromType, BSTR MsgType, boolean Wanted); 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). OCX to Router 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. Translations In one embodiment, the Kernel uses a five part address to route messages: ToName, ToType, FromName, FromType, MsgType 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. 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. 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. Message Reception Several technical issues come into play when it comes to how the OCX will process a message and present it to the module. File Maps 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: %%<Module Name><Module Type><counter>.sub.-- 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. OLE Method Calls The Router uses OLE to make method calls on the OCX (PostMsg). These calls can only be made in a blocking mode; this means | ||||||