NewGlobal (Transaction function)

From m204wiki
Revision as of 03:33, 14 January 2020 by Alex (talk | contribs) (→‎Usage notes)
Jump to navigation Jump to search

Start new global transaction (Transaction class)

Syntax

%string = %(Transaction):NewGlobal[( [description])] Throws CoordinatorException

Syntax terms

%stringstring
%(Transaction) The class name in parentheses denotes a shared method. NewGlobal can also be invoked via a Transaction object variable, which may be Null.
description A unicode string that describes the global transaction. It's only use is to aid in identifying transactions on the coordinator. The default value of this argument is a null string, e.g. no description.

Usage notes

Typically, a global transaction has an "orchestrator", that is a thread that starts the threads that do the updates in the global transaction. These threads can be started via a web service (HTTP request) or some other mechanism. The orchestrator thread can, itself, participate in the global transaction or not.

In any case, to create a global transaction, the coordinator needs to be told about the global transaction and then assign an XID (global, cross-system id) to the transaction. The NewGlobal method asks the coordinator to start a global transaction, receives the XID from the coordinator and returns that as the method output. This allows a Model 204 thread to act as an orchestrator for a global transaction.

The orchestrator for a global transaction involving Model 204 threads does not have to be a Model 204 thread – it can be, for example, an Imagine thread. If the orchestrator is not a Model 204 thread, a NewGlobal method would not be invoked but its equivalent would be invoked on the orchestrator's platform.

Regardless of where the orchestrator is running, it must send the XID to all threads on any platform participating in the global transaction. This allows those threads to add themselves as branches of the global transaction. Model 204 branches of a global transaction would add themselves to the global transaction by invoking the SetGlobal method before their first update.

Examples

In the following example, a global transaction is started and the XID sent (encapsulated in XML) to systems connected via WebSocket connections %websock1 and %websock2:

%doc is object xmlDoc %xid is string len 64 . . . %xid = %(transaction):newGlobal %doc = new %doc:addElement("startTransaction"):addAttribute("xid", %xid) %websock1:sendWebsocket(%doc:serial, 2) %websock2:sendWebsocket(%doc:serial, 2)