Skip to content

Commit ca8e9c1

Browse files
Improved documentation.
1 parent 49e6938 commit ca8e9c1

File tree

3 files changed

+21
-13
lines changed

3 files changed

+21
-13
lines changed

doc/src/api_manual/connection.rst

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -352,7 +352,7 @@ Connection Methods
352352
explicitly closed using the function :meth:`~Connection.close()`, the
353353
subscription will not be deregistered in the database.
354354

355-
.. method:: Connection.tpc_begin(xid, flags)
355+
.. method:: Connection.tpc_begin(xid, flags, timeout)
356356

357357
Begins a Two-Phase Commit (TPC) on a global transaction using the specified
358358
transaction identifier (xid).
@@ -364,10 +364,19 @@ Connection Methods
364364
:data:`oracledb.TPC_BEGIN_NEW`, :data:`oracledb.TPC_BEGIN_PROMOTE`, or
365365
:data:`oracledb.TPC_BEGIN_RESUME`. The default is :data:`oracledb.TPC_BEGIN_NEW`.
366366

367+
The ``timeout ``parameter is the number of seconds to wait for a transaction to
368+
become available for resumption when :data:`~oracledb.TPC_BEGIN_RESUME` is
369+
specified in the ``flags`` parameter. When :data:`~oracledb.TPC_BEGIN_NEW` is
370+
specified in the ``flags`` parameter, the ``timeout`` parameter indicates the
371+
number of seconds the transaction can be inactive before it is automatically
372+
terminated by the system. A transaction is inactive between the time it is
373+
detached with :meth:`Connection.tpc_end()` and the time it is resumed with
374+
:meth:`Connection.tpc_begin()`.The default is 0 seconds.
375+
367376
The following code sample demonstrates the ``tpc_begin()`` function::
368377

369-
connection.tpc_begin(xid=x, flags=oracledb.TPC_BEGIN_NEW)
370378
x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1")
379+
connection.tpc_begin(xid=x, flags=oracledb.TPC_BEGIN_NEW, timeout=30)
371380

372381
See :ref:`tcp` for information on TPC.
373382

@@ -392,8 +401,8 @@ Connection Methods
392401

393402
The following code sample demonstrates the ``tpc_commit()`` function::
394403

395-
connection.tpc_commit(xid=x, one_phase=False)
396404
x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1")
405+
connection.tpc_commit(xid=x, one_phase=False)
397406

398407
See :ref:`tcp` for information on TPC.
399408

@@ -415,8 +424,8 @@ Connection Methods
415424

416425
The following code sample demonstrates the ``tpc_end()`` function::
417426

418-
connection.tpc_end(xid=x, flags=oracledb.TPC_END_NORMAL)
419427
x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1")
428+
connection.tpc_end(xid=x, flags=oracledb.TPC_END_NORMAL)
420429

421430
See :ref:`tcp` for information on TPC.
422431

@@ -430,8 +439,8 @@ Connection Methods
430439

431440
The following code sample demonstrates the ``tpc_forget()`` function::
432441

433-
connection.tpc_forget(xid=x)
434442
x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1")
443+
connection.tpc_forget(xid=x)
435444

436445
See :ref:`tcp` for information on TPC.
437446

@@ -452,8 +461,8 @@ Connection Methods
452461

453462
The following code sample demonstrates the ``tpc_prepare()`` function::
454463

455-
connection.tpc_prepare(xid=x)
456464
x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1")
465+
connection.tpc_prepare(xid=x)
457466

458467
See :ref:`tcp` for information on TPC.
459468

@@ -487,8 +496,8 @@ Connection Methods
487496

488497
The following code sample demonstrates the ``tpc_rollback()`` function::
489498

490-
connection.tpc_rollback(xid=x)
491499
x = connection.xid(format_id=1, global_transaction_id="tx1", branch_qualifier="br1")
500+
connection.tpc_rollback(xid=x)
492501

493502
See :ref:`tcp` for information on TPC.
494503

doc/src/api_manual/connection_pool.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,7 @@ ConnectionPool Attributes
199199

200200
.. attribute:: ConnectionPool.homogeneous
201201

202-
This read-write boolean attribute indicates whether the pool is considered
202+
This read-only boolean attribute indicates whether the pool is considered
203203
:ref:`homogeneous <connpooltypes>` or not. If the pool is not homogeneous,
204204
different authentication can be used for each connection acquired from the
205205
pool.

doc/src/user_guide/appendix_c.rst

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -484,15 +484,15 @@ following steps:
484484

485485
6. The default value of the ``oracledb.SessionPool()`` parameter
486486
:attr:`~Connection.getmode` now waits for an available connection. That is the
487-
default is now :data:`~oracledb.SPOOL_ATTRVAL_WAIT` instead of
488-
:data:`~oracledb.SPOOL_ATTRVAL_NOWAIT`. The new default value improves the
487+
default is now :data:`~oracledb.POOL_GETMODE_WAIT` instead of
488+
:data:`~oracledb.POOL_GETMODE_NOWAIT`. The new default value improves the
489489
behavior for most applications. If the pool is in the middle of growing, the
490490
new value prevents transient connection creation errors from occurring when
491491
using the Thin mode, or when using the Thick mode with recent Oracle
492492
Client libraries.
493493

494494
If the old default value is required, modify any pool creation code to
495-
explicitly specify ``getmode=oracledb.POOL_SPOOL_ATTRVAL_NOWAIT``.
495+
explicitly specify ``getmode=oracledb.POOL_GETMODE_NOWAIT``.
496496

497497
Note a :ref:`ConnectionPool class <connpool>` deprecates the equivalent
498498
SessionPool class. The method :meth:`oracledb.create_pool()` deprecates the
@@ -558,8 +558,7 @@ addition to the common :ref:`commonupgrade`:
558558
this behavior is also similar in recent versions of the Oracle Call
559559
Interface (OCI) Session Pool used by the Thick mode. Unless the
560560
``oracledb.SessionPool()`` function's parameter ``getmode`` is
561-
``SPOOL_ATTRVAL_WAIT`` (or the new equivalent
562-
:data:`oracledb.POOL_GETMODE_WAIT`), then applications should not call
561+
:data:`oracledb.POOL_GETMODE_WAIT`, then applications should not call
563562
:meth:`ConnectionPool.acquire()` until sufficient time has passed for
564563
connections in the pool to be created.
565564

0 commit comments

Comments
 (0)