private COREUtilities MyUtilities = new COREUtilities();

      private HL7Controller oController = null;

      private HL7Message oMessage = null;

      private void MakeAMessage()

       {

          //For our example we will assume that oController has already been created and

          //the license verified (see snippets in Getting Started).

          //We are also using the object the way that we do. That is to say

          //we create the object at the Class level whenever possible and then

          //reuse it over and over again. Slight performance improvement this way.

          if (oMessage == null)

           {

               oMessage = oController.NewHL7Message();

           }

           oMessage.Clear();

          //I MUST add the MSH Segment FIRST

           HL7Segment oMSH = oMessage.AddSegment("MSH");

          //Now I can use the oMSH OR I can just set some quick shortcut properties to set some values

          //In the MSH segment

           oMSH.SetFieldValue(3, 1, "Sending APP");

          //Is the same as calling

           oMessage.SendingApplication = "Sending APP";

          //likewise this call below

           oMessage.MessageControlID = oController.NewMessageControlID();

          //is the same as calling

           HL7Field msh10 = oMSH.GetField(10, true);

           HL7Component msh10_1 = msh10.GetFieldComponent(1, 1, true);

           msh10_1.Value = oController.NewMessageControlID();

          //...continue and fill out MSH segment

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

          //Add the patient name

           oPID.SetFieldValue(5, 1, "Smith");

           oPID.SetFieldValue(5, 2, "John");

          //...continue and fill out pid segment

          //...and so on until you have created your message

          return;

       }

      private COREUtilities MyUtilities = new COREUtilities();

      private HL7Controller oController = null;

      private HL7Message oMessage = null;

      private COREException LoadAMessage(string fullHL7Message)

       {

          try

           {

              //For our example we will assume that oController has already been created and

              //the license verified.

              //We are also using the object the way that we do. That is to say

              //we create the object at the Class level whenever possible and then

              //reuse it over and over again. Slight performance improvement this way.

              if (oMessage == null)

               {

                   oMessage = oController.NewHL7Message();

               }

              //Right here all I have to do is call the LoadHL7Message method I don't have

              //to clear the message object or anything.

              if (!oMessage.LoadHL7Message(fullHL7Message))

               {

                  //If this fails then we can just return the

                  //COREException object from the message object.

                  return oMessage.LastException.Copy();

               }

              //So the load continued maybe I want to do some extended validation

              //No truly valid HL7 message has 1 segment so I could check for that

              if (oMessage.SegmentCount() < 2)

               {

                  //NOW I might want to clear the message

                   oMessage.Clear();

                  return new COREException("Not enough segments.", "LoadAMessage()", 300198);

               }

              //Maybe I want to check the message type

              if (oMessage.MessageType != "ADT")

               {

                  string badType = oMessage.MessageType;

                  //NOW I might want to clear the message

                   oMessage.Clear();

                  return new COREException("Invalid Message Type " + MyUtilities.SQuote(badType), "LoadAMessage()", 300199);

               }

              //Everything is good enough I will return an empty COREException

              return new COREException();

           }

          catch (Exception ex)

           {

              return new COREException("System Error: " + ex.Message, "LoadAMessage()", 120001);

           }

       }

Individual Properties & Methods Dealing with Control Characters:

NOTE: You can call these properties even if your HL7Message object is empty. If you query or set any of these properties and your message is empty a MSH segment is automatically added!

Example Code C#:

      private void TestMSHSegment()

       {

          //Assume oController has been instantiated elsewhere

           oMessage = oController.NewHL7Message();

          //oMessage is now EMPTY

          int segCount = oMessage.SegmentsCount;

          //segCount == 0

           oMessage.MessageControlID = oController.NewMessageControlID();

           segCount = oMessage.SegmentsCount;

          //segCount == 1 (we automatically added a MSH segment)

       }

Here's a quick, quirky C# code snippet that displays using and reusing disconnected HL7Segment objects.

    private COREUtilities MyUtilities = new COREUtilities();

    private HL7Controller oController = new HL7Controller(LPInternals.ACTIVATIONHANDLE);

    private HL7Message oMessage = null;

    private void TestHL7Segments1()

      {

        string msgs10 = COREAPIExample3.Properties.Resources.AdHocDemoMessages10;

          HL7StringAnalyzer a1 = oController.NewStringAnalyzer(msgs10);

        if (a1.HasException)

          {

            //something went wrong

              FormResults.ErrorMsgBox(a1.LastException.ExtendedErrorMessage);

            return;

          }

          HL7Message msg = a1.GetMessage(1);

          RTF1.Text = msg.Value;

        if (FormResults.QuestionBox("Found " + a1.MessageCount.ToString() + " HL7 Messsages. Showing Message #1. Continue") != DialogResult.Yes) { return; };

        //Now watch closely

        int startAt = 3;

          HL7Segment oSeg = msg.GetSegment(startAt);

        //Oseg is now connected to the message

          oSeg = msg.RemoveSegment(oSeg.Index);

        //Oseg is now disconnected from the message

          RTF1.Text = msg.Value;

        if (FormResults.QuestionBox("Removed the " + oSeg.SegmentName + " segment. Continue") != DialogResult.Yes) { return; };

          oSeg = msg.AddSegment(oSeg);

        //Oseg is now connected to the message again

          RTF1.Text = msg.Value;

        if (FormResults.QuestionBox("Added the " + oSeg.SegmentName + " segment to "  +

            "the end (Position " + oSeg.Index.ToString() + "). Continue") != DialogResult.Yes) { return; };

          oSeg = msg.RemoveSegment(oSeg.Index);

        //Oseg is now disconnected from the message

          RTF1.Text = msg.Value;

        //Save off the current segment count

        int iRestoreTo = msg.SegmentsCount;

        if (FormResults.QuestionBox("Removed the " + oSeg.SegmentName + " segment again. Continue") != DialogResult.Yes) { return; };

        for (int i = 0; i < 50; i++)

          {

            //Adding 50 copies

              _ = msg.AddSegment(oSeg);

          }

        //and oSeg is STILL disconnected

          RTF1.Text = msg.Value;

        if (FormResults.QuestionBox("Added 50 " + oSeg.SegmentName + " segments. Continue") != DialogResult.Yes) { return; };

        while (msg.SegmentsCount > iRestoreTo)

          {

              msg.RemoveSegment(msg.SegmentsCount);

          }

          RTF1.Text = msg.Value;

        if (FormResults.QuestionBox("I removed all the " + oSeg.SegmentName + " segments I just added. Continue") != DialogResult.Yes) { return; };

        //Now I'm going to put it back where I started!

          oSeg = msg.InsertSegmentAt(startAt, oSeg);

        //oSeg is now a connected to the HL7 message at position 3

          RTF1.Text = msg.Value;

          FormResults.MsgBox("And I've restored the message to as it was when I started!", "Done");

          a1.Clear();

        return;

      }

Notes regarding the RawValue property and SaveRawValue() method.

The RawValue property will only be populated ONCE when the HL7 message is initially created. Any subsequent modification of the HL7 message values through setting individual field properties or adding or removing segments will not be reflected.

Example Code (C#):

      private COREUtilities MyUtilities = new COREUtilities();

      private HL7Controller oController = null;

      private HL7Message oMessage = null;

      private void TestRawValue()

       {

          //Assume oController has been instantiated elsewhere

           oMessage = oController.NewHL7Message();

          //RawValue property is ""

           oMessage.LoadHL7Message("MSH|^~\\&|Hospital|Lab|EMR|733737|20200426211916||ADT^A08|3564006401|P|2.5.1|||AA|AE|");

          //oMessage has 1 segment

          //RawValue is "MSH|^~\\&|Hospital|Lab|EMR|733737|20200426211916||ADT^A08|3564006401|P|2.5.1|||AA|AE|"

           oMessage.SendingApplication = "HOSPITAL2";

          //oMessage still has 1 segment

          //RawValue is STILL "MSH|^~\\&|Hospital|Lab|EMR|733737|20200426211916||ADT^A08|3564006401|P|2.5.1|||AA|AE|"

          //The VALUE property is "MSH|^~\\&|HOSPITAL2|Lab|EMR|733737|20200426211916||ADT^A08|3564006401|P|2.5.1|||AA|AE|"

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

           oPID.SetFieldValue(5, 1, "Smith");

           oPID.SetFieldValue(5, 2, "John");

          //oMessage now has 2 segments.

          //RawValue is STILL "MSH|^~\\&|Hospital|Lab|EMR|733737|20200426211916||ADT^A08|3564006401|P|2.5.1|||AA|AE|"

          //

          //*********Creating a Message From Scratch**********

           oMessage.Clear();

          //RawValue is empty

           oMessage.AddSegment("MSH");

           oMessage.SendingApplication = "HOSPITAL3";

          //etc.

          //etc.

           oPID = oMessage.AddSegment("PID");

           oPID.SetFieldValue(5, 1, "Doe");

           oPID.SetFieldValue(5, 2, "Jane");

          //RawValue is STILL empty because I did not LOAD a message string, I assembled the message

       }