home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer) / NeXT_Developer-3.3.iso / NextLibrary / Documentation / Sybase / DBLIB / Section3 / twophase < prev   
Encoding:
Text File  |  1993-04-22  |  7.7 KB  |  211 lines
  1. .H1 "Programming Distributed Transactions"
  2. .Ih "distributed transactions"
  3. .Ih "transactions, distributed"
  4. .Ih "two-phase commit service"
  5. .Ih "commit service"
  6. The two-phase commit service
  7. allows an application to coordinate
  8. updates among two or more \*Ss.
  9. This initial implementation of distributed transactions
  10. treats separate transactions (which may be on separate
  11. \*Ss) as if they were a single transaction.
  12. The commit service uses one \*S, the ``commit server,''
  13. .Ih "commit server"
  14. as a central record-keeper that
  15. helps the application determine whether 
  16. to commit, or whether to roll back transactions
  17. in case of failure.
  18. Thus, the two-phase commit guarantees 
  19. that either all the databases on the participating
  20. servers are updated or that none of them are.
  21. .LP
  22. A distributed transaction is performed by submitting 
  23. \*N
  24. statements to the \*Ss via \*L routines.
  25. An application
  26. program opens a session with each server, issues the
  27. update commands, and then prepares to commit the transaction.
  28. Through \*L, the application issues to each participating server:
  29. .By
  30. a BEGIN TRANSACTION
  31. with identifying information on the application, the
  32. transaction, and the commit server.
  33. .By
  34. the \*N update statements.
  35. .By
  36. a PREPARE TRANSACTION statement that 
  37. indicates that the updates have been performed and that the
  38. server is prepared to commit.
  39. .Bz
  40. .LP
  41. After the updates have been performed on all the
  42. servers participating in the distributed transaction,
  43. the two-phase commit begins.
  44. In the first phase, all servers agree that they are ready to commit.
  45. In the second phase, 
  46. the application informs the commit service that the transaction is complete
  47. (\f2i.e.,\f1 that the commit will take place),
  48. and a COMMIT TRANSACTION is then issued to all of the servers, causing them to commit.
  49. .LP
  50. If an error occurs between phase one and phase two,
  51. all servers coordinate with the commit service
  52. to determine whether the transaction should be committed or aborted.
  53. .H2 "The Commit Service and the Application Program"
  54. The role of the commit service is to be a single place of record that
  55. helps the application decide whether 
  56. the transaction should be committed or aborted.
  57. .LP
  58. If the \*Ss are all prepared to commit,
  59. the application notifies the commit service to mark
  60. the transaction as committed.
  61. Once this happens,
  62. the transaction is committed despite any failures that
  63. might subsequently happen.
  64. .LP
  65. If any \*S or the application program 
  66. fails before the PREPARE TRANSACTION statement,
  67. the \*S will ROLLBACK the transaction.
  68. If any \*S or the application program fails after 
  69. the PREPARE but before the COMMIT,
  70. the \*S will communicate with the server functioning as the commit service and ask it
  71. whether to ROLLBACK or COMMIT.
  72. .LP
  73. The role of the application program is to deliver the \*N statements
  74. to the \*Ss in the proper order, using the proper \*L routines.
  75. The role of the commit service is to provide a single place where the
  76. commit/rollback status is maintained.
  77. The \*Ss communicate with the commit service only
  78. if a failure happens during the two-phase commit.
  79. .LP
  80. The commit service needs its own DBPROCESS, separate from the
  81. DBPROCESSes used for the distributed transaction, to perform its record-keeping.
  82. Note, however, that the server handling the commit service can also be 
  83. one of the servers participating in the transaction, as long as the 
  84. commit service has its own DBPROCESS.
  85. In fact, all the servers involved in the transaction can be one and the same.
  86. .H2 "The Probe Process"
  87. .Ih "probe process, in two-phase commit"
  88. If any server must recover the transaction,
  89. it initiates a process, \f2probe\f1, that determines the last known
  90. status of the transaction.
  91. After it returns the status of that transaction to the commit service,
  92. the \f2probe\f1 process dies.
  93. The \f2probe\f1 process makes use of \f2stat_xact()\f1, 
  94. the same status-checking routine
  95. that the commit service uses to check
  96. on the progress of a distributed transaction.
  97. .H1 "The Two-Phase Commit Routines"
  98. The routines that make up the two-phase commit service are:
  99. .By
  100. \f2open_commit()\f1 - opens a connection with the commit service.
  101. The routine is given the login ID of the user initiating the
  102. session and the name of the commit service.
  103. It returns a pointer to a DBPROCESS structure used in subsequent
  104. commit service calls.
  105. .By
  106. \f2start_xact()\f1 - records the start of a distributed transaction,
  107. and stores initial information about the transaction (DBPROCESS id,
  108. application name, transaction
  109. name, and number of sites participating) in a lookup table on the commit
  110. server.
  111. It returns the \f2commid\f1 identifying number for the transaction.
  112. .By
  113. \f2build_xact_string()\f1 - builds a name string for use by each
  114. participating \*S for its BEGIN TRANSACTION and PREPARE
  115. TRANSACTION statements.
  116. This string
  117. encodes the application's transaction name, the commit service name,
  118. and the \f2commid\f1.
  119. .By
  120. \f2commit_xact()\f1 - tells the commit service to commit the transaction.
  121. .By
  122. \f2abort_xact()\f1 - tells the commit service to abort the transaction.
  123. .By
  124. \f2remove_xact()\f1 - decrements the count of servers
  125. still participating in the transaction.
  126. .By
  127. \f2close_commit()\f1 - closes the connection with the commit service.
  128. .Bz
  129. .LP
  130. Two additional routines are used for ongoing status reports:
  131. .By
  132. \f2scan_xact()\f1 - returns the status of a single or all distributed transactions.
  133. .By
  134. \f2stat_xact()\f1 - returns the completion status of a distributed transaction.
  135. .Bz
  136. .LP
  137. During the course of a session,
  138. the diagnostic routines \f2scan_xact()\f1 and 
  139. \f2stat_xact()\f1 are
  140. used to check that the commit service carried out the
  141. request.
  142. .LP
  143. The \f2scan_xact()\f1 routine uses the
  144. commit service lookup table, \f2spt_committab\f1,
  145. .Ih "commit service lookup table"
  146. which holds the values of:
  147.  
  148. .nf
  149.     - the transaction id
  150.     - the time the transaction started
  151.     - the last time the row was updated
  152.     - the number of servers initially involved in the transaction
  153.     - the number of servers that still have not completed
  154.     - the status ('a'-abort, 'c'-commit, 'b'-begin)
  155.     - the application name
  156.     - the transaction name
  157. .sp
  158. .LP
  159. The two-phase commit routines
  160. call internal stored procedures (\f2e.g.\f1, \f2sp_start_xact\f1)
  161. that are created in each server's master database.
  162. The \f2installmaster\f1 script creates the commit service
  163. lookup table and stored procedures in each server's master database,
  164. for use whenever that server becomes a commit server.
  165. .H2 "Specifying the Commit Server"
  166. .mc |
  167. The commit server must have an entry in the \f2interfaces\f1 file
  168. .Ih "interfaces file for commit server"
  169. .Ih "commit server, interfaces file for"
  170. on each machine participating in the distributed transaction.
  171. On the machine on which the commit server is actually running, the commit server
  172. entry must specify the usual ports described in the \f2Installation Guide\f1, 
  173. including a query port.
  174. For example:
  175. .SD
  176. .ne 6
  177. .ta +8n +8n
  178. .in +3n
  179. SERVICE
  180.     console tcp sun-ether rose 2002 
  181.     master tcp sun-ether rose 2001 
  182.     debug tcp sun-ether rose 2003 
  183.     query tcp sun-ether rose 2001 
  184. .in -3n
  185. .ED
  186. On any additional machines containing other servers participating in the distributed
  187. transaction, the commit server entry need specify only the query port:
  188. .SD
  189. .ne 8
  190. .ta +8n +8n
  191. .in +3n
  192. SERVICE
  193.     query tcp sun-ether rose 2001
  194.  
  195. SITEA
  196.     console tcp sun-ether gaia 2012 
  197.     debug tcp sun-ether gaia 2013 
  198.     master tcp sun-ether gaia 2011 
  199.     query tcp sun-ether gaia 2011 
  200. .in -3n
  201. .ED
  202. The name of the commit server (in these examples, ``SERVICE'') is used as a parameter in calls to
  203. the \f2open_commit()\f1 and \f2build_xact_string()\f1 routines.
  204. The commit server name must be the same on all machines participating in
  205. the transaction.
  206. The name cannot contain a period (``.'') or a colon (``:'').
  207. .H2 "Two-Phase Commit Example Program"
  208. The \f2\*L Reference Supplement\f1 contains an example program illustrating
  209. the two-phase commit service.
  210. .mc
  211.