Take another run at long-lived cursor and transactional wording, use

a common more complex example in all places that shows all of the
transactional methods, with lots of comments.  Ref #291.

1 files changed, 22 insertions, 37 deletions

diff --git a/examples/c/ex_all.c b/examples/c/ex_all.c
index 6c39aaeda20..b47ff231b25 100644
--- a/examples/c/ex_all.c
+++ b/examples/c/ex_all.c
@@ -447,18 +447,6 @@ session_ops(WT_SESSION *session)
 	ret = session->verify(session, "table:mytable", NULL);
 	/*! [Verify a table] */
 
-	/*! [Begin a transaction] */
-	ret = session->begin_transaction(session, NULL);
-	/*! [Begin a transaction] */
-
-	/*! [Commit a transaction] */
-	ret = session->commit_transaction(session, NULL);
-	/*! [Commit a transaction] */
-
-	/*! [Rollback a transaction] */
-	ret = session->rollback_transaction(session, NULL);
-	/*! [Rollback a transaction] */
-
 	/*! [Close a session] */
 	ret = session->close(session, NULL);
 	/*! [Close a session] */
@@ -469,44 +457,41 @@ session_ops(WT_SESSION *session)
 int
 transaction_ops(WT_CONNECTION *conn, WT_SESSION *session)
 {
-	WT_CURSOR *cursor;
+	WT_CURSOR *cursor, *cursor1, *cursor2;
 	int ret;
 
-	/*! [simple transaction] */
-	ret = session->begin_transaction(session, NULL);
+	/*! [transaction commit/rollback] */
 	ret =
 	    session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
-	cursor->set_key(cursor, "some-key");
-	cursor->set_value(cursor, "some-value");
-	ret = cursor->update(cursor);
-	ret = session->commit_transaction(session, NULL);
-
+	ret = session->begin_transaction(session, NULL);
 	/*
-	 * The cursor position has been reset by the transaction commit, it
-	 * can be used again until the handle is explicitly closed.
+	 * Cursors may be opened before or after the transaction begins, and in
+	 * either case, subsequent operations are included in the transaction.
+	 * The begin_transaction call resets all open cursors.
 	 */
-	ret = cursor->close(cursor);
-	/*! [simple transaction] */
 
-	/*! [simple rollback transaction] */
-	ret =
-	    session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
-	ret = session->begin_transaction(session, NULL);
-	cursor->set_key(cursor, "some-key");
-	cursor->set_value(cursor, "some-value");
-	ret = cursor->update(cursor);
-	switch (ret) {
-	case 0:
+	cursor->set_key(cursor, "key");
+	cursor->set_value(cursor, "value");
+	switch (ret = cursor->update(cursor)) {
+	case 0:					/* Update success */
 		ret = session->commit_transaction(session, NULL);
+		/*
+		 * The commit_transaction call resets all open cursors.
+		 * If commit_transaction fails, the transaction was rolled-back.
+		 */
 		break;
-	case WT_DEADLOCK:			/* Conflict */
+	case WT_DEADLOCK:			/* Update conflict */
 	default:				/* Other error */
 		ret = session->rollback_transaction(session, NULL);
+		/* The rollback_transaction call resets all open cursors. */
 		break;
 	}
-	/*! [simple rollback transaction] */
 
-	/*! [simple transaction isolation] */
+	/* Cursors remain open and may be used for multiple transactions. */
+	/*! [transaction commit/rollback] */
+	ret = cursor->close(cursor);
+
+	/*! [transaction isolation] */
 	/* A single transaction configured for snapshot isolation. */
 	ret =
 	    session->open_cursor(session, "table:mytable", NULL, NULL, &cursor);
@@ -515,7 +500,7 @@ transaction_ops(WT_CONNECTION *conn, WT_SESSION *session)
 	cursor->set_value(cursor, "some-value");
 	ret = cursor->update(cursor);
 	ret = session->commit_transaction(session, NULL);
-	/*! [simple transaction isolation] */
+	/*! [transaction isolation] */
 
 	/*! [session isolation configuration] */
 	/* Open a session configured for read-uncommitted isolation. */