Entering content frame

Function documentation com.sap.sql.BatchExecutionContext Locate the document in its SAP Library structure

Use

com.sap.sql.BatchExecutionContext extends sqlj.runtime.ExecutionContext

A Batch ExecutionContext is a subclass of ExecutionContext. In Open SQL / SQLJ, DML statements (INSERT, UPDATE, DELETE) are batchable only if they are executed using a BatchExecutionContext.

Initially, a BatchExecutionContext is clean (that is, it is not associated with a statement batch). If a DML statement is executed through the BatchExecutionContext, a new statement batch is prepared for this DML statement. If the same DML statement is executed on this BatchExecutionContext with different parameters, the parameters are added to the batch for deferred execution. The statement batch is executed either explicitly by the exceuteBatch() method or implicitly when a certain batch limit is reached. After the execution, the BatchExecutionContext is clean again. Now, any DML statement or query can be executed using this BatchExecutionContext.

If a statement batch is pending, only the DML statement that the BatchExecutionContext is associated with (the statement with exactly the same source code position) can be added to the batch. Any other DML statement or query is rejected by a runtime exception.

Constants

These constants are inherited from sqlj.runtime.ExecutionContext:

public static final int ADD_BATCH_COUNT

Constant returned by getUpdateCount() if the last statement encountered was added to the existing statement batch rather than being executed.

public static final int AUTO_BATCH

Constant passed to setBatchLimit()or returned by getBatchLimit(), indicating that implicit batch execution should be performed and that the actual batch size is at the discretion of the Open SQL / SQLJ runtime.

public static final int EXEC_BATCH_COUNT

Constant returned by getUpdateCount() if the last execution was a statement batch execution.

public static final int EXCEPTION_COUNT

Constant returned by getUpdateCount()if an exception was thrown before the last execution was successfully completed, or if no operation has yet been attempted on this ExecutionContextobject.

public static final int NEW_BATCH_COUNT

Constant returned by getUpdateCount()if the last statement encountered was added to a new statement batch rather than being executed.

public static final int QUERY_COUNT

Constant returned by getUpdateCount()if the last execution produced a result set iterator.

public static final int UNLIMITED_BATCH

Constant passed to setBatchLimit()or returned by getBatchLimit(), indicating that no implicit batch execution should be performed once a certain batch size is reached.

Constructor

public BatchExecutionContext ()

This is the default constructor for the Batch ExecutionContext class. Batching is always switched on for an BatchExecutionContext object. Initially, the batch limit is set to UNLIMITED_BATCH.

Methods

public void cancel () throws SQLException

This method enables a pending batch to be cleared. Note that if the implicit batching is switched on, the batch may already have been partly executed.

public synchronized int[] executeBatch () throws SQLException

Executes the pending statement batch contained in this BatchExecutionContext object, and returns the result as an array of update counts containing one element for each command in the batch. The array is ordered according to the order in which commands were inserted into the batch. Each element either contains a non-negative update count, or the value -2 as a generic success indicator, or the value -3 as a generic failure indicator. Failure may also be indicated by an array that has fewer elements than the number of commands in the batch. In this case, each element must contain either a non-negative update count or the value -2 as a generic success indicator.

If no pending statement batch exists for this BatchExecutionContext object, null is returned.

Following a direct or exceptional return from this method, the update count is set to EXEC_BATCH_COUNT. If this method returns successfully, the batch update counts of this BatchExecutionContext object are updated to reflect the return result.

Once this method is called, the statement batch is emptied even if the call results in an exception. Subsequent calls to this method return null until another batchable statement is added.

Note that exceptions returned by this method will generally be instances of java.sql.BatchUpdateException.

public synchronized int getBatchLimit ()

Returns the current batch limit that was set for this BatchExecutionContext:

·        UNLIMITED_BATCH (the default), if the maximum batch size is unlimited,

·        AUTO_BATCH, if the maximum batch size is finite and implementation-dependent.

·        n > 0, if the maximum batch size is the value n.

public int[] getBatchUpdateCounts ()

Returns an array of update counts containing one element for each command in the last statement batch to successfully complete execution. The array is ordered according to the order in which commands were inserted ino the batch. Each element either contains a non-negative update count, or the value -2 as a generic success indicator, or the value -3 as a generic failure indicator. Failure may also be indicated by an array that has fewer elements than the number of commands in the batch. In this case, each element must contain either a non-negative update count or the value -2 as a generic success indicator.

Returns null if no statement batch has completed execution on this BatchExecutionContext.

public synchronized int getUpdateCount ()

Returns the update count, defined as the number of rows modified by the last executable SQL operation to complete execution using this execution context object.

The method returns

·        QUERY_COUNT, if the last SQL operation was a query,

·        NEW_BATCH_COUNT, if the last SQL operation was batchable (a DML statement) and was added as the first member of a new statement batch,

·        ADD_BATCH_COUNT, if the last SQL operation was batchable and was added to the current statement batch,

·        EXEC_BATCH_COUNT, if the statement batch has been executed (either explicitly by the exceuteBatch() method or implicitly on reaching the batch limit),

·        EXCEPTION_COUNT, if an exception occurred before the last SQL operation completed execution.

Otherwise, the value returned is undefined.

public synchronized boolean isBatching ()

This method always returns true (batching is always enabled on a BatchExecutionContext).

public synchronized void setBatching (boolean doBatch)

Batching cannot be switched off on a BatchExecutionContext. If this method is invoked with the argument false, an IllegalArgumentException will be thrown.

public synchronized void setBatchLimit (int batchLimit)

Sets the maximum batch size. When the maximum batch size is exceeded, implicit batch execution is performed: 

·        When the constant UNLIMITED_BATCH is specified, the maximum batch size is unlimited, and cannot be exceeded. New BatchExecutionContext objects are always created with UNLIMITED_BATCH.

·        When a positive, non-zero batchLimit is specified, an implicit batch execution will be performed whenever the number of batched statements reaches the value batchLimit.

¡        When the constant AUTO_BATCH is specified, the batch size is determined by the SQLJ runtime.

This method only affects statements encountered after it is called. It does not affect statements that have previously been or are currently being executed, nor does it affect the pending statement batch.

 

 

Leaving content frame