Using serialization flags

Several classes in the eConnect serialization namespace include fields called serialization flags. A serialization flag is a boolean member of the class that you use to specify whether to use or discard the value assigned to a related field.

To update a field that has a serialization flag, you assign a value to the field and set the value of the related serialization flag to True. The serialization flag instructs the business object to use the value you assigned to the field to update the record in the database. If you set the serialization flag to False or do not include the serialization flag, the value you supply in the class field is not used.

You use serialization flags when the underlying eConnect business object supports update functionality. Update functionality enables you to update a record by submitting a document that specifies a few fields that have new values. Fields not explicitly included in the update document retain their existing value. For more information about eConnect update functionality, see Using eConnect to update existing data .

The following Visual Basic example illustrates the use of a serialization flag in a .NET development project. Notice the use of the HOLD and HOLDSpecified fields of the taUpdateCreateCustomerRcd class. The value of the HOLD field places a hold on the customer. The value of the HOLDSpecifed field enables the update of the customer hold status. If HOLDSpecified is omitted or is not set to True, the value assigned to HOLD is discarded and the hold status of the customer remains unchanged.

public sub UseSerializationFlag()
	Try

		'**Create a customer document**
		'Use the taUpdateCreateCustomerRcd class to specify 
		‘ the customer update
		Dim customer As New taUpdateCreateCustomerRcd
		With customer
			'Specify the customer
			.CUSTNMBR = "AARONFIT0001"

			'Use the HOLD field to place a hold on the customer
			'Set the serialization flag HOLDSpecifed to True.
			.HOLD = 1
			.HOLDSpecified = True
		End With

		'Add the customer object to the RMCustomerMasterType
transaction type
		Dim customerTransactionType As New RMCustomerMasterType
		customerTransactionType.taUpdateCreateCustomerRcd =
customer

		'Create an array of RMCustomerMasterType and add 
		‘ the customer transaction type object to the array
		Dim mySMCustomerMaster(0) As RMCustomerMasterType
		mySMCustomerMaster(0) = customerTransactionType

		'Add the array of transaction type objects to an 
		‘ eConnect document object
		Dim eConnectDoc As New eConnectType
		eConnectDoc.RMCustomerMasterType = mySMCustomerMaster

		'**Serialize the eConnect document**
		'Create a memory stream for the serialized eConnect
document
		Dim memStream As New MemoryStream()

		'Create an Xml Serializer and serialize the eConnect
document
		‘ to the memory stream
		Dim serializer As New XmlSerializer(GetType(eConnectType))
		serializer.Serialize(memStream, eConnectDoc)

		'Reset the position property to the start of the buffer
		memStream.Position = 0

		'**Load the serialized Xml into an Xml document**
		Dim xmldoc As New XmlDocument()
		xmldoc.Load(memStream)

		'Instantiate an eConnectMethods object
		Dim eConnectObject As New eConnectMethods

		'**Set the connection string**
		'The connection string targets the TWO database on the
local computer
		Dim ConnectionString As String
		ConnectionString="Data Source=localhost; Integrated
Security=SSPI;" _
			& "Persist Security Info=False; Initial
Catalog=TWO;"

		'**Update the customer record**
		'If eConnectResult is TRUE, the XML document was 
		‘ successfully submitted
		Dim eConnectResult As Boolean
	 
eConnectResult=eConnectObject.UpdateEntity(ConnectionString, _
			xmlDoc.OuterXml)

	Catch eConnectError As eConnectException
		Console.Write(eConnectError.ToString())

	Catch ex As System.Exception
		Console.Write(ex.ToString())
	End Try
End Sub