An instance of this class represents a pipe-delimited HL7 message. This class can be used in MD Link jython scripts to create and manipulate HL7 messages.
Repetitions: one can also get and set the values of repeating segments and fields with this class. To do this, supply a 2-tuple for the argument in question (i.e. segment location or field location), with the desired repetition number as the second element of the tuple. For example, if the variable msg refers to a message object that looks like this:
MSH|^~\&|xxx
EVN|one
EVN|two~three
then msg.getField('EVN', 1) will return 'one',
msg.getField(('EVN',2), 1) will return 'two',
msg.getField(('EVN',2), (1,2)) will return 'three', and
msg.getField(('EVN',2), (1, -1)) will also return 'three'.
It's worth noting that although segment and field repetition numbers start from 1, repetition 1 doesn't really refer to the first repetition of the field, but rather, one could say, to the first instance of it.
void addSegment(HL7Segment newSegment)
Adds the given segment onto the end of the message.
HL7Segment addSegment(string newSegmentString)
Same as addSegment(), but instead of adding an already-created segment object, this method takes a string as an argument and automatically creates a new segment object out of it.
void addSegment(segmentLocation, HL7Segment newSegment)
Add an already-created segment to this message at the specified segment index.
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
newSegment - the segment to add. This segment object is not copied; it is added "live" to the message object. So any changes made to it after calling this method will be reflected in the mesage (and vice versa).
You can create one of these segment objects with the util.makeHL7Segment() methods, or by calling clone() on an existing segment object.
HL7Segment addSegment(segmentLocation, string newSegmentString)
Same as addSegment(), but instead of adding an already-created segment object, this method takes a string as an argument and automatically creates a new segment object out of it.
void addSegmentAfter(segmentLocation, HL7Segment newSegment)
Add an already-created segment to this message after the specified segment location.
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
newSegment - the segment to add. This segment object is not copied; it is added "live" to the message object. So any changes made to it after calling this method will be reflected in the mesage (and vice versa).
You can create one of these segment objects with the util.makeHL7Segment() methods, or by calling clone() on an existing segment object.
void addSegmentAfter(segmentLocation, string newSegmentString)
Like addSegmentAfter() but takes a string argument instead of an HL7Segment object.
Example: if you want to add a PID segment after your EVN segment, you could write:
hl7msg.addSegmentAfter('EVN', 'PID|1||J0999|')
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
a deep copy of this message.
string getComponent(segmentLocation, fieldLocation, int componentIndex)
Returns the value of the specified component.
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
fieldLocation - May be either an integer (a 1-based field index) or an (int,int) tuple (a 1-based field index and a 1-based field repetition index - eg. (3,2) or (3,-1) for last repetition of third field).
string getField(segmentLocation, fieldLocation)
Returns the value of the specified field. Unlike setField() does with its input value, this method will not return multiple components or repetitions. On a message like 'MSH|^~\&|one^two~three^four',
getField("MSH", 3) will return 'one', and
getField("MSH", (3, 2)) will return 'three'.
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
fieldLocation - May be either an integer (a 1-based field index) or an (int,int) tuple (a 1-based field index and a 1-based field repetition index - eg. (3,2) or (3,-1) for last repetition of third field).
string getAllComponents(segmentLocation, fieldLocation)
Returns the value of all components in the specified field. On a message like 'MSH|^~\&|one^two~three^four',
getField("MSH", 3) will return 'one^two', and
getField("MSH", (3, 2)) will return 'three^four'.
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
fieldLocation - May be either an integer (a 1-based field index) or an (int,int) tuple (a 1-based field index and a 1-based field repetition index - eg. (3,2) or (3,-1) for last repetition of third field).
string getAllFieldRepetitions(segmentLocation, fieldLocation)
Returns the value of all repetitions of the specified field. On a message like 'MSH|^~\&|one^two~three^four',
getField("MSH", 3) will return 'one^two~three^four'.
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
fieldLocation - May be either an integer (a 1-based field index) or an (int,int) tuple (a 1-based field index and a 1-based field repetition index - eg. (3,2) or (3,-1) for last repetition of third field).
list of strings getAllFieldRepetitionsAsList(segmentLocation, fieldLocation)
Returns the value of all repetitions of the specified field as a list of strings. On a message like 'MSH|^~\&|one^two~three^four',
getField("MSH", 3) will return ['one^two', 'three^four'].
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
fieldLocation - May be either an integer (a 1-based field index) or an (int,int) tuple (a 1-based field index and a 1-based field repetition index - eg. (3,2) or (3,-1) for last repetition of third field).
HL7Segment getSegmentId(int n)
the ID of the Nth segment. Will throw an exception if that segment doesn't exist.
HL7Segment getSegment(int n)
the Nth segment, or None if that segment doesn't exist. The returned segment object is "live" with respect to the original message object, so any changes made to it will be reflected in the original message object (and vice versa).
HL7Segment getSegment(segmentLocation)
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
the specified segment object, or None if that segment doesn't exist. The returned segment object is "live" with respect to the original message object, so any changes made to it will be reflected in the original message object (and vice versa).
int getAbsoluteSegmentIndex(segmentLocation)
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
the specified segment absolute index, or throws error if specified segment doesn't exist.
HL7Segment newSegment(string segmentId)
Create a new, empty segment and append it to the end of this message.
segmentId - the type (or ID) of the segment to add. Typically three characters.
the new segment. (It will have been added to the message already.)
int numComponents(segmentLocation, fieldLocation)
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
fieldLocation - May be either an integer (a 1-based field index) or an (int,int) tuple (a 1-based field index and a 1-based field repetition index - eg. (3,2) or (3,-1) for last repetition of third field).
the number of components that the specified field (and repetition) contains, or 0 if the specified field (and repetition) does not exist.
int numFieldRepetitions(segmentLocation, int fieldIndex)
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
the number of repetitions that the specified field contains, or 0 if the specified field does not exist.
Grammatically speaking, the returned value does not represent the number of repetitions -- eg. for a segment like ZYX|one|two~two|, field 1 clearly does not repeat, so one could say that it has 0 repetitions. But the way we count, we still say (and this method still returns) that it has one repetition.
int numFields(segmentLocation)
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
the number of fields that the specified segment contains, or 0 if the specified segment does not exist. "field 0" (i.e. the segment ID) does not count towards this total.
the total number of segments in this message.
int numSegmentsWithId(string segId)
the number of segments in this message with the specified segment ID.
void removeComponent(segmentLocation, fieldLocation, int componentIndex)
Remove the specified component and all subsequent components in the specified field (+ repetition). If the specified component does not exist, then do nothing. If component 1 is specified then it is cleared, not removed.
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
fieldLocation - May be either an integer (a 1-based field index) or an (int,int) tuple (a 1-based field index and a 1-based field repetition index - eg. (3,2) or (3,-1) for last repetition of third field).
void removeField(segmentLocation, int fieldIndex)
Remove the specified field and all subsequent fields in the specified segment.
If the specified field does not exist, then do nothing.
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
void removeFieldRepetition(segmentLocation, fieldLocation)
Remove the specified field repetition and all subsequent field repetitions in the specified field. If the specified field repetition does not exist, then do nothing. If repetition 1 is specified then it is cleared, not removed.
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
fieldLocation - May be either an integer (a 1-based field index) or an (int,int) tuple (a 1-based field index and a 1-based field repetition index - eg. (3,2) or (3,-1) for last repetition of third field).
void removeSegment(int segmentIndex)
Removes the segment at the specified index.
This method will effectively shift (down) the indexes of all subsequent segments; it will not, as removeField(), removeFieldRepetition(), and removeComponent() do (with fields, field repetitions, and components respectively) remove all subsequent segments as well.
segmentIndex - This segment index addresses the entire message, and its value 1,2.. for front indexing or -1,-2.. for back indexing.
void removeSegment(segmentLocation)
Remove the specified segment.
This method will effectively shift (down) the indexes of all subsequent segments; it will not, as removeField(), removeFieldRepetition(), and removeComponent() do (with fields, field repetitions, and components respectively) remove all subsequent segments as well.
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
void setComponent(string newComponentValue, segmentLocation, fieldLocation, int componentIndex)
Sets the specified component to the specified value.
newComponentValue - may contain subcomponent delimiters (typically "&") if desired. These characters are not treated specially; since this class does not go down to the subcomponent level, the only way to insert subcomponents into a message is to include subcomponent delimiters as part of a component value.
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
fieldLocation - May be either an integer (a 1-based field index) or an (int,int) tuple (a 1-based field index and a 1-based field repetition index - eg. (3,2) or (3,-1) for last repetition of third field).
void setField(string newFieldValue, segmentLocation, fieldLocation)
Set the specified field to the specified value.
newFieldValue - If fieldLocation doesn't identify a field repetition then this method will overwrite the entire specified field, including all field repetitions and components within. (Naturally this argument can contain field repetition and component delimiters in this case.)
If fieldLocation does identify a field repetition then this method will only overwrite the specified field repetition and any components within it -- other repetitions will not be modified. (Naturally this argument can contain component delimiters, but not field repetition delimiters, in this case.)
Also, this argument may contain subcomponent delimiters (typically "&") if desired. These characters are not treated specially; since this class does not go down to the subcomponent level, the only way to insert subcomponents into a message is to include subcomponent delimiters as part of a component value.
segmentLocation - May be either a string (a segment ID) or a (string,int) tuple (a segment ID and a 1-based repetition index - eg. ('ZYX',2) or ('ZYX',-2) for last second repetition of 'ZYX' seg).
fieldLocation - May be either an integer (a 1-based field index) or an (int,int) tuple (a 1-based field index and a 1-based field repetition index - eg. (3,2) or (3,-1) for last repetition of third field).
a string version of the message. This is the reverse of creating an object with util.makeHL7Message(textvar).
string makeAckString(string ackType, string message)
an HL7 ACK message in string form. The MSA-1 of this message will be ackType. The MSA-3 of this message (if not None) will be message.
HL7Message makeAckObject(string ackType, string message)
Same as makeAckString(), but returns a new instance of HL7Message (i.e. this class) instead of a string.
an HL7 ACK message in parsed object form.
the segment delimiter character for this message, which is by default the carriage return '\r'.
void setSegmentDelim(string newSegmentDelim)
Sets the segment delimiter character for this message.
the field delimiter character for this message, which is by default the pipe character '|'.
void setFieldDelim(string newFieldDelim)
Sets the field delimiter character for this message.
the component delimiter character for this message, which is by default the caret '^'.
void setComponentDelim(string newComponentDelim)
Sets the component delimiter character for this message.
the segment field repetition character for this message, which is by default the tilde '~'.
void setRepetitionDelim(string newRepetitionDelim)
Sets the field repetition delimiter character for this message.
the subcomponent delimiter character for this message, which is by default the ampersand '&'.
int getSegmentPositionWithinMessage(HL7Segment segment)
the absolute index of the given segment within this message. If the segment does not belong to this message, an exception is thrown.
list of HL7Segment getSegments([segmentIds])
Returns a list of segments. This function is convenient for looping through segments.
For example, to set the 10th field of every segment to 'x':
for segment in hl7msg.getSegments():
segment.setField('x', 10)
To do this for OBX segments only:
for segment in hl7msg.getSegments('OBX'):
segment.setField('x', 10)
To do this for OBR and OBX segments:
for segment in hl7msg.getSegments(['OBR', 'OBX']):
segment.setField('x', 10)
newFieldValue - optional. If present, can be a string or a list of strings.
a list of segments.
list of integers getFieldRepetitionNums(segmentLocation, int fieldIndex)
Returns a list of field repetition indices which are convenient for writing loops. For example:
for repNum in hl7msg.getFieldRepetitionNums('EVN', 4):
print msg.getAllComponents('EVN', (4,repNum))
a list of integers, which are 1-based field repetition indices.