Ancestor: HL7Connect.V2.DataObject

Encapsulates a single logical HL7Message.

To read an existing message, create an HL7Message and then decode a source message.

To create a reply, create an HL7Message, and then use BuildAsReply.

To create a new message, create a message, set it's version, and then add the segments that you require and populate them with values. When finished, call Encode


string Encoding;
   The encoding for this message. If the message has been decoded, then this is the encoding that was read. If the message is encoded, this encoding will be used unless something different is specified when the message is encoded.

Valid Values = XML or ER7

string Version;
   Version of message. This should be treated as read-only except when building a message before any segments have been added.

If you want to change the version after the message has segments, use ChangeVersion

string Event;
   The event for this message

string MessageType;
   The Message type for this message. Setting this will alter the value of the MSH segment if one exists

string StructName;
   The Name of the Message type for this message. Setting this will alter the value of the MSH segment if one exists

string MsgID;
   The message ID of this message. This should be treated as read-only except when building a message before any segments have been added. Setting this will alter the value of the MSH segment if one exists.

HL7Connect.V2.DictMessageStructure Structure;
   Dictionary information about the structure for this message

int SegmentCount;
   The number of segments in the message.

string Source;
   Full source for the original message (when reading)

string FieldDelimiter;
   The character used as the Field delimiter. 1 character long only.

string ComponentDelimiter;
   The character used as the Component delimiter. 1 character long only.

string SubComponentDelimiter;
   The character used as the SubComponent delimiter. 1 character long only.

string RepeatDelimiter;
   The character used as the Repeat delimiter. 1 character long only.

string EscapeDelimiter;
   The character used as the Escape delimiter. 1 character long only.


HL7Connect.V2.Segment GetSegmentByIndex(int AIndex);
HL7Connect.V2.Segment GetSegment(string ACode, int i);
HL7Connect.V2.Cell GetElement(string sCode);
void ChangeVersion(string ANewVersion, bool ADeleteInvalidContent);
   Change the Version of the message to the version specified. ChangeVersion is not very elegant - use with care.

if DeleteInvalidContent is true, anything in the message but not in the dictionary for the specified version is deleted.

There is many issues with this procedure that are yet to be determined, including:

  • downgrading a message into a version where the event or message type does not exist
  • upgrading a message into a version which contains compulsory segments
not defined in the initial version. (If this happens anywhere in the standard?)

HL7Connect.V2.Segment Segment(string ACode, int i);
   Retrieve a given segment (3 letter code). There may be multiple xxx segments in a message. Segment 0 is the first instance of a given segment.

IList<HL7Connect.V2.Segment> SegmentQuery(string query);
   Retrieve a set of segments

If the query is empty, all the segments in the message are returned.

The query specifies which set of segments to retrieve:

 XXX: a three letter code means all segments with the specified code
 X* : the asterisk is a wild card - all segments whose code starts with the specified letter
  • : all segments
HL7Connect.V2.Cell Element(string ACode);
   Element is the most convenient way to retrieve content Code is a string with format SEG[]-N[].O.P
  Seg - 3 letter code of segment
  N   - Data Element index (starts at 1)
  O   - Component Element index (starts at 1) [optional]
  P   - Subcomponent index  [optional]

SEG-N-O-P is also accepted

both SEG and N can be followed by a condition to specify which repeat to use. In the absence of such a condition:

  for segments:      First matching segment
  for data elements: First Repeat (actually the 0th repeat, the field that isn't a repeat)

if a condition is specified, it can be a simple number - choose the nth instance. (note that the first segment is 1 and the first field is 0).

Alternatively, the condition can be an expression using any combination of the following items:

  =    case sensitive equals
  ==   non case sensitive equals
  !=   not equals
  !==  not equals - not case sensitive
  ~    Regex test
  |~   starts with (not case sensitive)
  ~|   ends with (not case sensitive)
  +    addition - numerical if both operands a numeric, else string concatenation
  ++   forced numerical addition (will be an error if one or both operands are not numerical)
  -    numerical subtraction (will be an error if one or both operands are not numerical)
  &    string concatenation
  and  logical and
  or   logical or
  xor  logical xor
  @    a nested query. The context for the nexted query will be the segment or field to which the condition is attached
  ""   string constants (double "" inside string constants for the character ")

Special Variables:

  @index  The index of this instance in the list

Support for () as precendence operators is planned, but they are not currently supported.

if a condition simply consists of a number, it will be taken to be a reference to the index i.e. PID[2] is the same as PID[@index=2]


  EVN-1                                  Event Type
  MSH-9-3                                Structure identifier
  PID[1]-3-1                             UR number in second PID segment (i.e. in an A17 message) - counting is from zero
  PID-11[@7="H"].1                       1st Street line of Home Address
  PID-13[@2 = "PRN" and @3="PH"].1       Phone number for home phone
  OBX[@3.1="HEIGHT" or @3.2="HEIGHT"]-5  Value from OBX segment for Weight

void ForceElement(string sCode);
   Uses the similar syntax as element, but will create the element if it does not exist. The segment must exist.

The acceptable syntax is SEG[]-N[]-O-P where the contents in the [] can be real numbers - no conditions allowed

void Decode(string APacket, string AVersionOverride, int ASegmentLimit, string sFormat, bool ASuppressErrors);
   decode converts a message into a DOM type tree integrated with the dictionary.

If VersionOverride is provided, a version of HL7 different to that claimed by the message will be used - a way to handle exceptions to the standard.

If a segmentlimit is provided, only the first few segments will be decoded up to the specified limit. This is to support high-throughput applications only interested in the MSH (and perhaps the EVN). Note that PID's can be scattered through the message so it is dangerous to examine the PID segment if a segment limit has been set

You can also nominate the Format. The library will choose the right class for all messages currently observed, so this is not usually necessary. Valid Values are XML or ER7

You can also set ASuppressErrors. If this is true the library will do it's best to suppress errors encountered reading messages. You need to be very careful if you set this to true as the library will do it's level best to ignore errors when reading messages in this case. This is mostly used with XML messages to deal with cases where the library needs to deal with XML messages that do not use the right data types.

See also decodeOptions which provides more control

void DecodeOptions(string APacket, string options);
   decode converts a message into a DOM type tree integrated with the dictionary.

The options must be one or more of the following words, separated by whitespace:

    Where X is 2.v (i.e. 2.3 or 2.3.1). v can be any of the supported versions.
    Parse as if the specified version, irrespective of what the message says

    Where n is an integer. Parse up the first n segments only. If n is 0, or
    this option is not specified, the entire message will be parsed.

    Treat as xml without first trying to figure out what it is

    Treat as vertical bar message without first trying to figure out what it is

    Tell the parser to do it's best to suppress errors encountered reading
    messages. Mostly this relates to XML parsing where the apparent semantics
    in the instance don't match the specified semantics in the standard

    Don't allow odd length \Xdd\ escape sequences to have a '0' prepended to them. (causes an exception instead)
    i.e. \X9\ is not treated as \X09\

string Encode(string sFormat, string sOptions);
   Encode and return the encoded message, using the ITS specified by the parameters. Valid values are
  ER7    (the famous vertical bars)
The default value is ER7

sOptions: any space separated combination of:

    when writing XML, how the segments are mapped against the segment structure. If
    this is not defined, then the list of segments must match the expected list. If
    this is not defined, then the mapping code will attempt to deal with unexpected
    segments. Note that in optimistic mapping, things can go quite badly wrong
    if they do go wrong

    If this is set, then if mapping fails, any remaining segments not
    mapped will be mapped into the root segment. If this is not set,
    and mapping fails, then an exception will be raised and encoding
    will fail. Relevent for XML

    When this is set extended characters (ascii 127+) will automatically
    be escaped in ER7 format.

    for stupid OACIS system that requires an extra Field Delimiter at
    the end of every segment

    suppress the automatic addition of a structure name (MSH-9-3)

void BuildAsReply(HL7Connect.V2.Message AMsg, bool AUseSequenceNum, int ASequenceNum);
   Build this message as a reply to the given message. Add sequence numbering info if provided

void SetExceptionMessage(string AMsg, bool AMakeReject);
   Populate NACK message using the String in MSA-3. The message will be an AE unless MakeReject is true, in which case it will be an AR. BuildAsReply must have been used already

HL7Connect.V2.Segment AddSegment(string ACode);
   Add the specifed segment to the message and build it's Data Elements and components

HL7Connect.V2.Segment InsertSegment(int AIndex, string ACode);
   Add the specifed to the segment to the message at the point nominated and build it's Data Elements and components If Index is 0, the string is inserted at the beginning of the list. If Index is 1, the string is put in the second position of the list, and so on.

void DropSegments(string ACode);
   Drop any segments with the given code from the message

void DeleteSegment(HL7Connect.V2.Segment ASegment);
   Delete the segment from the message. Do not refer to the segment after it is deleted

void CloneSegment(HL7Connect.V2.Segment ASegment);
   Copy a segment from another message - add it to this message as a new segment. All information whether in dictionary or not will be copied across

void AddMSHForBuild();
   special case - this puts an MSH in place and populates it as much as possible from known information

int CountSegment(string ACode);
   number of segments of given type

void Clear();
   Clear all segments and message information

void StripEmptyRepeats(bool ALeading);
   incredible as it may seem, some very large vendors send HL7 that contains empty repeats. This is often in contexts where the presence of non-empty repeats has meaning. This procedure will find and delete any repeats with empty content.

If a field is encoded as |content~content| then the repeat will stand. if the content is encode as any of the following:

then the empty repeat will be deleted. This is not empty:

finally, regarding this situation:

The first instance of the field (it's unclear whether this is usually called a "repeat") will be dropped and the content promoted in it's place if ALeading is true, and nothing will happen if ALeading is false

HL7Connect.V2.Message Clone();
   generate an exact copy of this message

void UpdateSource();
   update the internal source so that it reflects the current state of the message (using message.encode).

This doesn't do anything - it's deprecated, but remains declared because many scripts use it for historical reasons

© Kestral Computing P/L 2000 - 2003. HL7Connect v2.00-063 generated on 30-Nov 2015.
Keywords: Structure, Decode, EnCode, CloneSegment, Element, ForceElement, AddMSHForBuild, AddSegment, BuildAsReply, ChangeVersion, Clear, Clone, ComponentDelimiter, CountSegment, DecodeOptions, DeleteSegment, DropSegments, Encoding, EscapeDelimiter, Event, FieldDelimiter, InsertSegment, MessageType, MsgID, RepeatDelimiter, Segment, SegmentCount, SegmentQuery, SetExceptionMessage, Source, StripEmptyRepeats, StructName, SubComponentDelimiter, UpdateSource, Version, Message, GetElement, HL7Connect.V2.Message, GetSegmentByIndex, GetSegment