|
|
xdmp:commit( ) as empty-sequence()
|
|
|
|
Summary:
Commit the current transaction to the database.
|
Usage Notes:
Transactions running in "update" or "query" transaction mode must be
explicitly committed, using this function. xdmp:commit
is a no-op in "auto" transaction mode (the default) because
auto-commit transactions automatically commit at the end of
every statement.
When you call xdmp:commit, the transaction is marked for
commit, but commit does not actually happen until the end of the
currently executing statement.
This function is equivalent to calling
xdmp:transaction-commit
for the current host and transaction:
xdmp:transaction-commit(xdmp:host(), xdmp:transaction()).
|
Example:
xdmp:set-transaction-mode("update"),
xdmp:document-insert("/docs/mydoc.xml", <myData/>),
xdmp:commit()
=> Empty. The current transaction is marked ready to be committed.
When the commit completes, the document is visible in the database,
and the transaction ends.
|
|
|
|
xdmp:rollback( ) as empty-sequence()
|
|
|
|
Summary:
Roll back the current transaction.
|
Usage Notes:
When a transaction is rolled back, the current statement immediately
terminates, updates made by any statement in the transaction are
discarded, and the transaction terminates.
Transactions running in "update" or "query" transaction mode should be
explicitly rolled back, using this function. Failure to explicitly
commit or roll back such a transaction leaves the transaction open
until transaction timeout, thus unnecessarily holding resources and
locks, potentially blocking other transactions.
Transactions running in "auto" transaction mode may also use this
function, to roll back a transaction without raising an error.
The result of a statement terminated with xdmp:rollback
is always the empty sequence.
This function is equivalent to calling
xdmp:transaction-rollback
for the current host and transaction:
xdmp:transaction-rollback(xdmp:host(), xdmp:transaction()).
|
Example:
(: multi-statement transaction :)
declare option xdmp:transaction-mode "update";
xdmp:document-insert("/docs/first.xml", <first/>);
xdmp:document-insert("/docs/second.xml", <second/>);
xdmp:rollback();
=> Empty. The transaction is rolled back. The documents are
not added to the database. The transaction ends.
|
|
|
|
xdmp:set-transaction-mode(
|
|
$value as xs:string
|
| ) as empty-sequence() |
|
|
|
Summary:
Set the transaction mode for the current session. Calling this function
has no effect on existing transactions.
|
Parameters:
|
$value
:
The new transaction mode. Must be one of "auto", "query", or "update".
|
|
Usage Notes:
The mode a transaction runs under is fixed when the transaction is
created. Calling xdmp:set-transaction-mode during a
query does not affect the current transaction.
The transaction mode defaults to "auto". To change the mode, you
may either call xdmp:set-transaction-mode or use the
xdmp:transaction-mode option.
Use the xdmp:transaction-mode option to set the
transaction mode before a transaction exists. Use
xdmp:set-transaction-mode to set the mode during execution.
|
Example:
declare option xdmp:transaction-mode "update";
(: this transaction runs in update mode, due to the option :)
xdmp:set-transaction-mode("query"),
xdmp:document-insert("/docs/mydoc.xml", <myData/>),
xdmp:commit();
(: but this new transaction runs in query mode :)
xdmp:get-transaction-mode(),
fn:doc("/docs/mydoc.xml")
=> "query"
<myData/>
|
|
|
|
xdmp:set-transaction-name(
|
|
$name as xs:string,
|
|
$host-id as xs:unsignedLong,
|
|
$txn-id as xs:unsignedLong
|
| ) as empty-sequence() |
|
|
|
Summary:
Set the name of a local or remote transaction.
|
Parameters:
|
$name
:
The new name.
|
|
$host-id
:
An optional host id. If omitted, the local App Server host is assumed.
If a host id is given, then a transaction id must also be given.
|
|
$txn-id
:
An optional transaction ID. If omitted, the current transaction is
assumed. If a transaction id is given, then a host id must also be given.
|
|
Required Privilege:
http://marklogic.com/xdmp/privileges/xdmp-set-transaction-name-my
http://marklogic.com/xdmp/privileges/xdmp-set-transaction-name-any
|
Usage Notes:
If the transaction already has a name, it is overwritten with the
new name.
If the specified transaction does not exist, XDMP-NOTXN
is raised.
If host-id is not found or MarkLogic Server is not available
on that host, the exception XDMP-HOSTOFFLINE is raised.
|
|
Example:
|
Example:
xdmp:set-transaction-name("myTransaction")
=> Set the name of the current transaction in the current local session
to "myTransaction".
|
Example:
xdmp:set-transaction-name("myTransaction", $txn-id,
xdmp:host("some-host.marklogic.com"))
=> Set the name of the given transaction on the remote host
some-host.marklogic.com to "myTransaction".
|
|
|
|
xdmp:set-transaction-time-limit(
|
|
$time-limit as xs:unsignedInt,
|
|
$host-id as xs:unsignedLong,
|
|
$txn-id as xs:unsignedLong
|
| ) as empty-sequence() |
|
|
|
Summary:
Set the transaction time limit for a local or remote transaction.
Defaults to the configured request timeout.
|
Parameters:
|
$time-limit
:
The desired time limit, in seconds.
|
|
$host-id
:
A host id.
|
|
$txn-id
:
The transaction ID.
|
|
Required Privilege:
http://marklogic.com/xdmp/privileges/xdmp-set-transaction-time-limit-my
http://marklogic.com/xdmp/privileges/xdmp-set-transaction-time-limit-any
|
Usage Notes:
The transaction time limit determines how long the transaction may run
before being automatically aborted. If you set the time limit to a limit
less than the elapsed time of the current transaction, the transaction
may abort immediately.
The default (and maximum) transaction time limit is the request time
limit configured for the server that creates the transaction. For
information on configuring the request time limit, see the Administrator's
Guide, or
admin:appserver-set-request-timeout.
If you attempt to set the transaction time limit to a value greater
than the configured request time limit, the exception
XDMP-TIMELIMIT is raised.
|
Example:
xdmp:set-transaction-time-limit(10)
=> Empty. The time limit of the current transaction on the
local host is set to 10 seconds.
|
Example:
xdmp:set-transaction-time-limit(10, xdmp:host(), $some-txn-id)
=> Empty. The time limit of the given transaction on the local
host is set to 10 seconds.
|
|
|
|
xdmp:transaction(
|
|
$txn-name as xs:string,
|
|
$host-id as xs:unsignedLong
|
| ) as xs:unsignedLong* |
|
|
|
Summary:
Returns the transaction id for the current, or transaction id's for
all transactions with the given name.
|
Parameters:
|
$txn-name
:
An optional transaction name.
|
|
$host-id
:
An optional host id, for retrieving the transaction id of a named
remote transaction.
|
|
Usage Notes:
When called with no parameters, this function returns the transaction
id of the current transaction on the local host. When called with a
txn-name, the transaction id for the named local or remote
transaction(s) is returned.
Transaction names need not be unique. This function will return
multiple transaction id's if more than one transaction matches
the parameters.
To retrieve the transaction id of a named remote transaction, supply
a host-id. If host-id is unknown or MarkLogic Server
is not online on that host, an exception is raised.
If no matching transaction exists, an empty sequence is returned.
|
Example:
xdmp:transaction("myNamedTransaction")
=> The transaction id for "myNamedTransaction" on the local host.
|
Example:
xdmp:transaction("myNamedTransaction", xdmp:host("some-host.marklogic.com"))
=> The transaction id for "myNamedTransaction" on the remote host
some-host.marklogic.com.
|
|
|
|
xdmp:transaction-commit(
|
|
$host-id as xs:unsignedLong,
|
|
$txn-id as xs:unsignedLong
|
| ) as empty-sequence() |
|
|
|
Summary:
Explicitly commit a transaction running on a named host.
|
Parameters:
|
$host-id
:
A host id.
|
|
$txn-id
:
The transaction ID.
|
|
Required Privilege:
http://marklogic.com/xdmp/privileges/complete-my-transactions
http://marklogic.com/xdmp/privileges/complete-any-transactions
|
Usage Notes:
Use this function to explicitly commit a remote transaction running in
"update" or "query" transaction mode. You typically will not use this
function for transactions running in "auto" transaction mode because
the server commits such transactions automatically, at the end of
every statement.
When you call xdmp:transaction-commit, the transaction is
marked for commit. The commit occurs at the end of the current executing
statement. The transaction ends at that point.
If the named host or transaction does not exist, an error is raised.
|
Example:
xdmp:transaction-commit(xdmp:host("some-host.marklogic.com"), $some-txn-id)
=> Empty. The given transaction is marked ready to be committed.
|
|
|
|
xdmp:transaction-rollback(
|
|
$host-id as xs:unsignedLong,
|
|
$txn-id as xs:unsignedLong
|
| ) as empty-sequence() |
|
|
|
Summary:
Explicitly roll back a transaction running on a named host.
|
Parameters:
|
$host-id
:
A host id.
|
|
$txn-id
:
The transaction ID.
|
|
Required Privilege:
http://marklogic.com/xdmp/privileges/xdmp-transaction-complete
|
Usage Notes:
Use this function to explicitly roll back a remote transaction running in
"update" or "query" transaction mode. See
xdmp:rollback for more information.
Any statement executing under the remote transaction is halted immediately.
If the named host or transaction does not exist, an error is raised.
|
Example:
xdmp:transaction-rollback(xdmp:host("some-host.marklogic.com"), $some-txn-id)
=> Empty. The given transaction is rolled back and all
modifications made by the transaction are discarded.
|
|
|
|
xdmp:xa-complete(
|
|
$forestID as unsignedLong,
|
|
$txn-id as xs:unsignedLong,
|
|
$commit as xs:boolean,
|
|
$remember as xs:boolean
|
| ) as empty-sequence() |
|
|
|
Summary:
Completes (commits or rolls back) a prepared XA transaction.
|
Parameters:
|
$forestID
:
A forest ID.
|
|
$txn-id
:
The transaction ID.
|
|
$commit
:
Whether to commit or rollback. A value of true means commit.
|
|
$remember
:
Whether to remember the completion until explicitly forgotten.
|
|
Required Privilege:
http://marklogic.com/xdmp/privileges/complete-my-transactions
http://marklogic.com/xdmp/privileges/complete-any-transactions
|
Usage Notes:
You should usually let the Transaction Manager handle commit or rollback
of global transactions. This function is made available for unusual
circumstances in which you need to heuristically complete the MarkLogic
branch of a global XA transaction. For example, if contact with the
Transaction Manager is lost for a long time.
|
Example:
xdmp:xa-complete($forest-id, $txn-id, fn:true(), fn:true())
=> Empty. The given transaction is committed and the
outcome is remembered.
xdmp:xa-complete($forest-id, $txn-id, fn:false(), fn:true())
=> Empty. The given transaction is rolled back and the
outcome is remembered.
|
|
|