NewGlobal (Transaction function): Difference between revisions
(Automatically generated page update) |
No edit summary |
||
| Line 1: | Line 1: | ||
{{Template:Transaction:NewGlobal subtitle}} | {{Template:Transaction:NewGlobal subtitle}} | ||
Start a new global transaction. | |||
==Syntax== | ==Syntax== | ||
{{Template:Transaction:NewGlobal syntax}} | {{Template:Transaction:NewGlobal syntax}} | ||
| Line 10: | Line 9: | ||
<td>The class name in parentheses denotes a shared method. <var>NewGlobal</var> can also be invoked via a <var>Transaction</var> object variable, which may be <var>Null</var>.</td></tr> | <td>The class name in parentheses denotes a shared method. <var>NewGlobal</var> can also be invoked via a <var>Transaction</var> object variable, which may be <var>Null</var>.</td></tr> | ||
<tr><th>description</th> | <tr><th>description</th> | ||
<td> | <td>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.</td></tr> | ||
</table> | </table> | ||
==Usage notes== | ==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 <var>XID</var> (global, cross-system id) to the transaction. The <var>NewGlobal</var> 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 <var>Imagine</var> thread. If the orchestrator is not a Model 204 thread, a <var>NewGlobal</var> 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. | |||
==Examples== | ==Examples== | ||
== | In the following example, a global transaction is started and the XID sent (encapsulated in XML) to systems connected via WebSocket connections <code>%websock1</code> and <code>%websock2</code>: | ||
<p class="code">%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) | |||
</p> | |||
{{Template:Transaction:NewGlobal footer}} | {{Template:Transaction:NewGlobal footer}} | ||
Revision as of 23:40, 13 January 2020
Start new global transaction (Transaction class)
Start a new global transaction.
Syntax
%string = %(Transaction):NewGlobal[( [description])] Throws CoordinatorException
Syntax terms
| %string | string |
|---|---|
| %(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.
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)