Please enable JavaScript to view this site.


Online Help - Region 1: [CORE HL7 API Basic]

Other CORE HL7 API Help Regions

Download the API Libraries


Object: HL7Segment

NOTE: No public entry point. Created only through a HL7Message object.


HL7 Segment Object Hierarchy

HL7 Segment Object Hierarchy


A HL7Message object is essentially a collection of HL7Segment objects (this object). The HL7Segment object is in turn essentially a collection of HL7Field objects, which are in turn a collection of HL7Component objects. As you work you will find that the HL7Segment object is, in many ways, the object you will be interfacing with the most.




Public Properties:


Property Name

Data Type


Uses the Standard Exceptions Interface


bool (read only) - Will be true if the object is a live part of the ParentMessage. See Disconnected Segments above.


int (read only) - Will be the number of HL7Field objects the segment contains. NOTE: Segment Name is field 0 and does not count as a field object.


int (read only) - Will be the ordinal position (1 based) of the segment within ParentMessage. Will be 0 for disconnected segments (see Disconnected Segments above)


HL7Message Object (read only) - Reference to the Parent object that created the segment.


string (read only) - The name of the segment (MSH, PID, OBX, etc, etc)


CORETag Object


string - Get returns the string value of the segment. You can Set this value also by passing in a fully formed HL7 segment string



Public Methods:



Return Value


Uses the Standard Exceptions Interface


HL7Field Appends a new (empty) HL7Field object to the segment.


HL7Field[] Returns a one dimensional array of all HL7Field objects in the segment.


void - Clears all HL7Field objects from the segment. SegmentName does not count and is not cleared.


HL7Segment Returns a disconnected CLONE of the HL7Segment object (see Disconnected Segments above)

Rename(string newSegmentName)

bool Renames a HL7 segment. The SegmentName property is read only, if you ever need to rename a HL7 segment use this setter method. newSegmentName must be a valid HL7 segment name (3 alphanumeric characters) and special rules apply for Connected segments, for instance you cannot rename the MSH segment, and you cannot rename another segment in the message TO MSH.

*For Methods GetField(), GetFieldValue(), SetFieldValue()  - See Below

TrimFieldsTo(int newCount)

void - Removes HL7Field objects from the segment until FieldCount == newCount. newCount <= 0 is the same as Clear().


*Getting and Setting Field and Component Values from the HL7Segment Object

The HL7Segment object gives you several methods for Getting and Setting individual field and component values in your HL7 messages which are outlined below. The IMPORTANT thing to know is that all of these methods only interface with INSTANCE 1 of any field. If you think a field might repeat and need to access all of the repeating instances you will need to get down to the HL7Field object, see Working With Repeating Fields for more information.


HL7Field GetField(int fieldNumber, bool padIfNotPresent = false) Returns the HL7Field object at position fieldNumber of the segment. IF padIfNotPresent == true AND fieldNumber < FieldCount then HL7Fields are added to the segment until FieldCount == fieldNumber. IF padIfNotPresent == false AND fieldNumber < FieldCount will return null.

Example Code (C#):


        HL7Segment oSeg = oMessage.AddSegment("PID|1|f2|f3|f4|Doe^John");

          //oSeg is a connected segment object with 5 fields representing a PID segment

           HL7Field oField;

           oField = oSeg.GetField(7);

          //oField will be null because there are only 5 fields in the segment

           oField = oSeg.GetField(7, true);

          //NOW oField will be the HL7Field object for field #7 of the PID segment


string GetFieldValue(int index) Returns the FULL field value of the HL7Field object at position index. Will be "" if index < 1 or index > FieldCount.

string GetFieldValue(int index, int componentIndex = 1) Returns the FULL component value of HL7Component of componentIndex of the HL7Field object INSTANCE 1 at position index. Will be "" if index < 1 or index > FieldCount. OR componentIndex < 1 OR componentIndex > HL7Field.ComponentCount.

Example Code (C#):


          string tst;

           HL7Segment oSeg = oMessage.AddSegment("PID|1|f2ID1~f2ID2~f2ID3^AA~f2ID4|f3|f4|Doe^John");

          //oSeg is a connected segment object with 5 fields representing a PID segment

          //Note that field 2 is a repeating field

           tst = oSeg.GetFieldValue(2);

          //tst is now the FULL value of field 2

          //tst == "f2ID1~f2ID2~f2ID3^AA~f2ID4"

           tst = oSeg.GetFieldValue(2, 2);

          //Since I specified which component value I wanted 2

          //I get back the value of Component #2 in the FIRST instance

          //only of Field #2 which will be blank! 1st instance only has 1 component.

          //tst == ""

          //To access repeating instances I need to get down to the HL7Field object

           HL7Field oField = oSeg.GetField(2);

          //Now I can ask for the value of Component #2, instance #3

           tst = oField.GetComponentValue(2, 3);

          //tst now == "AA"


void SetFieldValue(int index, string value) Will set the Value of the HL7Field object at position index to value. If index < 1 nothing happens, if the FieldCount is < index fields are added to the segment until FieldCount == index.

void SetFieldValue(int index, int componentIndex, string value) Will set the Value of component componentIndex of field index with value. If the field or component don't exist they are added as above and if index < 1 or componentIndex < 1 nothing happens.

Example Code (C#):


          int tst;

           HL7Segment oSeg = oMessage.AddSegment("PID");

          //oSeg is now a PID segment in the message

           tst = oSeg.FieldCount;

          //tst is 0

          //Now set the Patient FULL name in 1 call

           oSeg.SetFieldValue(5, "Smith^John^P");

           tst = oSeg.FieldCount;

          //tst is now 5

          //Even though the segment was empty, 5 fields were

          //automatically added by this call.

          //wipe out the entire field

          //Clear field #5

           oSeg.SetFieldValue(5, "");

          //Set just the patient last name

           oSeg.SetFieldValue(5, 1, "Jones");


           tst = oSeg.FieldCount;

          //tst is 0

          //Now do the same things we did above with the HL7Field object

           HL7Field oFld = oSeg.GetField(5, true);

           tst = oSeg.FieldCount;

          //tst is now 5. Using true as parameter 2 caused 5 empty fields

          //to be added.

           oFld.Value = "Smith^John^P"; //Set the whole field with 1 call


           oFld.SetComponentValue("Jones", 1);









Keyboard Navigation

F7 for caret browsing
Hold ALT and press letter

This Info: ALT+q
Nav Header: ALT+n
Page Header: ALT+h
Topic Header: ALT+t
Topic Body: ALT+b
Exit Menu/Up: ESC