Message.GetFieldInstance

Method

Visual Basic

Public Function GetFieldInstance(
    ByVal fieldName As String,
    ByVal instanceNumber As UInt32
) As MessageField

C#

public MessageField GetFieldInstance(
    string  fieldName,
    uint    instanceNumber)

Purpose

Get a specific instance of a field from a message.

Remarks

When a message contains several field instances with the same field name, retrieve a specific instance by number (for example, get the i^th field named foo). Programs can use this method in a loop that examines every field with a specified name.

The argument 1 denotes the first instance of the named field.

The method takes a snapshot of the field, and returns that information as a MessageField object. To obtain the value of the field, programs can either extract the Value property from the MessageField object explicitly, or implicitly extract its Value by assigning the object to a variable; see Implicit Conversions.

When the instance argument is greater than the actual number of instances of the field in the message, this method throws an exception.

Release 5 Interaction

Rendezvous 5 (and earlier) did not support array datatypes. Some older programs circumvented this limitation by using several fields with the same name to simulate arrays. This work-around is no longer necessary, since release 6 (and later) supports array datatypes within message fields. The method Message.GetFieldInstance ensures backward compatibility, so new programs can still receive and manipulate messages sent from older programs. Nonetheless, we encourage programmers to use array types as appropriate, and we discourage storing several fields with the same name in a message.

Parameter	Description
fieldName	Get an instance of the field with this name. Null specifies the empty string as the field name.
instanceNumber	Get this instance of the specified field name. The argument 1 denotes the first instance of the named field.

See Also

MessageField