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.

Hint: The serialization flag fields in an eConnect serialization class always append the word "Specified" to the name of the field that the boolean flag targets.

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