|DotNet Class HL7Connect.V2.Message|
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
|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
|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
|The event for this message|
|The Message type for this message. Setting this will alter the value of the MSH segment if one exists|
|The Name of the Message type for this message. Setting this will alter the value of the MSH segment if one exists|
|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.|
|Dictionary information about the structure for this message|
|The number of segments in the message.|
|Full source for the original message (when reading)|
|The character used as the Field delimiter. 1 character long only.|
|The character used as the Component delimiter. 1 character long only.|
|The character used as the SubComponent delimiter. 1 character long only.|
|The character used as the Repeat delimiter. 1 character long only.|
|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:
|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
|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 ")
@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 is the same as PID[@index=2]
EVN-1 Event Type
MSH-9-3 Structure identifier
PID-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
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
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)
XMLThe 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|
|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|
|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:
etcthen the empty repeat will be deleted. This is not empty:
finally, regarding this situation:
|~Content|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
|generate an exact copy of this message|
|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