Functionality and Architecture

Functionality

Exactly one Fabasoft Folio Distributed Transaction Manager is needed for one distributed transaction. In a Fabasoft Folio installation each Fabasoft Folio COO Service can also be a Fabasoft Folio Distributed Transaction Manager (1:1 relationship).

The Fabasoft Folio Kernel is responsible for performing distributed transactions. At the beginning of a distributed transaction the Fabasoft Folio Kernel chooses exactly that Fabasoft Folio COO Service as Fabasoft Folio Distributed Transaction Manager which is involved in the distributed transaction and has the highest instance number.

Example: If the Fabasoft Folio COO Services with the instance numbers 1, 2 and 4 are involved in the distributed transaction, the Fabasoft Folio Distributed Transaction Manager of the Fabasoft Folio COO Service with the instance number 4 is used.

The Fabasoft Folio Distributed Transaction Manager is implemented on the basis of the XA protocol.

Architecture

(1) COOSTDTMTransactionBegin
Starts a distributed transaction. Input parameter: instancelist; Output parameter: XID

(2) COOSTTransactionInitDTC
Starts a transaction with MSDTC/FSCDTM

(3) COOSTTransactPartStart
Starts a new part of a transaction.

(4) COOSTTransactPartExec
Runs the defined part of a transaction since the last call of COOSTTransactPartStart.

(5) COOSTDTMResourcePrepare
Prepares an involved resource for a “Commit”.

(6) COOSTDTMTransactionEnd
Informs the Fabasoft Folio Distributed Transaction Manager about a successful “Prepare”

(7) COOSTDTMResourceEnd
Closes the local transaction of a resource with “Commit” or “Rollback”. Update of the cache.

(8) COOSTDTMTransactionEnd
Informs the Fabasoft Folio Distributed Transaction Manager about a successful “Commit” or “Rollback”

(9) COOSTTransactionClose
Transaction is marked in the service as “closed”. RPC-transaction will be closed.

Log File

In order to close open distributed transactions accordingly after a system crash, a log about all performed transactions is created. The path to this log file can be configured explicitly for each Fabasoft Folio COO Service. The Fabasoft Folio Distributed Transaction Manager performs periodically a “Recover” of open transactions.

The filename of the log file is created the following way:
FSCDTM_<cooservice>.dtm  (e.g. FSCDTM_COOService_1_1190_2.dtm)

The log file starts with a header containing among others the creation date of the log:

Example: FSCDTM 1.0 Transaction Log 2006-07-25T09:44:32

After this entry a list of distributed transactions follows. Each entry from the list can contain the following information:

• Status flags about the transaction
  • T…transaction
  • I…initialized (transaction was started)
  • P…prepared (transaction was prepared)
    or
    O…transaction was prepared but one or more resources answered with “read-only”
  • C…committed (transaction has been finished)
    or
    R…Rolled back (transaction has been reset)

A transaction is finished if it is closed or reset.

• Start time of the transaction
  UTC time displaying when the transaction has been started. It is also used to calculate the timeouts.
• XID
  The global identification of the transaction.
• Involved resources
  All resources (instance numbers of Fabasoft Folio COO Services) involved in the transaction. The resources are written in an own line.

Example for a log file:

The color bordered part represents an entry for a transaction in the log file. The entry displays a transaction (T), which was initialized (I), prepared (P) and finally closed (C). Then the start time of the transaction is displayed followed by the global identification, the XID. In the line below the involved resources are mentioned. In this case these are the Fabasoft Folio COO Services with the instance numbers 1 and 2.

Syntax of the log file:

   Log =

     EntryWelcome { EntryTransaction EntryResource { EntryResource } }.

   EntryWelcome =

     Prolog Blank TimeStamp Padding.

   Prolog =

     "FSCDTM 1.0 Transaction Log".

   EntryTransaction =

     "T" Initiated Prepared Completed TimeStamp Blank GlobalTransationId Padding

   Initiated =

     1  x (I | Blank).

   Prepared =

     1  x (P | O | Blank).  -- P prepared, O prepared with read-only votes

   Completed =

     1  x (C | R | Blank).  -- C committed, R rolled back

   TimeStamp =

     19 x (0123456789T:-). -- Date formatted YYYY-MM-DDThh:mm:ss

   GlobalTransationId =

     32 x (0-9A-F).  -- typedef struct { int gtrid[4];  } DTMGTRID;   BinHex coded

   EntryResource =

     "R" Resources Padding.

   Resources =

     Resource { ',' Resource };

   Resource =

     (0-9)*.

   Blank =

     ' '.

   Padding =

     Blank till LENGTH_LOGENTRY-1 bytes are reached, followed by '\n'

   -- Required minimal size of entry: 1 + 1 + 1 + 1 + 19 + 1 + 32 = 56 bytes

Example: Recovery

Assuming that a distributed transaction has successfully prepared all involved transaction parts. Suddenly at “Commit” an involved database is not available anymore.

In the log file the following entry is created:

The first four letters show that the transaction (T) was initialized (I) and prepared (P), but neither a rollback (R) nor a commit (C) were performed.

It is also possible to access information about open distributed transactions via the DBA_2PC_PENDING view in the Oracle database instance:

Comparing the XID in the log file and the one in the DBA_2PC_PENDING view shows, that it is the same transaction and that this one has the “prepared” state in the database too.

The “commit” failed during the transaction, so a periodically running recovery thread tries to close the transaction now. After a successful transaction closing the entry in the log file changes:

Now the “C” shows, that the transaction has been closed.

The DBA_2PC_PENDING view does not contain entries about open distributed transactions any longer.