HL7PlusField

*All example code is in Visual Basic.Net

'Where MyController is a HL7PlusController object

Dim oMSg As HL7PlusMessage = MyController.NewHL7PlusMessage()

If IsNothing(oMSg) Then

MessageBox.Show("An Error Occurred: " & MyController.LastError, "Error")

Return

End If

'oMsg is now an EMPTY HL7 message.

'From this point on we don't have to worry about HL7PlusController Errors

'In an EMPTY message I MUST add the MSH segment first

Dim oMSH As HL7PlusSegment = oMSg.AddEmptySegment("MSH")

'---------------------------------

'The following 3 snippets do EXACTLY the same thing

'-----------#1---------------

oMSH.Field(9).ComponentValue(1) = "ADT"

oMSH.Field(9).ComponentValue(2) = "A01"

'-----------#2---------------

Dim oFld9 As HL7PlusField = oMSH.Field(9)

With oFld9

.ComponentValue(2) = "A01"

.ComponentValue(1) = "ADT"

End With

'-----------#3---------------

'I can also just set the VALUE property with the raw

'value for the entire field. Useful for fields with only 1

'component, but can be used for compound fields as well.

'This only works if ComponentDelimiter is ^

oFld9.Value = "ADT^A01"

MessageBox.Show(oMSH.Field(9).Value, "Field 9 of the MSH Segment")

Property Name	Data Type	Description
Component	HL7PlusComponent	While this property is read-only you can change the value(s) contained in the field. This property also takes up to 3 parameters. Parameter 1: Index (Int32) the index starting with Component #1. Parameter 2: OPTIONAL Instance (Int32) HL7 fields can repeat. Which Instance of the Field are you querying. The default is 1. Parameter 3: OPTIONAL blnPadToIfNotPresent (Boolean) Default is TRUE. This parameter is very important. If you set it to False and there is no Component(Index) OR FieldInstances < Instance then Nothing is returned. If it is set to TRUE (the Default) then before the object is returned to you everything will be padded out so that no error is created. See Working With Repeating Fields below
ComponentValue	String	Get / Set the String value of a particular HL7PlusComponent within the HL7PlusField. This property also takes 2 parameters. Parameter 1: Index (Int32) The index starting with Component #1. Parameter 2: OPTIONAL Instance (Int32) HL7 fields can repeat. Which Instance of the Field are you querying. The default is 1. NOTE: When SETTING the ComponentValue if the Component(INDEX) does not exist or if FieldInstances < Instance they will be created automatically.
FieldInstances	Int32	The number of repeating instances the field object contains
FieldRepeats	Boolean	Does the field contain more than 1 instance (True or False)
Index	Int32	The Index of the HL7PlusField object. Will also be the ordinal position of the field within the segment. NOTE: The Segment NAME does not count as a field. See the NAME property of the HL7PlusSegment object.
InstanceValue	String	Get / Set the raw String value of 1 particular HL7PlusField Instance. This property takes 1 parameter. Parameter 1: Instance (Int32) Which field instance are you getting / setting. NOTE: When SETTING the InstanceValue if FieldInstances < Instance the instances will be padded to Instance.
ParentSegment	HL7PlusSegment	The parent HL7PlusSegment object which contains the field.
Value	String	Get / Set the entire raw value of the HL7PlusField. Using this property to Set the HL7PlusField value should be considered an advanced option. It is possible to corrupt your message doing this.
ValueIsValid	Boolean	Evaluates the Value of the object to determine if it contains invalid data (IE Encoding Characters)

Method:	Clear()
Paramters:	None
Return Value:	None
Description:	Clears the HL7PlusField object. Equivalent to setting Value = ""

Method:	PadInstancesTo(MaxInstances)
Paramters:	1: MaxInstances (Int32)
Return Value:	Boolean
Description:	Adds empty("") repeating instances to the HL7PlusField object until FieldInstances = MaxInstances

Method:	RemoveInstance(Instance)
Paramters:	1: Instance (Int32)
Return Value:	Boolean
Description:	Removes repeating instance # Instance from the HL7PlusField object. NOTE: Instance must be > 1 AND <= FieldInstances or a HL7PlusException is created.

Method:	Scrub(OPTIONAL ScrubAllEscapes = False, Optional ScrubAllSubComponents = False, Optional ScrubAllRepeats = False)
Paramters:	1: OPTIONAL ScrubAllEscapes Boolean- Default = False. 2: OPTIONAL ScrubAllSubComponents Boolean- Default = False. 3: OPTIONAL ScrubAllRepeats Boolean- Default = False.
Return Value:	Boolean
Description:	Scrubs the Field object of invalid corrupting data. See Validating Data for Scrub Rules.

Method:	ScrubAValue(ValueToScrub, OPTIONAL ScrubAllEscapes = False, Optional ScrubAllSubComponents = False, Optional ScrubAllRepeats = False)
Paramters:	1: ValueToScrub - String. The string value to perform the Scrub operation on. 2: OPTIONAL ScrubAllEscapes Boolean- Default = False. 3: OPTIONAL ScrubAllSubComponents Boolean- Default = False. 4: OPTIONAL ScrubAllRepeats Boolean- Default = False.
Return Value:	String - Returns the scrubbed ValueToScrub.
Description:	Scrubs ValueToScrub of invalid corrupting data. See Validating Data for Scrub Rules.

Method:	SetFieldValue(ListOfValues, Instance) + 1 OverLoad SetFieldValue(ListOfListOfValues)
Paramters:	1: ListOfValues ( .Net List (Of String) ) 1: ListOfListOfValues ( .Net List (List (Of String)) ) 2: Instance (Int32)
Return Value:	None
Description:	Removes repeating instance # Instance from the HL7PlusField object. NOTE: Instance must be > 1 AND <= FieldInstances or a HL7PlusException is created.

Method:	TrimInstancesTo(MaxInstances)
Paramters:	1: MaxInstances (Int32)
Return Value:	Boolean
Description:	Removes repeating instances from the HL7PlusField object until FieldInstances = MaxInstances NOTE: Calling TrimInstancesTo(0) is the same as calling Clear().

This object class uses our standard HL7PlusException Class interface for error handling wherever possible.

See the HL7PlusException Implementation Reference

*All example code is in Visual Basic.Net

'Where MyController is a HL7PlusController object

Dim oMSg As HL7PlusMessage = MyController.NewHL7PlusMessage()

If IsNothing(oMSg) Then

MessageBox.Show("An Error Occurred: " & MyController.LastError, "Error")

Return

End If

'oMsg is now an EMPTY HL7 message.

'From this point on we don't have to worry about HL7PlusController Errors

'In an EMPTY message I MUST add the MSH segment first

Dim oMSH As HL7PlusSegment = oMSg.AddEmptySegment("MSH")

'---------------------------------

'The following 3 snippets do EXACTLY the same thing

'-----------#1---------------

oMSH.Field(9).ComponentValue(1) = "ADT"

oMSH.Field(9).ComponentValue(2) = "A01"

'-----------#2---------------

Dim oFld9 As HL7PlusField = oMSH.Field(9)

With oFld9

.ComponentValue(2) = "A01"

.ComponentValue(1) = "ADT"

End With

'-----------#3---------------

'I can also just set the VALUE property with the raw

'value for the entire field. Useful for fields with only 1

'component, but can be used for compound fields as well.

'This only works if ComponentDelimiter is ^

oFld9.Value = "ADT^A01"

MessageBox.Show(oMSH.Field(9).Value, "Field 9 of the MSH Segment")

*All example code is in Visual Basic.Net

'Where MyController is a HL7PlusController object

Dim oMsg As HL7PlusMessage = MyController.NewHL7PlusMessage(MyController.ExampleHL7MessageString)

If IsNothing(oMsg) Then

MessageBox.Show("An Error Occurred: " & MyController.LastError, "Error")

Return

End If

'oMsg is now and EMPTY message

Dim oMSH As HL7PlusSegment = oMsg.AddEmptySegment("MSH")

'...Code...

Dim oEVN As HL7PlusSegment = oMsg.AddEmptySegment("EVN")

'...Code...

'-------------

'Make the PID segment

Dim oPID As HL7PlusSegment = oMsg.AddEmptySegment("PID")

'...Code...

'WAIT! We now have to do a repeating field for example

'PID field 9, the Patient Alias.

'Our HL7 message is for Billy The Kid.

Dim oFld9 As HL7PlusField = oPID.Field(9)

'Our Name Values First Alias

Dim oLst1 As New List(Of String)

oLst1.Add("Bonney") '--Last Name

oLst1.Add("William") '--First

oLst1.Add("H") '--Middle

'Second Alias Name

Dim oLst2 As New List(Of String)

oLst2.Add("Kid") '--Last Name

oLst2.Add("Billy") '--First

oLst2.Add("The") '--Middle

With oFld9

'-------Method 1---------

'We can just set the first instance like this

.ComponentValue(1) = oLst1(0)

.ComponentValue(2) = oLst1(1)

.ComponentValue(3) = oLst1(2)

'--OR LIKE THIS

.ComponentValue(1, 1) = oLst1(0)

.ComponentValue(2, 1) = oLst1(1)

.ComponentValue(3, 1) = oLst1(2)

'NOW set the repeating instance like so

.Component(1, 2).Value = oLst2(0)

.Component(2, 2).Value = oLst2(1)

.Component(3, 2).Value = oLst2(2)

'--OR LIKE THIS

.ComponentValue(1, 2) = oLst2(0)

.ComponentValue(2, 2) = oLst2(1)

.ComponentValue(3, 2) = oLst2(2)

MessageBox.Show(.Value, "Field 9 Value")

.Clear() ' Start over

'-------Method 2--Using Lists (of String)-------

.SetFieldValue(oLst1, 1)

.SetFieldValue(oLst2, 2)

MessageBox.Show(.Value, "Field 9 Value Set with 2 lists")

.Clear() ' Start over

'-------Method 3--Using A List (Of List(of String))-------

Dim oLst3 As New List(Of List(Of String))

oLst3.Add(oLst1)

oLst3.Add(oLst2)

.SetFieldValue(oLst3)

MessageBox.Show(.Value, "Field 9 Value Set with List(of List)")

.Clear() ' Start over

'Finally, If you're really good you can set the whole

'field with pre-formatted HL7 values

'This ONLY works if ComponentDelimiter is ^

'AND RepeatDelimiter is ~

Dim strFld9 As String = "Bonney^William^H~Kid^Billy^The"

oFld9.Value = strFld9

MessageBox.Show(.Value, "Field 9 Value Set Directly")

End With

Class Name:	HL7PlusField
HL7+ Category:	Restricted (Accessed through the HL7PlusSegment object)
Description:	Object representation of 1 Field in a HL7PlusSegment