HL7StringAnalyzer Class
Contents
Class Name: HL7StringAnalyzer
Scope: Public - Restricted ( License Required )
Overview: It will analyze a string (or a LoadFromFile method) and carve out HL7 messages. It also has some interfaces to the SQLHL7Importer and SchemaTrainer classes.
NOTE: The object has a maximum capacity of 30 megabytes. It won't accept a string or a file containing a string > than that. See Exception Handling.
Visual Basic
Dim MyKey As New SQLSchemaAPIKey("<A Valid Key or File>") Dim MyAnalyzer As HL7StringAnalyzer = MyKey.NewHL7StringAnalyzer() Dim sHL7 As String = "<some valid string containing HL7 messages>" With MyAnalyzer .Refresh(sHL7) MessageBox.Show("It has " & .Count().ToString() & " messages!") Dim i As Integer 'NOTE this is ONE based For i = 1 To .Count() Dim s As String = .GetMessage(i) 'code 'code Next End With
C#
SQLSchemaAPIKey MyKey = new SQLSchemaAPIKey("Valid Key or File"); string sHL7 = "<string containing 1 or more HL7 messages>"; HL7StringAnalyzer MyAnalyzer = MyKey.NewHL7StringAnalyzer(); MyAnalyzer.Refresh(sHL7); Console.WriteLine("It has " + MyAnalyzer.Count().ToString() + " messages!"); //IMPORTANT - The iteration is ONE based for(int i = 1;i <= MyAnalyzer.Count(); i++) { string s = MyAnalyzer.GetMessage(i); //Code //Code } |
Integer MaximumCapacity - 30 MB (30000 x 1024) - The maximum String size (or File Size if using the LoadFromFile() method) that this class can accommodate. It is a "hard" default and is not configurable. Performance Metrics Properties
Test the performance of various operations performed by this class using a standard .Net TimeSpan object. Evaluate (OperationEnded - OperationStarted).TotalSeconds.
DateTime OperationStarted - The starting time of the last operation 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 the last operation 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.
|
Integer MaximumErrorTableEntries - The maximum number of entries which will be inserted into the <schemaprefix>_MessageErrors table in each Import Operation. The default value is 15.
HL7MessageEncoder PreferredEncoder. The encoder object to use when performing Parsing Operations.
NOTE: This property can also be set when creating the object instance using the SQLSchemaAPIKey.NewHL7StringAnalyzer() methods.
|
Loading the object with HL7 messages **Performance Metrics are set for these operations (See Properties) Boolean Refresh(String) Parameter 1: String - HL7String. Value containing one or more fully formed HL7 messages. HL7String can be up to MaximumCapacity characters.
Returns: Boolean Success/Failure - Failure follows the common exception interface of other objects.
Description: Loads (or Reloads) the object. HL7String is analyzed and HL7 messages are carved out using the HL7MessageEncoder passed in the constructor or by setting the PreferredEncoder property. If any error is encountered in parsing and validating any message detected the entire operation fails. Example: if you have a string that contains 10 messages but message 5 has some form of corruption, the entire operation is aborted, it doesn't just skip #5 and move on. Boolean LoadFromFile(fileName) Parameter 1: String - Full path/filename to file containing HL7 messages. The file can be up to MaximumCapacity bytes in size otherwise the operation fails.
Returns: Boolean Success/Failure - Failure follows the common exception interface of other objects.
Description: Reloads the object from a file on the file system. Integer Count()
Description: Returns the number of HL7 messages loaded into the object.
String GetMessage(Index) Parameter 1: Integer - Integer between 1 and Count().
Returns: String - The HL7 Message string or "" if Index is not valid.
Description: Retrieve a message string from the object. Important because messages in the object have passed parser testing for HL7 valid syntax.
NOTE: GetMessage() returns the RAW HL7 message value used by the HL7StringAnalyzer to create the individual HTSQLHL7Message objects in its collection. This value might not match the CURRENT value of the HL7 message if you have updated the message in process using any of the HTSQLHL7Message Accessor Properties. For that value call GetMessageObject(Index).Value, this is the value that is written to the <prefix>_HL7Data column in Import Operations.
HTSQLHL7Message GetMessageObject(Integer) Parameter 1: Integer - index. Integer between 1 and Count().
Returns: HTSQLHL7Message - The HL7 parser object or Null if Index is not valid.
Description: Retrieve a parsed message object from the HL7StringAnalyzer. Import Operations **Performance Metrics are set for these operations (See Properties)
HL7ImportResults ImportMessage(Index) Parameter 1: Integer - Integer between 1 and Count().
Returns: HL7ImportResults - Results of the import operation. Description: Attempts to import a single HL7 message into your SQL Schema Tables.
List<HL7ImportResults> ImportMessages()
Returns: List<of HL7ImportResults> Description: Performs the ImportMessage() method for Count() message strings.
Boolean InitializeForImporting()
Returns: Boolean Success/Failure - Failure follows the common exception interface of other objects.
Description: You can call this method before you begin import operations. When performing import operations there is some initial overhead loading or refreshing the internal UPSInfo derived subclass. Calling this method ONCE before you begin multiple import operations will let you effectively "preload" that object instance. Calling this method is NOT mandatory, if you don't, it will be invoked automatically on the first import operation performed by the object instance. The only side-effect you might see is that if you are reusing your HTSQLHL7Message object (which you can and are encouraged to do for best performance) in a "Refresh() --> ImportMessages() -->Repeat--<" loop you might notice that the 1st message import operation takes slightly longer to complete than the rest. Training Operations **Performance Metrics are set for these operations (See Properties)
SchemaTrainingResults TrainMessage( autoFix = False) Parameter 1: Integer - index. Integer between 1 and Count(). Parameter 2: Boolean - autoFix (Optional Default is False). Automatically execute suggested SQL fixes if detected default is False.
Returns: SchemaTrainingResults - Results of the operation.
Description: Performs a schema training operation on a single message (see SchemaTrainingResults)
List<SchemaTrainingResults> TrainMessages(Boolean) Parameter 1: Boolean - autoFix (Optional Default is False) Automatically execute suggested SQL fixes if detected.
Returns: List<of SchemaTrainingResults> - Results for every operation.
Description: Performs the TrainMessage() method for each message string and populates the return list with results for each.
|
Event ImportStarted(object sender, eventArgs e) Parameter 1: sender will be of whichever type fired the event. HL7StringAnalyzer, or HTHL7Message, or HL7FileAnalyzer (Future) Parameter 2: e will be of derived class HTImportEventArg.
Trigger: Fired whenever an Import Operation is about to begin. Implementation: Set e.Cancel() to cancel the operation.
Event ImportCompleted(object sender, eventArgs e) Parameter 1: sender will be of type HL7ImportResults. Parameter 2: e will be of derived class HTImportEventArg.
Trigger: Fired whenever an Import Operation is completed. Implementation: Set e.Cancel() to cancel the BATCH operation (if the running operation was part of a batch).
Event TransactionRunning(object sender, eventArgs e) Parameter 1: sender will be of type HTSQLServerConnector. Parameter 2: e will be of derived class HTExceptionEventArg.
Trigger: Fired whenever a multi-command SQL transaction is underway. The event is fired before every command is executed. Implementation: This class uses the HTSQLServerConnector internally and passes this event through to be picked up and fired in other classes derived from the UPSInfo class. Set e.Cancel() to cancel the operation and rollback the SQL Transaction.
Event TrainingStarted(object sender, eventArgs e) Parameter 1: sender will be of whichever type fired the event. HL7StringAnalyzer, or HTHL7Message, or HL7FileAnalyzer (Future) Parameter 2: e will be of derived class HTTrainingEventArg.
Trigger: Fired whenever a TrainingOperation is about to begin. Implementation: Set e.Cancel() to cancel the operation.
Event TrainingEnded(object sender, eventArgs e) Parameter 1: sender will be of type SchemaTrainingResults. Parameter 2: e will be of derived class HTTrainingEventArg.
Trigger: Fired whenever a TrainingOperation has ended. Implementation: Set e.Cancel() to cancel the BATCH operation (if the running operation was part of a batch).
|
Exception Handling: Follows the Common Exceptions Interface.
Programming Notes
For best performance (for reasons which WILL be explained in detail in the near future) you should whenever possible keep these objects in-scope and reuse them and let them fall out of scope when you must.
Example Pseudocode:
<Class MyMainClass>
@Scope - Class
<Create your SQLSchemaAPIKey>
<Use Key object to create needed objects>
<HL7MessageEncoder>
<HL7StringAnalyzer>
...And so on
<Your Process Code Which will reuse the Objects>
<Processes>
<Processes>
<Processes>
......And so on
<Process Ends>
<Class Ends>
Now every time you create <Class MyMainClass> there's some overhead loading the objects up. This is mainly from the UPSInfo class which is used extensively internally and is the base class for the SQLHL7Importer and the SchemaTrainer derived classes. This is the object that has to query system information tables and loads up the schema definition tables structures into memory for every table, every column, etc.
Performance wise you might notice that if you were to recreate <Class MyMainClass> every time you have a HL7 message ready to import it might take 1/2 second or more to import a basic ADT message. However, if you followed the example above, you might see 1/2 second or more on the FIRST message dropping down to milliseconds on subsequent imports.
