iNTERFACEWARE™ Inc.

Parsing a Message

The ParseMessage method of the application Engine should be invoked to parse a message. If it successfully recognizes and parses a message, it will invoke one of the OnMessage events. If not, it will throw a ChameleonException. The following code shows an example of how this API can be invoked:

private void TestMessage()
{
   try
   {
      Println("Testing...");
      string message;
      
      //Load an HL7 message into the string Message.
      //Note the use of a double \\ to escape the \ character at the start of the message 
      //and the use of \r at the end of each segment.
      message += "MSH|^~\\&|REGADT|MCM|RSP1P8|MCM|199601051530|SEC|ADT^A44|00000007|P|2.3\r"; 
      message += "EVN|A44|199601051530\r"; 
      message += "PID|||MR2^^^XYZ||JONES^WILLIAM^A^JR||19501010|M|||123 EAST\r"; 
      message += "STREET^^NY^NY^10021||(212)111-3333|||S||ACCT1\r";
      message += "MRG|MR1^^^XYZ||ACCT1\r" ;
      
      m_Engine.ParseMessage(message, null); 
   }
   catch (ChameleonException ex) 
   {
      Println(ex.ToString() + " while trying to parse message.");
   }
} 

This diagram gives the call sequence which is invoked assuming the user has chosen to name the application Engine class 'ServerEngine':

Parsing Call Sequence

• An object invokes ParseMessage method on the ServerEngine.
• The ServerEngine may have an implementation of this method if the user has chosen to override it for error handling and/or logging purposes (see below). After this, the call passes up the chain to the parent stubcode class HL7Engine.
• HL7Engine.ParseMessage invokes the Parse method of its parent Engine object.
• This method invokes the core Chameleon engine. If a parsing error is found an exception is thrown. If not, a table and message index is returned.
• HL7Engine.ParseMessage uses that message index to construct the appropriate message object and call the On<message name>Message handler.
• At this point, the ServerEngine object now takes over. The user is responsible for creating these On<message name>Message handlers.
• These user applications may use the Transport interface to return a result ACK message, or query result to the sender.

The following code fragment gives an idea of what a typical On<message name>Message virtual method would look like when the user performs an override in the ServerEngine class:

public override void OnPatientAdmitMessage
(
   PatientAdmitMessage message,
   Transport aTransport
)
{
   Println("Sending application = " + message.Header(0).SendingApplication());
   Println("Receiving application = " + message.Header(0).ReceivingApplication());
   // ...process message here 
}

Overriding the ParseMessage Method

There are many times that it's helpful to override the ParseMessage method in an application. Some good reasons are:

• Logging each incoming message before parsing it.
• Error handling, exceptions can be caught in a central place for uniform handling.

The following code fragment shows an example of how you might go about overriding the ParseMessage method in an application engine object:

public override void ParseMessage(string flatwire, Transport aTransport)
{
   try
   {
      // Additional logging could be performed here.
      Println("Parsing message...");
      Println(flatwire);
      base.ParseMessage(flatwire, aTransport);
   }
   catch (Exception ex)
   {
      Println("Error: " + ex.ToString());
      try
      {
          MakeReturnACK(aTransport, "UNKNOWN");
      }
      catch (Exception aException)
      {
         Println("Couldn't make NACK message." + aException.ToString());
      }
   }
}

Overriding ParseMessage