HL7MessageEncoder
Contents
Class Name: HL7MessageEncoder
Scope: Public - Unrestricted
Factory Creation: Yes - SQLSchemaAPIKey.NewEncoder() method
Used for parsing HL7 messages. You will notice when working with the API that most of the classes and methods that deal with HL7 message data directly will have an optional parameter of type HL7MessageEncoder named preferredEncoder. In the world 99% of the time you can ignore this parameter and let the method or class just do it's thing, and everything will work swimmingly. Until it doesn't.
ANSIEncodingCharacters [String] The ANSI standard HL7 encoding characters ^~\&.
EncodingCharacters [String] The current Encoding Characters: ComponentDelimiter + RepeatDelimiter + EscapeDelimiter + SubComponentDelimiter
DefaultBOM [String] The ANSI default Beginning of Message character - Hex [0B] DefaultEOM [String] The ANSI default End of Message character - Hex [1C-0D] DefaultSegmentDelimiter [String] The ANSI default Segment Delimiter Hex [0D] (A Carriage Return).
DefaultFieldDelimiter [String] The ANSI default Beginning of Message character - | DefaultComponentDelimiter [String] The ANSI default Beginning of Message character - ^ DefaultRepeatDelimiter [String] The ANSI default Beginning of Message character - ~ DefaultEscapeDelimiter [String] The ANSI default Beginning of Message character - \ DefaultSubComponentDelimiter [String] The ANSI default Beginning of Message character - &
|
Public Properties (Read / Write)
BOM [String] The Beginning of Message character - Hex [0B] EOM [String] The End of Message character(s) SegmentDelimiter [String] The Segment Delimiter
FieldDelimiter [String] The Field Delimiter character (1 character only) ComponentDelimiter [String] The Component Delimiter character. RepeatDelimiter [String] The Repeat Delimiter character. EscapeDelimiter [String] The Escape Delimiter character. SubComponentDelimiter [String] The SubComponent Delimiter character.
Future Use Properties These properties are used by the HTHL7Message object (Future Version) when assembling HL7 messages;
IncludeBOMEOM [Boolean] Default = False. Include the message enveloping characters (BOM and EOM) when assembling messages. EndAllSegmentsWithFieldDelimiter [Boolean] Default = False. Include the FieldDelimiter character at the end of every segment. EndLastSegmentWithSegmentDelimiter [Boolean] Default = True. Always append the SegmentDelimiter character after the last segment.
|
HL7MessageEncoder Copy() Returns: HL7MessageEncoder - A copy of the object.
Boolean IsANSI() Returns: Boolean - True if all Read / Write properties are identical to their default ANSI values.
Boolean SetEncodingCharacters(String encodingChars) Parameter 1: String - The four (4) encoding characters (ComponentDelimiter + RepeatDelimiter + EscapeDelimiter + SubComponentDelimiter). Returns: Boolean (Success/Failure) Description: Sets all 4 encoding characters. Must be a valid 4 character String which follows the HL7 rules for encoding characters.
Void ResetToANSI() Description: Resets all Read/Write properties to their ANSI default values.
Boolean Validate() Returns: Boolean - True if all Read / Write properties contain valid HL7 conforming values.
|
Implementation: When the object is created all of the Read/Write properties are set to their ANSI default values. You can then change them if needed to instruct the HL7 message parser on any non-ANSI idiosyncrasies your HL7 messages might contain.
Exception Handling: Follows the Common Exceptions Interface.
Discussion
The HL7 standards are really quite strict, they say "Here's how it's going to be, unless you decide amongst yourselves to do it differently". Our parsing engine can parse any properly formed HL7 2.x message with very little need for help from the developer. There are a couple of exceptions though and you must at least be aware of them to work with this API.
You must know:
1.What the BOM and EOM characters are (if your HL7 message strings contain them) and whether or not they are the ANSI standard characters. If not you need to create a "customized" encoder object to tell the API how to behave. In the SQL Schema Engine, these values are warehoused in the HL7 Vendor Definition. In the API you use the HL7MessageEncoder class.
2.What the SEGMENT delimiter (sometimes called the SOM) is and whether or not it is the ANSI standard (A carriage return or Ascii character 13 or Hex[0D]).
Programming note about #2. We try as hard as we can to make the API forgiving, so our parser will forgive the most common mistakes people make with the SEGMENT delimiter which is the general "messing up" of Carriage Returns CR, Line Feeds LF, and Carriage Return-Line Feeds CRLF.
The scenario is simple, the HL7 message contains the ANSI standard Carriage Return, then somebody decides to look at the message in some less than great text editor, they change it, save it, and voila the file now contains a CRLF instead a CR.
IF your HL7MessageEncoder has the SegmentDelimiter property set to the ANSI standard CR, then your messages can also have EITHER LF or CRLF SegmentDelimiters as well and they will parse just fine.
Example: using a non-standard SegmentDelimiter value.
C#
SQLSchemaAPIKey MyKey = new SQLSchemaAPIKey("Valid Key or File");
HL7MessageEncoder var = new HL7MessageEncoder();
// Or
var = MyKey.NewEncoder();
//I have a trading partner that uses the TAB character
//as the Segment Delimiter. Hey, we've seen it.
var.SegmentDelimiter = MyKey.Utils.FromAsciiHexString("09");
string sHL7 = "<one of the offending messages>";
if(!MyKey.TestHL7Message(sHL7,var))
{
//It's bad
Console.WriteLine(MyKey.LastError);
}
else
{
//It's good
Console.WriteLine("Huzzah!!");
}
