Java Doc for TransactionController.java in  » Database-DBMS » db-derby-10.2 » org » apache » derby » iapi » store » access » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Each transaction controller is associated with a transaction context which provides error cleanup when standard exceptions are thrown anywhere in the system. The transaction context performs the following actions in response to cleanupOnError:

• If the error is an instance of StandardException that has a severity less than ExceptionSeverity.TRANSACTION_SEVERITY all resources remain unaffected.
• If the error is an instance of StandardException that has a severity equal to ExceptionSeverity.TRANSACTION_SEVERITY, then all resources are released. An attempt to use any resource obtained from this transaction controller after such an error will result in an error. The transaction controller itself remains valid, however.
• If the error is an instance of StandardException that has a severity greater than ExceptionSeverity.TRANSACTION_SEVERITY, then all resources are released and the context is popped from the stack. Attempting to use this controller or any resources obtained from it will result in an error.

The request to get the table lock (any table lock including intent or "real" table level lock), will not wait if it can't be granted.

Returns free space from the conglomerate back to the OS.

There are 4 types of open "conglomerates" that can be tracked, those opened by each of the following: openConglomerate(), openScan(), createSort(), and openSort().

All parameters shared between openScan() and this routine are interpreted exactly the same.

Currently, only "heap"'s and ""btree secondary index"'s are supported, and all the features are not completely implemented.

Get a transaction controller with which to manipulate data within the access manager.

Returns a GroupFetchScanController which can be used to move rows around in a table, creating a block of free pages at the end of the table.

Returns true and fetches the rightmost non-null row of an ordered conglomerate into "fetchRow" if there is at least one non-null row in the conglomerate.

The dynamic info is a set of variables to be used in a given ScanController or ConglomerateController.

The static info would be valid until any ddl was executed on the conglomid, and would be up to the caller to throw away when that happened.

This transaction "name" will be the same id which is returned in the TransactionInfo information, used by the lock and transaction vti's to identify transactions.

Although implementation specific, the transaction id is usually a number which is bumped every time a commit or abort is issued.

The a string which identifies the transaction.

A superset of properties that "users" (ie.

Same as openScan(), except that one can optionally provide "compiled" static_info and/or dynamic_info.

All inputs work exactly as in openScan().

Return an open SortCostController which can be used to ask about the estimated costs of SortController() operations.

Parameters:
  implParameters - Properties which help in choosing implementation-specific sort options.

This function behaves the same as @see createConglomerate except it also populates the conglomerate with rows from the row source and the rows that are inserted are not logged.

Individual rows that are loaded into the conglomerate are not logged.

A nested user transaction can be used exactly as any other TransactionController, except as follows.

The request to get the table lock (any table lock including intent or "real" table level lock), will not wait if it can't be granted. A lock timeout will be returned. Note that subsequent row locks will wait if the application has not set a 0 timeout and if the call does not have a wait parameter (like OpenConglomerate.fetch().

Note that one must still set OPENMODE_FORUPDATE to be able to change rows in the scan. So to enable update locks for an updating scan one provides (OPENMODE_FORUPDATE | OPENMODE_USE_UPDATE_LOCKS)

Returns free space from the conglomerate back to the OS. Currently only the sequential free pages at the "end" of the conglomerate can be returned to the OS.

Parameters:
  conglomId - Id of the conglomerate to purge.
exception:
  StandardException - Standard exception policy.

There are 4 types of open "conglomerates" that can be tracked, those opened by each of the following: openConglomerate(), openScan(), createSort(), and openSort(). Scans opened by openSortScan() are tracked the same as those opened by openScan(). This routine can be used to either report on the number of all opens, or may be used to track one particular type of open.

This routine is expected to be used for debugging only. An implementation may only track this info under SanityManager.DEBUG mode. If the implementation does not track the info it will return -1 (so code using this call to verify that no congloms are open should check for return <= 0 rather than == 0).

The return value depends on the "which_to_count" parameter as follows:

• OPEN_CONGLOMERATE - return # of openConglomerate() calls not close()'d.
• OPEN_SCAN - return # of openScan() + openSortScan() calls not close()'d.
• OPEN_CREATED_SORTS - return # of sorts created (createSort()) in current xact. There is currently no way to get rid of these sorts before end of transaction.
• OPEN_SORT - return # of openSort() calls not close()'d.
• OPEN_TOTAL - return total # of all above calls not close()'d.

The nunber of open's of a type indicated by "which_to_count"parameter.
Parameters:
  which_to_count - Which kind of open to report on.
exception:
  StandardException - Standard exception policy.

Individual rows that are loaded into the conglomerate are not logged. After this operation, the underlying database must be backed up with a database backup rather than an transaction log backup (when we have them). This warning is put here for the benefit of future generation.

This function behaves the same as @see createConglomerate except it also populates the conglomerate with rows from the row source and the rows that are inserted are not logged.
Parameters:
  implementation - Specifies what kind of conglomerate to create.THE WAY THAT THE IMPLEMENTATION IS CHOSEN STILL NEEDS SOME WORK.For now, use "BTREE" or "heap" for a local access manager.
Parameters:
  rowSource - the interface to recieve rows to load into theconglomerate.
Parameters:
  rowCount - - if not null the number of rows loaded into the tablewill be returned as the first element of the array.
exception:
  StandardException - if the conglomerate could not be created orloaded for some reason. Throws SQLState.STORE_CONGLOMERATE_DUPLICATE_KEY_EXCEPTION ifthe conglomerate supports uniqueness checks and has been created todisallow duplicates, and one of the rows being loaded had key columns whichwere duplicate of a row already in the conglomerate.

All parameters shared between openScan() and this routine are interpreted exactly the same. Logically this routine calls openScan() with the passed in set of parameters, and then places all returned rows into a newly created HashSet and returns, actual implementations will likely perform better than actually calling openScan() and doing this. For documentation of the openScan parameters see openScan().

the BackingStoreHashtable which was created.
Parameters:
  conglomId - see openScan()
Parameters:
  open_mode - see openScan()
Parameters:
  lock_level - see openScan()
Parameters:
  isolation_level - see openScan()
Parameters:
  scanColumnList - see openScan()
Parameters:
  startKeyValue - see openScan()
Parameters:
  startSearchOperator - see openScan()
Parameters:
  qualifier - see openScan()
Parameters:
  stopKeyValue - see openScan()
Parameters:
  stopSearchOperator - see openScan()
Parameters:
  max_rowcnt - The maximum number of rows to insert into the HashSet. Pass in -1 if there is no maximum.
Parameters:
  key_column_numbers - The column numbers of the columns in thescan result row to be the key to the Hashtable. "0" is the first column in the scan result row (which may be different than the first row in the table of the scan).
Parameters:
  remove_duplicates - Should the HashSet automatically removeduplicates, or should it create the Vector of duplicates?
Parameters:
  estimated_rowcnt - The number of rows that the caller estimates will be inserted into the sort. -1 indicates that the caller has no idea.Used by the sort to make good choices aboutin-memory vs. external sorting, and to sizemerge runs.
Parameters:
  max_inmemory_rowcnt - The number of rows at which the underlyingHashtable implementation should cut overfrom an in-memory hash to a disk basedaccess method.
Parameters:
  initialCapacity - If not "-1" used to initialize the javaHashtable.
Parameters:
  loadFactor - If not "-1" used to initialize the javaHashtable.
Parameters:
  collect_runtimestats - If true will collect up runtime stats duringscan processing for retrieval byBackingStoreHashtable.getRuntimeStats().
Parameters:
  skipNullKeyColumns - Whether or not to skip rows with 1 or more null key columns
See Also:   BackingStoreHashtable
See Also:   TransactionController.openScan
exception:
  StandardException - Standard exception policy.

Currently, only "heap"'s and ""btree secondary index"'s are supported, and all the features are not completely implemented. For now, create conglomerates like this:

 TransactionController tc;
 long conglomId = tc.createConglomerate(
 "heap", // we're requesting a heap conglomerate
 template, // a populated template is required for heap and btree.
 null, // default properties
 0); // not temporary
 

• "baseConglomerateId" (integer). The conglomerate id of the base conglomerate is never actually accessed by the b-tree secondary index implementation, it only serves as a namespace for row locks. This property is required.
• "rowLocationColumn" (integer). The zero-based index into the row which the b-tree secondary index will assume holds a @see RowLocation of the base row in the base conglomerate. This value will be used for acquiring locks. In this implementation RowLocationColumn must be the last key column. This property is required.
• "allowDuplicates" (boolean). If set to true the table will allow rows which are duplicate in key column's 0 through (nUniqueColumns - 1). Currently only supports "false". This property is optional, defaults to false.
• "nKeyFields" (integer) Columns 0 through (nKeyFields - 1) will be included in key of the conglomerate. This implementation requires that "nKeyFields" must be the same as the number of fields in the conglomerate, including the rowLocationColumn. Other implementations may relax this restriction to allow non-key fields in the index. This property is required.
• "nUniqueColumns" (integer) Columns 0 through "nUniqueColumns" will be used to check for uniqueness. So for a standard SQL non-unique index implementation set "nUniqueColumns" to the same value as "nKeyFields"; and for a unique index set "nUniqueColumns" to "nKeyFields - 1 (ie. don't include the rowLocationColumn in the uniqueness check). This property is required.
• "maintainParentLinks" (boolean) Whether the b-tree pages maintain the page number of their parent. Only used for consistency checking. It takes a certain amount more effort to maintain these links, but they're really handy for ensuring that the index is consistent. This property is optional, defaults to true.

Sorts also do aggregation. The input (unaggregated) rows have the same format as the aggregated rows, and the aggregate results are part of the both rows. The sorter, when it notices that a row is a duplicate of another, calls a user-supplied aggregation method (see interface Aggregator), passing it both rows. One row is known as the 'addend' and the other the 'accumulator'. The aggregation method is assumed to merge the addend into the accumulator. The sort then discards the addend row.

So, for the query:

 select a, sum(b)
 from t
 group by a
 

Nulls are always considered to be ordered in a sort, that is, null compares equal to null, and less than anything else.
Parameters:
  implParameters - Properties which help in choosingimplementation-specific sort options. If null, a"generally useful" sort will be used.
Parameters:
  template - A row which is prototypical for the sort.All rows inserted into the sort controller must have exactly the same number of columns as the template row.Every column in an inserted row must have the same typeas the corresponding column in the template.
Parameters:
  columnOrdering - An array which specifies which columnsparticipate in ordering - see interface ColumnOrdering fordetails. The column referenced in the 0th columnOrderingobject is compared first, then the 1st, etc. To sort on a singlecolumn specify an array with a single entry.
Parameters:
  sortObserver - An object that is used to observethe sort. It is used to provide a callback into the sorter.If the sortObserver is null, then the sort proceeds as normal.If the sortObserver is non null, then it is called as rows are loaded into the sorter. It can be used to implementa distinct sort, aggregates, etc.
Parameters:
  alreadyInOrder - Indicates that the rows inserted intothe sort controller will already be in order. This is usedto perform aggregation only.
Parameters:
  estimatedRows - The number of rows that the caller estimates will be inserted into the sort. -1 indicates thatthe caller has no idea. Used by the sort to make good choicesabout in-memory vs. external sorting, and to size merge runs.
Parameters:
  estimatedRowSize - The estimated average row size of therows being sorted. This is the client portion of the rowsize, it shouldnot attempt to calculate Store's overhead. -1 indicates that the callerhas no idea (and the sorter will use 100 bytes in that case. Used by the sort to make good choices about in-memory vs. external sorting, and to sizemerge runs. The client is not expected to estimate the per column/per row overhead of raw store, just to make a guess about the storageassociated with each row (ie. reasonable estimates for some implementationswould be 4 for int, 8 for long, 102 for char(100),202 for varchar(200), a number out of hat for user types, ...). The sort identifier which can be used subsequently toopen sort controllers and scans.
See Also:   SortObserver
See Also:   ColumnOrdering
See Also:   ScanController
See Also:   SortController
exception:
  StandardException - From a lower-level exception.

Get a transaction controller with which to manipulate data within the access manager. Tbis controller allows one to manipulate a global XA conforming transaction.

Must only be called a previous local transaction was created and exists in the context. Can only be called if the current transaction is in the idle state. Upon return from this call the old tc will be unusable, and all references to it should be dropped (it will have been implicitly destroy()'d by this call.

The (format_id, global_id, branch_id) triplet is meant to come exactly from a javax.transaction.xa.Xid. We don't use Xid so that the system can be delivered on a non-1.2 vm system and not require the javax classes in the path.
Parameters:
  global_id - the global transaction identifier part of XID - ie.Xid.getGlobalTransactionId().
Parameters:
  branch_id - The branch qualifier of the Xid - ie. Xid.getBranchQaulifier()
exception:
  StandardException - Standard exception policy.
See Also:   TransactionController

Return a string with debugging information about current opened congloms/scans/sorts which have not been close()'d. Calls to this routine are only valid under code which is conditional on SanityManager.DEBUG.

String with debugging information.
exception:
  StandardException - Standard exception policy.

Returns a GroupFetchScanController which can be used to move rows around in a table, creating a block of free pages at the end of the table. The process will move rows from the end of the table toward the beginning. The GroupFetchScanController will return the old row location, the new row location, and the actual data of any row moved. Note that this scan only returns moved rows, not an entire set of rows, the scan is designed specifically to be used by either explicit user call of the SYSCS_ONLINE_COMPRESS_TABLE() procedure, or internal background calls to compress the table. The old and new row locations are returned so that the caller can update any indexes necessary. This scan always returns all collumns of the row. All inputs work exactly as in openScan(). The return is a GroupFetchScanController, which only allows fetches of groups of rows from the conglomerate.

The GroupFetchScanController to be used to fetch the rows.
Parameters:
  conglomId - see openScan()
Parameters:
  hold - see openScan()
Parameters:
  open_mode - see openScan()
Parameters:
  lock_level - see openScan()
Parameters:
  isolation_level - see openScan()
exception:
  StandardException - Standard exception policy.
See Also:   ScanController
See Also:   GroupFetchScanController

Drop a sort created by a call to createSort() within the current transaction (sorts are automatically "dropped" at the end of a transaction. This call should only be made after all openSortScan()'s and openSort()'s have been closed.
Parameters:
  sortid - The identifier of the sort to drop, as returned from createSort.

exception:
  StandardException - From a lower-level exception.

Returns true and fetches the rightmost non-null row of an ordered conglomerate into "fetchRow" if there is at least one non-null row in the conglomerate. If there are no non-null rows in the conglomerate it returns false. Any row with a first column with a Null is considered a "null" row.

Non-ordered conglomerates will not implement this interface, calls will generate a StandardException.

RESOLVE - this interface is temporary, long term equivalent (and more) functionality will be provided by the openBackwardScan() interface.

ISOLATION_SERIALIZABLE and MODE_RECORD locking for btree max: The "BTREE" implementation will at the very least get a shared row lock on the max key row and the key previous to the max. This will be the case where the max row exists in the rightmost page of the btree. These locks won't be released. If the row does not exist in the last page of the btree then a scan of the entire btree will be performed, locks acquired in this scan will not be released.

Note that under ISOLATION_READ_COMMITTED, all locks on the table are released before returning from this call.
Parameters:
  conglomId - The identifier of the conglomerateto open the scan for.
Parameters:
  open_mode - Specifiy flags to control opening of table. OPENMODE_FORUPDATE - if set open the table forupdate otherwise open table shared.
Parameters:
  lock_level - One of (MODE_TABLE, MODE_RECORD).
Parameters:
  isolation_level - The isolation level to lock the conglomerate at.One of (ISOLATION_READ_COMMITTED, ISOLATION_REPEATABLE_READ or ISOLATION_SERIALIZABLE).
Parameters:
  scanColumnList - A description of which columns to return from every fetch in the scan. template, and scanColumnList work togetherto describe the row to be returned by the scan - see RowUtil for description of how these three parameters work together to describe a "row".
Parameters:
  fetchRow - The row to retrieve the maximum value into. boolean indicating if a row was found and retrieved or not.
exception:
  StandardException - Standard exception policy.

the conglomid, which contains the container with containerid.
exception:
  StandardException - Standard exception policy.

Will have to change if we ever have more than one container in a conglomerate. the containerid of container implementing conglomerate with "conglomid."
exception:
  StandardException - Standard exception policy.

The context manager that the transaction was created with.

The dynamic info is a set of variables to be used in a given ScanController or ConglomerateController. It can only be used in one controller at a time. It is up to the caller to insure the correct thread access to this info. The type of info in this is a scratch template for btree traversal, other scratch variables for qualifier evaluation, ...

The dynamic information.
Parameters:
  conglomId - The identifier of the conglomerate to open.
exception:
  StandardException - Standard exception policy.

The static info would be valid until any ddl was executed on the conglomid, and would be up to the caller to throw away when that happened. This ties in with what language already does for other invalidation of static info. The type of info in this would be containerid and array of format id's from which templates can be created. The info in this object is read only and can be shared among as many threads as necessary.

The static compiled information.
Parameters:
  conglomId - The identifier of the conglomerate to open.
exception:
  StandardException - Standard exception policy.

This transaction "name" will be the same id which is returned in the TransactionInfo information, used by the lock and transaction vti's to identify transactions.

Although implementation specific, the transaction id is usually a number which is bumped every time a commit or abort is issued.

The a string which identifies the transaction.

A superset of properties that "users" (ie. from sql) can specify. Store may implement other properties which should not be specified by users. Layers above access may implement properties which are not known at all to Access.

This list is a superset, as some properties may not be implemented by certain types of conglomerates. For instant an in-memory store may not implement a pageSize property. Or some conglomerates may not support pre-allocation.

This interface is meant to be used by the SQL parser to do validation of properties passsed to the create table statement, and also by the various user interfaces which present table information back to the user.

Currently this routine returns the following list: derby.storage.initialPages derby.storage.minimumRecordSize derby.storage.pageReservedSpace derby.storage.pageSize The superset of properties that "users" can specify.

This simply passes the operation to the RawStore which logs and does it.
Parameters:
  operation - the operation that is to be applied
See Also:   org.apache.derby.iapi.store.raw.Loggable
See Also:   org.apache.derby.iapi.store.raw.Transaction.logAndDo
exception:
  StandardException - Standard cloudscape exception policy

Same as openConglomerate(), except that one can optionally provide "compiled" static_info and/or dynamic_info. This compiled information must have be gotten from getDynamicCompiledConglomInfo() and/or getStaticCompiledConglomInfo() calls on the same conglomid being opened. It is up to caller that "compiled" information is still valid and is appropriately multi-threaded protected.

See Also:   TransactionController.openConglomerate
See Also:   TransactionController.getDynamicCompiledConglomInfo
See Also:   TransactionController.getStaticCompiledConglomInfo
See Also:   DynamicCompiledOpenConglomInfo
See Also:   StaticCompiledOpenConglomInfo The identifier to be used to open the conglomerate later.
Parameters:
  hold - If true, will be maintained open over commits.
Parameters:
  open_mode - Specifiy flags to control opening of table.
Parameters:
  lock_level - One of (MODE_TABLE, MODE_RECORD).
Parameters:
  isolation_level - The isolation level to lock the conglomerate at.One of (ISOLATION_READ_COMMITTED, ISOLATION_REPEATABLE_READ or ISOLATION_SERIALIZABLE).
Parameters:
  static_info - object returned from getStaticCompiledConglomInfo() call on this id.
Parameters:
  dynamic_info - object returned fromgetDynamicCompiledConglomInfo() call on this id.
exception:
  StandardException - Standard exception policy.

Same as openScan(), except that one can optionally provide "compiled" static_info and/or dynamic_info. This compiled information must have be gotten from getDynamicCompiledConglomInfo() and/or getStaticCompiledConglomInfo() calls on the same conglomid being opened. It is up to caller that "compiled" information is still valid and is appropriately multi-threaded protected.

See Also:   TransactionController.openScan
See Also:   TransactionController.getDynamicCompiledConglomInfo
See Also:   TransactionController.getStaticCompiledConglomInfo
See Also:   DynamicCompiledOpenConglomInfo
See Also:   StaticCompiledOpenConglomInfo The identifier to be used to open the conglomerate later.
Parameters:
  open_mode - see openScan()
Parameters:
  lock_level - see openScan()
Parameters:
  isolation_level - see openScan()
Parameters:
  scanColumnList - see openScan()
Parameters:
  startKeyValue - see openScan()
Parameters:
  startSearchOperator - see openScan()
Parameters:
  qualifier - see openScan()
Parameters:
  stopKeyValue - see openScan()
Parameters:
  stopSearchOperator - see openScan()
Parameters:
  static_info - object returned from getStaticCompiledConglomInfo() call on this id.
Parameters:
  dynamic_info - object returned fromgetDynamicCompiledConglomInfo() call on this id.
exception:
  StandardException - Standard exception policy.

The lock level indicates the minimum lock level to get locks at, the underlying conglomerate implementation may actually lock at a higher level (ie. caller may request MODE_RECORD, but the table may be locked at MODE_TABLE instead).

The close method is on the ConglomerateController interface. a ConglomerateController to manipulate the conglomerate.
Parameters:
  conglomId - The identifier of the conglomerate to open.
Parameters:
  hold - If true, will be maintained open over commits.
Parameters:
  open_mode - Specifiy flags to control opening of table. OPENMODE_FORUPDATE - if set open the table forupdate otherwise open table shared.
Parameters:
  lock_level - One of (MODE_TABLE, MODE_RECORD).
Parameters:
  isolation_level - The isolation level to lock the conglomerate at.One of (ISOLATION_READ_COMMITTED, ISOLATION_REPEATABLE_READ or ISOLATION_SERIALIZABLE).
exception:
  StandardException - if the conglomerate could not be opened for some reason. Throws SQLState.STORE_CONGLOMERATE_DOES_NOT_EXISTif the conglomId being requested does notexist for some reason (ie. someone has dropped it).

All inputs work exactly as in openScan(). The return is a GroupFetchScanController, which only allows fetches of groups of rows from the conglomerate.

The GroupFetchScanController to be used to fetch the rows.
Parameters:
  conglomId - see openScan()
Parameters:
  open_mode - see openScan()
Parameters:
  lock_level - see openScan()
Parameters:
  isolation_level - see openScan()
Parameters:
  scanColumnList - see openScan()
Parameters:
  startKeyValue - see openScan()
Parameters:
  startSearchOperator - see openScan()
Parameters:
  qualifier - see openScan()
Parameters:
  stopKeyValue - see openScan()
Parameters:
  stopSearchOperator - see openScan()
exception:
  StandardException - Standard exception policy.
See Also:   ScanController
See Also:   GroupFetchScanController

The way that starting and stopping keys and operators are used may best be described by example. Say there's an ordered conglomerate with two columns, where the 0-th column is named 'x', and the 1st column is named 'y'. The values of the columns are as follows:

 x: 1 3 4 4 4 5 5 5 6 7 9
 y: 1 1 2 4 6 2 4 6 1 1 1
 

A {start key, search op} pair of {{5.2}, GE} would position on {x=5, y=2}, whereas the pair {{5}, GT} would position on {x=6, y=1}.

Partial keys are used to implement partial key scans in SQL. For example, the SQL "select * from t where x = 5" would open a scan on the conglomerate (or a useful index) of t using a starting position partial key of {{5}, GE} and a stopping position partial key of {{5}, GT}.

Some more examples:

 +-------------------+------------+-----------+--------------+--------------+
 | predicate         | start key  | stop key  | rows         | rows locked  |
 |                   | value | op | value |op | returned     |serialization |
 +-------------------+-------+----+-------+---+--------------+--------------+
 | x = 5             | {5}   | GE | {5}   |GT |{5,2} .. {5,6}|{4,6} .. {5,6}|
 | x > 5             | {5}   | GT | null  |   |{6,1} .. {9,1}|{5,6} .. {9,1}|
 | x >= 5            | {5}   | GE | null  |   |{5,2} .. {9,1}|{4,6} .. {9,1}|
 | x <= 5            | null  |    | {5}   |GT |{1,1} .. {5,6}|first .. {5,6}|
 | x < 5             | null  |    | {5}   |GE |{1,1} .. {4,6}|first .. {4,6}|
 | x >= 5 and x <= 7 | {5},  | GE | {7}   |GT |{5,2} .. {7,1}|{4,6} .. {7,1}|
 | x = 5  and y > 2  | {5,2} | GT | {5}   |GT |{5,4} .. {5,6}|{5,2} .. {5,6}|
 | x = 5  and y >= 2 | {5,2} | GE | {5}   |GT |{5,2} .. {5,6}|{4,6} .. {5,6}|
 | x = 5  and y < 5  | {5}   | GE | {5,5} |GE |{5,2} .. {5,4}|{4,6} .. {5,4}|
 | x = 2             | {2}   | GE | {2}   |GT | none         |{1,1} .. {1,1}|
 +-------------------+-------+----+-------+---+--------------+--------------+
 

As the above table implies, the underlying scan may lock more rows than it returns in order to guarantee serialization.

For each row which meets the start and stop position, as described above the row is "qualified" to see whether it should be returned. The qualification is a 2 dimensional array of @see Qualifiers, which represents the qualification in conjunctive normal form (CNF). Conjunctive normal form is an "and'd" set of "or'd" Qualifiers.

For example x = 5 would be represented is pseudo code as: qualifier_cnf[][] = new Qualifier[1]; qualifier_cnf[0] = new Qualifier[1]; qualifier_cnr[0][0] = new Qualifer(x = 5)

For example (x = 5) or (y = 6) would be represented is pseudo code as: qualifier_cnf[][] = new Qualifier[1]; qualifier_cnf[0] = new Qualifier[2]; qualifier_cnr[0][0] = new Qualifer(x = 5) qualifier_cnr[0][1] = new Qualifer(y = 6)

For example ((x = 5) or (x = 6)) and ((y = 1) or (y = 2)) would be represented is pseudo code as: qualifier_cnf[][] = new Qualifier[2]; qualifier_cnf[0] = new Qualifier[2]; qualifier_cnr[0][0] = new Qualifer(x = 5) qualifier_cnr[0][1] = new Qualifer(x = 6) qualifier_cnr[0][0] = new Qualifer(y = 5) qualifier_cnr[0][1] = new Qualifer(y = 6)

For each row the CNF qualfier is processed and it is determined whether or not the row should be returned to the caller. The following pseudo-code describes how this is done:

 if (qualifier != null)
 {
 
 for (int and_clause; and_clause < qualifier.length; and_clause++)
 {
 boolean or_qualifies = false;
 for (int or_clause; or_clause < qualifier[and_clause].length; or_clause++)
 {
 
 DataValueDescriptor key     = 
 qualifier[and_clause][or_clause].getOrderable();
 DataValueDescriptor row_col = 
 get row column[qualifier[and_clause][or_clause].getColumnId()];
 boolean or_qualifies = 
 row_col.compare(qualifier[i].getOperator,
 
 key,
 qualifier[i].getOrderedNulls,
 qualifier[i].getUnknownRV);
 
 if (or_qualifies)
 {
 break;
 }
 }
 if (!or_qualifies)
 {
 
 don't return this row to the client - proceed to next row;
 
 }
 

}

There may (in the future) be multiple sort inserters for a given sort, the idea being that the various threads of a parallel query plan can all insert into the sort. For now, however, only a single sort controller per sort is supported.
Parameters:
  id - The identifier of the sort to open, as returned fromcreateSort. A sort controller to use for inserting.
exception:
  StandardException - From a lower-level exception.

Return an open SortCostController which can be used to ask about the estimated costs of SortController() operations.

Parameters:
  implParameters - Properties which help in choosing implementation-specific sort options. If null, a"generally useful" sort will be used. The open StoreCostController.
exception:
  StandardException - Standard exception policy.
See Also:   StoreCostController

In the future, multiple sort scans on the same sort will be supported (for parallel execution across a uniqueness sort in which the order of the resulting rows is not important). Currently, only a single sort scan is allowed per sort.

In the future, it will be possible to open a sort scan and start retrieving rows before the last row is inserted. The sort controller would block till rows were available to return. Currently, an attempt to retrieve a row before the sort controller is closed will cause an exception.
Parameters:
  id - The identifier of the sort to scan, as returned from createSort.
Parameters:
  hold - If true, this scan will be maintained open over commits. The sort controller.
exception:
  StandardException - From a lower-level exception.

Return an open StoreCostController which can be used to ask about the estimated row counts and costs of ScanController and ConglomerateController operations, on the given conglomerate.

The open StoreCostController.
Parameters:
  conglomId - The identifier of the conglomerate to open.
exception:
  StandardException - Standard exception policy.
See Also:   StoreCostController

This call will purge committed deleted rows from the conglomerate, that space will be available for future inserts into the conglomerate.

Parameters:
  conglomId - Id of the conglomerate to purge.
exception:
  StandardException - Standard exception policy.

This function behaves the same as @see createConglomerate except it also populates the conglomerate with rows from the row source and the rows that are inserted are not logged.

Individual rows that are loaded into the conglomerate are not logged. After this operation, the underlying database must be backed up with a database backup rather than an transaction log backup (when we have them). This warning is put here for the benefit of future generation.
Parameters:
  implementation - Specifies what kind of conglomerate to create.THE WAY THAT THE IMPLEMENTATION IS CHOSEN STILL NEEDS SOME WORK.For now, use "BTREE" or "heap" for a local access manager.
Parameters:
  recreate_ifempty - If false, and the rowsource used to load the newconglomerate returns no rows, then the originalconglomid will be returned. To the client it willbe as if no call was made. Underlying implementations may actually create and drop a container.If true, then a new empty container will be created and it's conglomid will be returned.
Parameters:
  template - A row which describes the prototypicalrow that the conglomerate will be holding.Typically this row gives the conglomerateinformation about the number and type ofcolumns it will be holding. The implementationmay require a specific subclass of row type.Note that the createConglomerate call reads the template and makes a copyof any necessary information from the template, no reference to thetemplate is kept (and thus this template can be re-used in subsequentcalls - such as openScan()). This field is required when creating eithera heap or btree conglomerate.
Parameters:
  columnOrder - Specifies the colummns sort order.Useful only when the conglomerate is of type BTREE, defaultvalue is 'null', which means all columns needs to be sorted in Ascending order.
Parameters:
  properties - Implementation-specific properties of the conglomerate.
Parameters:
  temporaryFlag - If true, the conglomerate is temporary.Temporary conglomerates are only visible through the transactioncontroller that created them. Otherwise, they are opened,scanned, and dropped in the same way as permanent conglomerates.Changes to temporary conglomerates persist across commits, buttemporary conglomerates are truncated on abort (or rollbackto savepoint). Updates to temporary conglomerates are not locked or logged.
Parameters:
  orig_conglomId - The conglomid of the original conglomerate.
Parameters:
  rowSource - interface to receive rows to load into the conglomerate.
Parameters:
  rowCount - - if not null the number of rows loaded into the tablewill be returned as the first element of the array.
exception:
  StandardException - if the conglomerate could not be created orloaded for some reason. Throws SQLState.STORE_CONGLOMERATE_DUPLICATE_KEY_EXCEPTION ifthe conglomerate supports uniqueness checks and has been created todisallow duplicates, and one of the rows being loaded had key columns whichwere duplicate of a row already in the conglomerate.

if "close_controllers" is true then all conglomerates and scans are closed (held or non-held).

If "close_controllers" is false then no cleanup is done by the TransactionController. It is then the responsibility of the caller to close all resources that may have been affected by the statements backed out by the call. This option is meant to be used by the Language implementation of statement level backout, where the system "knows" what could be affected by the scope of the statements executed within the statement.

Parameters:
  name - The identifier of the SavePoint to roll back to.
Parameters:
  close_controllers - boolean indicating whether or not the controller should close open controllers.
Parameters:
  kindOfSavepoint - A NULL value means it is an internal savepoint (ie not a user defined savepoint)Non NULL value means it is a user defined savepoint which can be a SQL savepoint or a JDBC savepointA String value for kindOfSavepoint would mean it is SQL savepointA JDBC Savepoint object value for kindOfSavepoint would mean it is JDBC savepoint returns savepoint position in the stack.
exception:
  StandardException - Standard cloudscape exception policy. A statement level exception is thrown ifno savepoint exists with the given name.

A nested user transaction can be used exactly as any other TransactionController, except as follows. For this discussion let the parent transaction be the transaction used to make the startNestedUserTransaction() call, and let the child transaction be the transaction returned by the startNestedUserTransaction() call.

Only 1 non-readOnly nested user transaction can exist. If a subsequent non-readOnly transaction creation is attempted prior to destroying an existing write nested user transaction an exception will be thrown.

The nesting is limited to one level deep. An exception will be thrown if a subsequent getNestedUserTransaction() is called on the child transaction.

The locks in the child transaction of a readOnly nested user transaction will be compatible with the locks of the parent transaction. The locks in the child transaction of a non-readOnly nested user transaction will NOT be compatible with those of the parent transaction - this is necessary for correct recovery behavior.

A commit in the child transaction will release locks associated with the child transaction only, work can continue in the parent transaction at this point.

Any abort of the child transaction will result in an abort of both the child transaction and parent transaction, either initiated by an explict abort() call or by an exception that results in an abort.

A TransactionController.destroy() call should be made on the child transaction once all child work is done, and the caller wishes to continue work in the parent transaction.

AccessFactory.getTransaction() will always return the "parent" transaction, never the child transaction. Thus clients using nested user transactions must keep track of the transaction, as there is no interface to query the storage system to get the current child transaction. The idea is that a nested user transaction should be used to for a limited amount of work, committed, and then work continues in the parent transaction.

Nested User transactions are meant to be used to implement system work necessary to commit as part of implementing a user's request, but where holding the lock for the duration of the user transaction is not acceptable. 2 examples of this are system catalog read locks accumulated while compiling a plan, and auto-increment.

Once the first write of a non-readOnly nested transaction is done, then the nested user transaction must be committed or aborted before any write operation is attempted in the parent transaction.
Parameters:
  readOnly - Is transaction readonly? Only 1 non-readonly nestedtransaction is allowed per transaction. The new nested user transaction.
exception:
  StandardException - Standard exception policy.