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 = Message + "EVN|A44|199601051530\r"; 
      Message = Message + "PID|||MR2^^^XYZ||JONES^WILLIAM^A^JR||19501010|M|||123 EAST\r"; 
      Message = Message + "STREET^^NY^NY^10021||(212)111-3333|||S||ACCT1\r";
      Message = Message + "MRG|MR1^^^XYZ||ACCT1\r" ;
      
      m_Engine.parseMessage(Message, null); 
   }
   catch (ChameleonException Error) 
   {
      println(Error.toString() + " while trying to generate message.");
   }
} 

This diagram gives the call sequence which is invoked, assuming that the user has chosen to name the application Engine class 'ServerEngine', click on each section for descriptions:

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 it's 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.
• The use of Transport interface is deprecated since the networking components we supply do not rely on it.

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

public void onPatientAdmitMessage
(
   PatientAdmitMessage Message,
   Transport ATransport
) throws ChameleonException
{
   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 void parseMessage(String Flatwire, Transport ATransport)
{
   try
   {
      // Additional logging could be performed here.
      println("Parsing message...");
      println(Flatwire);
      super.parseMessage(Flatwire, ATransport);
   }
   catch (Exception Error)
   {
      println("Error: " + Error.toString());
      try
      {
          makeReturnACK(ATransport, "UNKNOWN");
      }
      catch (Exception AException)
      {
         println("Couldn't make NACK message." + AException.toString());
      }
   }
}

Overriding parseMessage