Message.UpdateField

Method

Visual Basic

Overloads Public Sub UpdateField(
    ByVal messageField As MessageField)
Overloads Public Sub UpdateField(
    ByVal fieldName As String,
    ByVal fieldValue As value_type)
Overloads Public Sub UpdateField(
    ByVal messageField As MessageField,
    ByVal fieldValue As value_type,
    ByVal fieldId As UInt16)

C#

public void UpdateField(MessageField messageField);
public void UpdateField(
    string fieldName,
    value_type  fieldValue);
public void UpdateField(
    string fieldName,
    value_type  fieldValue,
    ushort fieldId);

Purpose

Update a field within a message.

Remarks

This method copies the new data into the message field.

This method locates a field within the message by matching the fieldName and fieldId arguments. Then it updates the message field using the fieldValue argument. (Notice that only the value of the message field can change.)

If no existing field matches the specifications in the fieldName and fieldId arguments, then this method adds a new field to the message.

The type of the existing message field and the value_type of the updating fieldValue argument must be identical; otherwise, the method throws an exception with the error status code InvalidType. However, when updating array or vector fields, the count (number of elements) can change.

Parameter	Description
fieldName	Update a field with this name. When absent, locate the field by identifier only.
fieldValue	Update a field using this data value. It is illegal to add or update a field with null data. To remove a field, use Message.RemoveField.
fieldId	Update a field with this identifier. All field identifiers must be unique within each message. Zero is a special value, indicating no identifier. It is illegal to add a field that has both a null field name, and a non-zero field identifier.

Field Search Algorithm

The method uses this algorithm to find and update a field within a message, as specified by a field identifier and a field name.

Procedure 

1.

If the program supplied MessageField.NoSpecificId (zero) as the identifier, or omitted any identifier, then begin at step 3.

If the program supplied a non-zero field identifier, then search for the field with that identifier.

If the search succeeds, then update that field.

On failure, continue to step 2.

2.

If the identifier search (in step 1) fails, and the program supplied a non-null field name, then search for a field with that name.

If the search succeeds, then update that field.

If the name search succeeds, but the actual identifier in the field is non-null (so it does not match the identifier supplied) then throw an exception with the status code IDConflict.

If the search fails, add the field as specified (with name and identifier).

However, if the program supplied null as the field name, then do not search for the field name; instead, throw an exception with the status code NotFound.

3.

When the program supplied MessageField.NoSpecificId (zero) as the identifier, or omitted any identifier, then begin here.

Search for a field with the specified name—even if that name is null.

If the search fails, add the field as specified (with name and identifier).

If a message contains several fields with the same name, searching by name finds the first instance of the field with that name.

Nested Message

When the new value is a message object, this method uses only the data portion of the nested message (fieldValue); it does not include any address information or certified delivery information.

Top