Defining Data Flow Through Messages

This section covers the behavior of data and message flows. A message definition is created when an Action shape is connected to a port. These message definitions appear on the Data page. We looked at an example of such a page earlier in Figure 10.2, and you should now be familiar with many of the concepts.

Two wizards in the BizTalk Orchestration Designer guide you through the process of defining a message. The XML Communication Wizard defines messages used for sending or receiving over messaging services, such as BizTalk Messaging and MSMQ queues. The Method Communication Wizard defines messages used in making calls to or receiving calls from COM components. The wizards consist of pages shown in succession. We will look at each of these wizards next.

XML Communication Wizard

The XML Communication Wizard has five pages. The first page is the Welcome to the XML Communication Wizard. On this page, you specify whether the message is to be sent or received. For a port using BizTalk Messaging Services, the direction of message flow is dictated by the port; you cannot change this. On this page, you can also specify a latency value if you are going to receive messages through this port. By default, this latency is 0 seconds, which is the time that the engine expects to wait for a message to arrive on the port. The default latency of 0 seconds means that the message is expected to arrive immediately. A latency of greater than 180 seconds causes a schedule instance to dehydrate immediately; a smaller value means that the schedule will never dehydrate (unless forcibly dehydrated; see Chapter 11 to see how this can be done).

The next page of the wizard is Message Information. On this page, you specify the name of the message to use. You can choose to create a new message or use an existing message for this communication action. Note that a message is the only way data is passed into or out of the schedule. If an Action is not executed, the corresponding message is not created. Multiple Actions can share a message going through any port connected to a messaging implementation.

The third page of the wizard is XML Translation Information. On this page, you select whether you want to send messages in XML. Although you have the option of passing non-XML messages, the XLANG Scheduler Engine uses XML natively for processing all messages. Therefore, to use a non-XML message, you must apply (or remove) an XML wrapper around the message before (or after) the engine processes the message. The engine automatically manages the wrapper after you define the wrapper as a constant on the Data page and make the appropriate connections. See the discussion of StringData in the section “System and Special Fields.” Where possible, using XML messages is preferred because of the added flexibility of using XPath expressions; see the description for the last page of the wizard.

The next page is Message Type Information. On this page, you assign a message type label. The XLANG Scheduler Engine uses this label for message type identification. This label property can be used to optimize the performance of a schedule as follows. If the message type label does not match the XML root element of the message schema, then the engine examines the contents of the actual message and picks only those messages whose root elements are specified by the schema. On the other hand, if the label does match, no such filtering is done. This message label is particularly useful with MSMQ queues, where a label is associated with a message and a program can peek at a message in the queue without retrieving it. The property Use instance id as message label is used for correlation, described in Chapter 16. The message schema is specified on the next and final page of the wizard.

The last page of the wizard is Message Specification Information. This page is not shown if you chose to handle non-XML messages. On this page, you can optionally specify a document specification (built using the BizTalk editor) to validate the message or to pick apart the message fields. Figure 10.7 shows this page.

Figure 10.7 shows that the CommonPO.xml message specification was selected. You can validate incoming messages against this specification by selecting the check box. Inside the Message Fields group, you can see the fields that will be available in the message on the Data page. The first two fields (__Sender__ and Document) are always available. You can add more fields using XPath expressions to identify portions of the XML message. These fields can be used for building Rule expressions, or flowing the field to other messages in the schedule. Note that, if you pick apart fields like this, then, for an outgoing message, each field must be filled before the message can be sent.

The XPath expression must result in a scalar of an XLANG supported data type. You cannot select, for example, an XPath expression that results in an XML fragment as a message field.

Method Communication Wizard

The Method Communication Wizard has three pages. The Method Communication Wizard appears when you connect an action to a port using the COM component.

The first page, Welcome to the Method Communication Wizard, is functionally identical to the first page of the XML Communication Wizard. On this page, you specify whether the port is going to make an outgoing call or whether it is going to wait for an incoming call. As before, you can specify an expected latency period that governs how the schedule is dehydrated.

The second page is Message Information, as in the case of the XML Communication Wizard. On this page, you choose either to create a new message or reuse an existing message. You can reuse only the messages used for making or receiving method calls over the current port. You cannot share messages across ports.

The last page is Message Specification Information. It serves a similar purpose as the last page of the XML Communication Wizard. It is shown in Figure 10.8.

The message structure and the fields shown on the Data page are dictated by the method signature. The port represents a chosen interface of the COM component, and it can have many methods. You choose a specific method of this interface by picking it in the drop-down list box. The selected method determines the fields of the message. The selected fields are shown in the IN fields and the OUT fields portions of the wizard page.

For Visual Basic implementations, the IN fields contain all ByVal and ByRef parameters. The OUT fields contain only the ByRef parameters and function return values. For components implemented with scripting technology, all arguments are passed by reference, and therefore all arguments appear in both the IN and the OUT fields of the message.

For C/C++ implementations, the IN fields contain all [in] or [in, out] parameters as specified by the IDL. The OUT fields contain only the parameters with [out] or [retval] attributes.

If a field is present in both the IN and OUT parts of the message, then the IN part contains the pre-call, supplied, value, and the OUT part contains the post-call, returned, value. Recall that a message can either flow in from the port (a call into the schedule) or flow out (a call from the schedule). The IN fields are filled by the caller, and the OUT fields are filled by the callee to return the results.

Field Data Types

The following data types are supported in the message fields. The first column of Table 10.2 shows the data types denoted in the XLANG schedule; the other columns show corresponding data types in Automation and other languages.

Table 10.2. Data Types in an XLANG Schedule

XLANG	Automation	Visual Basic	C
Boolean	VT_BOOL	Boolean	VARIANT_BOOL
String	VT_BSTR	String	BSTR
Cy	VT_CY	Currency	CURRENCY
Date	VT_DATE	Date	Date
Dispatch	VT_DISPATCH	Object	IDispatch
Error	VT_ERROR		SCODE or HRESULT
I1	VT_I1		Signed char
I2	VT_I2	Integer	SHORT
I4	VT_I4	Long	LONG
Int	VT_INT		INT
R4	VT_R4	Single	FLOAT
R8	VT_R8	Double	DOUBLE
Ui1	VT_UI1	Byte	BYTE
Ui2	VT_UI2		USHORT
Ui4	VT_UI4		ULONG
Uint	VT_UINT		UINT
Unknown	VT_UNKNOWN	Object	IUnknown
Variant	VT_VARIANT	Variant	VARIANT

The data types of Base64, Binary, ID, IDREF, IDREFS, Enumeration, i8, and ui8, which are supported by BizTalk Messaging Services, are not supported by XLANG schedules.

Note that XLANG schedules can pass COM interface pointers via messages; however, only the supported interface types are passed.

System and Special Fields

In some examples earlier (for example, refer to Figure 10.2 or Figure 10.5), you saw messages with system-defined fields. These fields are provided by the XLANG implementation in addition to the fields required for message passing and method calls. Table 10.3 gives a summary of all such system or special fields.

Table 10.3. System and Special Fields

System Field	Description
__Status__	Returned status from a component. This is the SCODE or HRESULT and is included in the call return portion of a message pair.
__Sender__	Sender's authenticated identity as a String data type. The field is optionally checked by the receiver or callee of a message.
Document	The entire XML document as a String data type.
StringData	This is a special field defined when the document is not of XML form. The XLANG Scheduler Engine binds the non-XML document to this field. The non-XML document is wrapped as an element inside an XML wrapper. This wrapped entity, which is a well-formed XML document, is the preceding Document field. The wrapping XML fragment is an XLANG Scheduler Engine standard wrapper and is always <?xml version="1.0" ?><StringData></StringData>. The non-XML document is the value of the StringData element. To send non-XML messages, you must create a constant as the standard wrapper and connect it to the Document field of the outgoing message.
__Exists__	A test for whether a message exists.

Constants

The Constants message is a bag of named constant values for use within the Data page of the schedule. You can populate message fields with these values. Field values of the Constants message support additional data types that facilitate exchange of messages with the BizTalk Messaging Services. These additional data types are listed in Table 10.4.

Table 10.4. Additional Data Types for Constants

Data Type	Description
Fixed Point (14.4)	A data type useful for currency values. It can have at most 14 digits to the left of the decimal point and 4 digits to the right of the decimal point.
Time, Time.tz, Date time, and Date time.tz	These are four different data types. The format is a subset of the ISO 8601 format. Time has no date or time zone information. Time.tz is like Time but with time zone information. Similarly, for Date time and Date time.tz. Example: 2001-03-03T17:28:00-05:00
URI	Short form for Uniform Resource Identifier.
UUID	Short form for Universal Unique Identifier.

You can define constants of these data types and use them to plug in values in messages or parts of messages sent out by the schedule. The constants can also be used as part of Rule expressions.

Specifying Data Flow

After messages are created and displayed on the Data page, you can connect fields to show where data should flow. The arrow connecting the fields starts from the right of the source field to the left of the destination field. The movement of data, however, is tied to the actions being executed by the schedule—only those messages being sent or received by the action are populated with data flows.

A field can receive data from only one field; however, it can send data to many fields. The field providing data must have previously received data. In other words, a field is not valid unless a prior action caused it to be populated. You can check whether a message was received by using the __Exists__ system field in a Rule.

Outgoing messages must have all their fields populated. The value of the field is not of consequence (it may be empty or null); it is important that the source of data needed to populate the field be specified in the drawing.