HL7FileAnalyzer Class

The HL7FileAnalyzer class, when used properly, is designed to allow you (the programmer) to safely extract the messages from and then consume HL7 data files. When you activate your HL7FileAnalyzer by calling the AnalyzeFile(fileName) method it will attempt to seize control of fileName locking it from all other processes (both reading and writing). It will maintain this file lock until you call the Clear() method. Once analyzed you can iterate through the file contents as you like, and when you're done call the Clear() method. The Clear() method is also automatically invoked whenever you call the AnalyzeFile(fileName) method, so if (for instance) you are processing an entire folder of HL7 data files it would be acceptable practice to iterate through files calling the AnalyzeFile() method on each file and then calling the Clear() method after processing the final file.

Obvious but still IMPORTANT: Because of the file locking behavior programmers should exercise caution when using this class. Be mindful of your exception handling (Catch) and make sure that the Clear() method is called. If you allow this object to go "out of scope" with a file open and locked then you will be relying on Windows Garbage Collection to destroy the object and finally releasing the lock.

Accuracy

The HL7FileAnalyzer works by identifying MSH segments within the data file. It is possible that if a file is corrupt it can "map" a block of text which is not actually a valid HL7 message. That's the bad news. The good news is that the object will definitely correctly "map" all valid non-corrupted HL7 messages in a data file.

How do I verify the messages mapped? This is easy, corrupted messages will not load properly into a HTSQLHL7Message object. So you can just call the GetMessage(Index) method and check the returned HL7 message object for any exceptions. Note that you could also call the GetRawHL7(Index) method and then try to load that value into your own HTSQLHL7Message object.

Integer BufferedMessageCount - While mapping a HL7 data file the HL7FileAnalyzer keep a non-configurable 2 MB internal "buffer" to hold messages and thus will have the first <xx> messages detected stored in local memory for faster access. When you call the GetMessage(Index) method internally the object will first check to see if Index is "buffered" and if so will retrieve the message from the buffer. If it is not buffered then it will retrieve the message from the file stream by consulting the MessageMap.

Note: IF BufferedMessageCount is equal to MessageCount then the entire file is buffered in memory. It is important to know that while the 2 MB internal buffer is not configurable it is also not a "hard" 2 MB. If you have a data file that's 30 MB and contains 10 messages of 3 MB each (common with DICOMM images, etc) then the FIRST 3 MB message would be buffered. In other words, the 2 MB buffer is filled until AFTER it is exceeded. Example: The same 30 MB data file contains the first 9 messages of 100KB and 1 final message that is 29 MB the 2 MB message buffer would be extended to 30 MB to include the first 10 messages. If the same file contained 11 messages and the 11th message was 1 KB it would NOT be buffered because after the 10th message the 2 MB limit had been exceeded and no further buffering is allowed for that file.

EHFA_ErrorType FAError - Enumerator showing the current internal object error state. Use this in conjunction with the LastException property.

Boolean FileIsOpen - Indicates whether FileName is currently open and locked.

String FileName - The fileName parameter passed in the last AnalyzeFile() operation.

Integer MessageCount - The total number of HL7 messages detected in the current file operation.

List <Of FAMapMetric> MessageMap - The mapped positions of detected HL7 messages within FileName.

Performance Metrics Properties

Test the performance of file analysis operations performed by this class using a standard .Net TimeSpan  object. Evaluate (OperationEnded - OperationStarted).TotalSeconds.

DateTime OperationStarted - The starting time of various operations performed by this class (Import Operations, Training Operations, Parsing Operations, etc). The value is reset for each operation and the default value is SQLAPIGlobals.UndefinedDateValue.

DateTime OperationEnded - The ending time of various operations performed by this class (Import Operations, Training Operations, Parsing Operations, etc). The value is reset for each operation and the default value is SQLAPIGlobals.UndefinedDateValue.

NOTE: These properties always reflect the LAST qualifying operation performed by the class instance. If no operation has been performed the values will be SQLAPIGlobals.UndefinedDateValue. The valid operation for this class is an Analysis Operation invoked by calling the AnalyzeFile() method.

Integer MaxLoad - The maximum number of messages to identify within the HL7 data file when AnalyzeFile() is called. The Default value is 0 and any value of 0 or < 0 indicates that the object should "map" the entire file. Example: Setting MaxLoad to 10 would tell the class to only identify the first 10 messages in the file.

Boolean AnalyzeFile(String)

Parameter 1: String - fileName. The full path/filename of the HL7 data file to be analyzed.

Returns: Boolean Success/Failure - Failure follows the common exception interface of other objects. Also you can refer to the FAError property.

Void Clear() - Clears the object and closes FileName (if open).

IMPORTANT: Since this class locks files you need to be sure that you call this method after you have completed using the file.

HTSQLHL7Message GetMessage(Integer)

Parameter 1: Integer - Index. The index of the message to retrieve. Valid values are between 1 and MessageCount.

Returns: HTSQLHL7Message The HL7 message object at position Index within FileName. If Index is not valid Null is returned and LastException will be set.

String GetRawHL7(Integer)

Parameter 1: Integer - Index. The index of the message string to retrieve. Valid values are between 1 and MessageCount.

Returns: String The raw HL7 string value at position Index within FileName. If Index is not valid an empty string ( "" ) is returned and LastException will be set.