One might think that in a system whose primary function is dealing with HL7 messages, that the EasyHL7Message object would be the most important, but that's not the case. The HL7Vendor object is what operates at the center of the EasyHL7MC40 universe! The EasyHL7Message object uses the HL7Vendor object to get HL7 structure and definition information about how to create and read HL7 messages. The HL7FileAnalyzer object uses the HL7Vendor object to get information about what to expect when analyzing HL7 data files (like the BOM and EOM characters).

For more info see: Properties and Methods

Object Creation:

Dim oVendor As New EasyHL7MC40.HL7Vendor

Private oVendor As New EasyHL7MC40.HL7Vendor

Public oVendor As New EasyHL7MC40.HL7Vendor

Friend oVendor As New EasyHL7MC40.HL7Vendor

Programming with the HL7Vendor object

It's very important to get started correctly when programming with the HL7Vendor object. This object will most likely form the center of every HL7 application you create, so creating the object AND then initializing it properly and making sure that it is in a usable state is vitally important. Before you can really use the HL7Vendor object you must do 3 things.

1. Is there a license? For the object to work you must have a product license of some kind (Demo, Runtime, or Developer) AND the object must be able to "see" that license (the license file MUST be in either the folder where your application is running [.EasyInstallationFolder] OR the folder selected as the .VendorPath). Without a license (or with an expired Demo license) just about the only methods that work in the object revolve around getting a license. For more detailed information about exactly what a license is see the discussion below. The HL7Vendor object gives you several methods both for checking it's license status and also for obtaining a product license both silently (in the background) or via a built-in User Interface. NOTE: If you DO NOT own the EasyHL7 Managed Code objects and are just evaluating them then use the example program to generate a "Demo" license and then copy the license file to your <project>\bin\Debug or <project>\bin\Release folders.

Properties and Methods that deal with the License

2. Are the EasyHL7 Vendor definitions installed and where are they? After you've determined that your object has a valid license the 2nd step is to set the MOST IMPORTANT property for the HL7Vendor object, the .VendorPath. This is the folder where your HL7Vendor object will find the EasyHL7 Vendor definitions which it MUST have to operate and in fact will need for Step 3 below. For more detailed information on what an EasyHL7 Vendor definition is read the discussion below. The HL7Vendor object comes with EasyHL7 Vendor definitions for HL7 Versions 2.2, 2.3, 2.4, 2.5, 2.5.1 and 2.6 embedded which can be placed into a folder using the InstallDefaultVendors method.

A common method of setting and verifying the VendorPath

3. Open a Vendor definition. Steps 1 and 2 were the hardest. Now you just need to open an EasyHL7 Vendor definition and go to work. You use the OpenVendor method to do this but you do have to pass the VendorID to OpenVendor so you can use the GetVendorID method to retrieve a VendorID. For more information about what a vendor definition is and the role that it plays in your HL7 projects see the discussion below.

What is the License?

The EasyHL7MC license is a physical file on the file system. It will either be named <ProductID>.mc.lic (for a 'Demo' or 'Runtime' license) or EasyHL7.lic (for a 'Developer') license. Licenses are unique to each computer, this is why you can't "ship" a license with your programs and also why when you purchase a license from HermeTech we can't "send" you the license. The license has to be generated AFTER your program is installed because the ProductID (which is unique to each computer) is required to create it. EasyHL7MC will automatically detect this file so it MUST be located in 1 of 2 places:

There are 3 types of license files.

1) A DEVELOPMENT license. This is the license which you purchase from the HermeTech International Ltd EasyHL7 website (www.hermetechnz.com). It will be named EasyHL7.lic and the file is only good on a single computer. You purchase DEVELOPMENT licenses for your developer's computers as needed.

2) A RUNTIME license. If you own a DEVELOPMENT license you can create RUNTIME licenses using the EasyHL7 License Manager or also directly from your code using several built-in methods (an internet connection is required for that). See ActivateFromClipboard, ActivateComputerForDemo, ActivateComputerForRuntime. While not free, Runtime licenses are extremely cost-effective. You will receive 20 free runtime licenses when you purchase your first Developer license and after that can be purchased in bundles with a per license cost which will never exceed US$5.00 and can be as little as US$2.00.

3) A DEMO license. Any EasyHL7 customer who has registered on our website (which you had to do to download the software) can create DEMO licenses. You can do this directly from code over the internet. DEMO licenses have a 30-45 day expiration period (You can test when a License expires by calling the .LicenseExpiresOn or .LicenseExpired property). If you own a DEVELOPMENT license you can create an unlimited number of DEMO licenses, if not you can create DEMO licenses for up to 5 different computers (if you need more, contact customer service).

How is a license created? Licenses are generated either by calling one of the activation methods in the ProductLicense object or (if you own a Developer License) by using the EasyHL7 License/Account Manager a piece of free software available on our website (www.hermetechnz.com/EasyHL7). If you are evaluating the EasyHL7MC40 objects and do not own a license then use the example program to create a "Demo" license and then copy that file to your project\bin\.. folders

Can licenses be transferred? Yes and No. Each physical license file is only good for the computer on which it is installed, however, you can contact HermeTech Customer Service (info@hermetechnz.com) and ask that a particular license be 'reset'.

How long are licenses good for? DEMO licenses are good for 30-45 days. Runtime and Developer licenses are good for the life of the computer they were created for.

Can Demo licenses be extended beyond their expiration? No.

What Are EasyHL7 Vendor Definitions?

All HL7 messages are made up of HL7 Segments. HL7 Segments are made up of 1 or more HL7 Fields, and each HL7 Field has a specific HL7 Data Type which contains 1 or more (usually more) Components. HL7 also comes in different versions, the EasyHL7MC40 ships with definitions for HL7 versions 2.2, 2.3, 2.4, 2.5, 2.5.1 and 2.6. With HL7 versions 2.nn each version is really a superset of the prior version, that is to say version 2.3 is version 2.2 + more, version 2.5 is version 2.4 + more and so on. An EasyHL7 Vendor Definition contains all of these properties. Expand the sample to see how this works.

Sample HL7 Segment Definition

But there's more, the vendor definition might also contain "custom" segment definitions. These are HL7 message segments which are NOT part of the ANSI standards (and thus won't be in ANY of the "Default" definitions which come with the EasyHL7MC40 objects). The HL7 standard allows for custom segments as long as they begin with the letter Z and follow HL7 standard field and data type conventions. It's the responsibility of the HL7 Trading Partners to agree on these "Z" segments before exchanging messages. For instance, I can create my own HL7 segment called ZFI which I will define as containing extended family history information. In it I might put fields like "Grandfather's Name", "Grandmother's Name", "Sibling Count", "Sibling Names", etc etc. I can then create HL7 messages and populate those data fields and send the messages out. However, unless my trading partner has AGREED to accept and process those segments then it does no good. By the same token, I can define my custom ZFI segment and then insist that my HL7 trading partners produce that segment and include it in any HL7 messages which they send to me but they have to agree to do so.

EasyHL7 Vendor definitions can also contain user defined Annotations, Instructions, internal HL7 lookup tables with code/value pairs, etc. etc. For more information on how to manipulate EasyHL7 vendor definitions see the section on user interfaces and also run the example application.

Programmer Note: See almost any form in the example program for practical examples of how to instantiate a HL7Vendor object.