# package sqlj.runtime

## Interface Index

- ConnectionContext
- ForUpdate
- NamedIterator
- PositionedIterator
- ResultSetIterator

## Class Index

- AsciiStream
- BinaryStream
- DefaultRuntime
- ExecutionContext
- RuntimeContext
- StreamWrapper
- UnicodeStream

## Exception Index

- SQLNullException
Interface sqlj.runtime.ConnectionContext

# Interface sqlj.runtime.ConnectionContext

public interface ConnectionContext

A connection context manages a set of SQL operations performed during a session with a specific database. A connection context maintains an JDBC Connection instance on which dynamic SQL operations may be performed. It also contains a default execution context object by which sql operation execution semantics may be queried and modified.

In addition to those methods defined by this interface, each concrete implementation of a connection context, UserCtx, will provide the following methods:

-     public static Object getProfileKey(sqlj.runtime.profile.Loader l, String profileName) throws SQLException;

  Returns a profile key for a particular profile loader and name.

-     public static sqlj.runtime.profile.Profile getProfile(Object key);

  Returns a top-level profile for a particular profile key

-     public static UserCtx getDefaultContext();

  Returns the default context for the UserCtx class.

-     public static void setDefaultContext(UserCtx dflt);

  Sets the default context for the UserCtx class.

-     public UserCtx(java.sql.Connection conn) throws SQLException;

-     public UserCtx(String url, String user, String pwd, boolean autoCommit) throws SQLException;

-     public UserCtx(String url, Properties info, boolean autoCommit) throws SQLException;

-     public UserCtx(String url, boolean autoCommit) throws SQLException;

-     public UserCtx(ConnectionContext other) throws SQLException;

Note that for any context constructor which creates a JDBC connection during construction, that connection will be automatically closed if the constructor call throws an exception. For any context constructor which uses an already opened JDBC connection (or context) passed from the client, that connection (or context) will remain open even if the constructor call throws an exception.

## Variable Index

o CLOSE_CONNECTION
  Underlying JDBC Connection should be closed
o KEEP_CONNECTION
  Underlying JDBC Connection should not be closed

## Method Index

o close()
  Releases all resources used in maintaining database state on this context, closes any open connected profiles, and closes the underlying jdbc connection.
o close(boolean)
  Releases all resources used in maintaining database state on this context and closes any open connected profiles manages by this context.
o getConnectedProfile(Object)
  Returns the connected profile associated with a profileKey for this connection context instance.
o getConnection()
  Returns the underlying jdbc connection object associated with this context instance.
o getExecutionContext()
  Returns the default execution context used by this connection context.
o isClosed()
  returns true if this context has been closed, false otherwise.

## Variables

o CLOSE_CONNECTION

     public static final boolean CLOSE_CONNECTION

  Underlying JDBC Connection should be closed

  See Also:
    close

o KEEP_CONNECTION

     public static final boolean KEEP_CONNECTION

  Underlying JDBC Connection should not be closed

  See Also:
    close

## Methods

o getConnectedProfile

     public abstract ConnectedProfile getConnectedProfile(Object profileKey) throws SQLException

  Returns the connected profile associated with a profileKey for this connection context instance. Each connection context maintains a set of connected profiles on which sql operation statements are prepared. Collectively, the set of connected profiles contained in a connection context represent the set of all possible sql operations that may be performed in the lifetime of this context instance.

  The profileKey object must be an object that was returned via a prior call to getProfileKey(). An exception is raised if a connected profile instance could not be created for this connection context.

  Parameters:
    profileKey - the key asscoiated with the desired profile.
  Throws: IllegalArgumentException
    if the profileKey is null or invalid.
  Throws: SQLException
    if the connected profile instance could not be created.

o getConnection

     public abstract Connection getConnection()

  Returns the underlying jdbc connection object associated with this context instance. Note that depending on construction, the returned connection may be shared between many connection context instances.

o close

     public abstract void close() throws SQLException

  Releases all resources used in maintaining database state on this context, closes any open connected profiles, and closes the underlying jdbc connection. This method is equivalent to `close(CLOSE_CONNECTION)`

  Throws: SQLException
    if unable to close the context
  See Also:
    close

o close

     public abstract void close(boolean closeConnection) throws SQLException

  Releases all resources used in maintaining database state on this context and closes any open connected profiles manages by this context. Since the underlying JDBC connection managed by this context may be shared between mutliple context objects, it is not always desireable to close the underlying JDBC Connection `close` is called. If the constant KEEP_CONNECTION is passed, the underlying jdbc connection is not closed. Otherwise, if the constant CLOSE_CONNECTION, the underlying connection is closed.

  Note: A context is automatically closed when it is garbage collected. A context closed in such a way does not close the underlying JDBC connection since it will also be automatically closed when it is garbage collected.

  Parameters:
    closeConnection - is true if the underlying Connection should also be closed.
  Throws: SQLException
    if unable to close the context
  See Also:
    KEEP_CONNECTION, CLOSE_CONNECTION

o isClosed

     public abstract boolean isClosed()

  returns true if this context has been closed, false otherwise.

  See Also:
    close, close

o getExecutionContext

     public abstract ExecutionContext getExecutionContext()

  Returns the default execution context used by this connection context. The default execution context is the execution context used if no explicit context is supplied during the execution of a particular sql operation.

  Returns:
    the default excution context

Interface sqlj.runtime.ForUpdate

# Interface sqlj.runtime.ForUpdate

public interface ForUpdate

An interface implemented by iterators which will be used in a positioned update or delete statement (as parameter to a WHERE CURRENT OF clause). Any iterator which is to be passed as a parameter to a WHERE CURRENT OF clause must implement this interface.

## Method Index

o getCursorName()
  Get the name of the SQL cursor used by this iterator.

## Methods

o getCursorName

     public abstract String getCursorName() throws SQLException

  Get the name of the SQL cursor used by this iterator.

  In SQL, a result table is retrieved through a cursor that is named. The current row of a result can be updated or deleted using a positioned update/delete statement that references the cursor name.

  SQLJ supports this SQL feature by providing the name of the SQL cursor used by an iterator. The current row of an iterator is also the current row of this SQL cursor.

  Note: If positioned update is not supported a SQLException is thrown

  Returns:
    the iterator's SQL cursor name
  Throws: SQLException
    if a database-access error occurs.

Interface sqlj.runtime.NamedIterator

# Interface sqlj.runtime.NamedIterator

public interface NamedIterator
extends ResultSetIterator

An interface implemented by all iterators that employ a by-name binding strategy. All such iterators depend on the name of the columns of the data to which they are bound, as opposed to the order of the columns to which they are bound.

In addition to implementing this interface, name-bound iterator implementations will provide:

- A public constructor which takes an RTResultSet as a parameter. If the construction of a named iterator results in an exception being thrown, it is assumed that the iterator automatically closes the underlying result set. This only applies to exceptions thrown during construction.
- An accessor method for each column in the expected result. The name of the accessor method will match the expected name of the result column.

Interface sqlj.runtime.PositionedIterator

# Interface sqlj.runtime.PositionedIterator

public interface PositionedIterator
extends ResultSetIterator

An interface implemented by all iterators that employ a by-position binding strategy. All such iterators depend on the position of the columns of the data to which they are bound, as opposed to the names of the columns to which they are bound.

In addition to implementing this interface, position-bound iterator implementations will provide:

- A public constructor which takes an RTResultSet as a parameter. If the construction of a positioned iterator results in an exception being thrown, it is assumed that the iterator automatically closes the underlying result set. This only applies to exceptions thrown during construction.
- An accessor method for each column in the expected result. The name of the accessor method for the Nth column will be getColN.

## Method Index

o endFetch()
  Returns true iff the iterator is not positioned on a row.

## Methods

o endFetch

     public abstract boolean endFetch() throws SQLException

  Returns true iff the iterator is not positioned on a row. This method is used to determine the success of a FETCH..INTO statement; it returns true if the last attempt to fetch a row failed, false if the last attempt was successful. Rows are attempted to be fetched when the `next` method is called (which is called implicitely during the execution of a FETCH..INTO statement). Note: If `next` has not yet been called, this method returns true;

  A common usage of this method is as follows:

      while (true) {
       #sql { FETCH :c INTO ... };
       if (c.endFetch()) break;
       ...
      }

  Throws: SQLException
    if a databse access error occurs
  See Also:
    next

Interface sqlj.runtime.ResultSetIterator

# Interface sqlj.runtime.ResultSetIterator

public interface ResultSetIterator

An interface that defines the shared functionality of those objects used to iterate over the contents of a result set.

## Variable Index

o ASENSITIVE
  Constant used by the "sensitivity" field, indicating that the iterator is defined to have an asensitive cursor.
o INSENSITIVE
  Constant used by the "sensitivity" field, indicating that the iterator is defined to have an insensitive cursor.
o SENSITIVE
  Constant used by the "sensitivity" field, indicating that the iterator is defined to have a sensitive cursor.

## Method Index

o close()
  Closes the iterator object, releasing any underlying resources.
o getResultSet()
  Returns the JDBC result set associated with this iterator.
o isClosed()
o next()
  Advances the iterator to the next row.

## Variables

o ASENSITIVE

     public static final int ASENSITIVE

  Constant used by the "sensitivity" field, indicating that the iterator is defined to have an asensitive cursor.

o INSENSITIVE

     public static final int INSENSITIVE

  Constant used by the "sensitivity" field, indicating that the iterator is defined to have an insensitive cursor.

o SENSITIVE

     public static final int SENSITIVE

  Constant used by the "sensitivity" field, indicating that the iterator is defined to have a sensitive cursor.

## Methods

o close

     public abstract void close() throws SQLException

  Closes the iterator object, releasing any underlying resources. It is recommended that iterators be explicitely closed as soon as they are no longer needed to allow for the immediate release of resources that are no longer needed.

  Note: If it is not already closed, an iterator is automatically closed when it is garbage collected.

  Throws: SQLException
    If there is a problem closing the iterator.
  See Also:
    isClosed

o isClosed

     public abstract boolean isClosed() throws SQLException

  Returns:
    true if the `close` method on this iterator has been called, false otherwise.
  Throws: SQLException
    if an error occurs determining the close-status of the iterator.
  See Also:
    close

o next

     public abstract boolean next() throws SQLException

  Advances the iterator to the next row. At the begining the iterator is positioned before the first row.

  Note: A FETCH..INTO statement performs an implicit `next` call on the iterator passed.

  Returns:
    true if there was a next row in the iterator, false otherwise.
  Throws: SQLException
    If an exception occurs while changing the position of the iterator.

o getResultSet

     public abstract ResultSet getResultSet() throws SQLException

  Returns the JDBC result set associated with this iterator. The result set produced must have normal JDBC functionality, as defined in the JDBC specification (in particular, SQL NULL values fetched with primitive accessor methods will not raise a SQLNullException). This method is provided to facilitate interoperablity with JDBC.

  Notes:

  - Support for this method is implementor defined and not part of Core SQLJ. An SQLException will be thrown if this method is not supported.
  - If an implementor supports this method, then any synchronization between the iterator and the produced result set is implementor defined.
  - For maximum portability this method should be invoked before the first `next` method invocation on the iterator. Once the result set has been produced, all operations to fetch data should be through the result set.

  Returns:
    a JDBC result set for this iterator.
  Throws: SQLException
    if no result set is available for this iterator.

Class sqlj.runtime.AsciiStream

# Class sqlj.runtime.AsciiStream

    java.lang.Object
       |
       +----java.io.InputStream
               |
               +----java.io.FilterInputStream
                       |
                       +----sqlj.runtime.StreamWrapper
                               |
                               +----sqlj.runtime.AsciiStream

public class AsciiStream
extends StreamWrapper

An InputStream-derived class whose bytes should be interpreted as ASCII. When passing an InputStream as an input parameter to a executable sql operation, both the length of the InputStream and the way to interpret its bytes must be specified. Therefore, an InputStream cannot be passed directly, but rather must be an instance of AsciiStream, BinaryStream or UnicodeStream.

See Also:
  BinaryStream, UnicodeStream

## Constructor Index

o AsciiStream(InputStream)
  Creates an Ascii-valued input stream with an uninitialized length.
o AsciiStream(InputStream, int)
  Creates an Ascii-valued input stream of given length.

## Constructors

o AsciiStream

     public AsciiStream(InputStream in)

  Creates an Ascii-valued input stream with an uninitialized length.

  Note: the length attribute must be set via a call to `setLength()` before use of an AsciiStream as an input (or in-out) parameter to an executable sql operation.

  Parameters:
    in - the InputStream to interpret as an AsciiStream.

o AsciiStream

     public AsciiStream(InputStream in,
                        int length)

  Creates an Ascii-valued input stream of given length.

  Parameters:
    in - the InputStream to interpret as an AsciiStream.
    length - the length in bytes of the AcsiiStream

Class sqlj.runtime.BinaryStream

# Class sqlj.runtime.BinaryStream

    java.lang.Object
       |
       +----java.io.InputStream
               |
               +----java.io.FilterInputStream
                       |
                       +----sqlj.runtime.StreamWrapper
                               |
                               +----sqlj.runtime.BinaryStream

public class BinaryStream
extends StreamWrapper

An InputStream-derived class whose bytes should be interpreted as binary. When passing an InputStream as an input parameter to an executable sql operation, both the length of the InputStream and the way to interpret its bytes must be specified. Therefore, an InputStream cannot be passed directly, but rather must be an instance of AsciiStream, BinaryStream or UnicodeStream.

See Also:
  AsciiStream, UnicodeStream

## Constructor Index

o BinaryStream(InputStream)
  Creates a Binary-valued input stream with an uninitialized length.
o BinaryStream(InputStream, int)
  Creates a Binary-valued input stream of given length.

## Constructors

o BinaryStream

     public BinaryStream(InputStream in)

  Creates a Binary-valued input stream with an uninitialized length.

  Note: the length attribute must be set via a call to setLength() before use of an BinaryStream as an input (or in-out) parameter to an executable sql operation.

  Parameters:
    in - the InputStream to interpret as a BinaryStream.

o BinaryStream

     public BinaryStream(InputStream in,
                         int length)

  Creates a Binary-valued input stream of given length.

  Parameters:
    in - the InputStream to interpret as an BinaryStream.
    length - the length in bytes of the BinaryStream

Class sqlj.runtime.DefaultRuntime

# Class sqlj.runtime.DefaultRuntime

    java.lang.Object
       |
       +----sqlj.runtime.RuntimeContext
               |
               +----sqlj.runtime.DefaultRuntime

public class DefaultRuntime
extends RuntimeContext

The default runtime context is implemented to satisfy the expected runtime behavior of sqlj for most java virtual machine environments.

## Constructor Index

o DefaultRuntime()

## Method Index

o getDefaultConnection()
  By default, there is no implicit connection available.
o getLoaderForClass(Class)
  Creates and returns a default loader object which uses the class loader of the passed class.

## Constructors

o DefaultRuntime

     public DefaultRuntime()

## Methods

o getLoaderForClass

     public Loader getLoaderForClass(Class forClass)

  Creates and returns a default loader object which uses the class loader of the passed class.

  Parameters:
    forClass - the class with which the resulting loader is to be associated.
  Returns:
    a default loader for the passed class
  Overrides:
    getLoaderForClass in class RuntimeContext
  See Also:
    DefaultLoader

o getDefaultConnection

     public Connection getDefaultConnection()

  By default, there is no implicit connection available. Accordingly, this method always returns null.

  Returns:
    null
  Overrides:
    getDefaultConnection in class RuntimeContext

Class sqlj.runtime.ExecutionContext

# Class sqlj.runtime.ExecutionContext

    java.lang.Object
       |
       +----sqlj.runtime.ExecutionContext

public class ExecutionContext
extends Object

An execution context provides the context in which executable sql operations are preformed. An execution context object contains a number of operations for execution control, execution status, and execution cancellation. Execution control operations modify the semantics of subsequent sql operations executed on this context. Execution status operations describe the results of the last sql operation executed on this context. Execution cancellation methods terminate the currently executing sql operation on this context.

Note that concurrently executing sql operations are expected to use distinct execution contexts. The execution context implementation is not expected to support multiple sql operations executing using the same execution context object. The client is responsible for insuring the proper creation of distinct execution context instance where needed, or synchronizing the execution of operations on a particular execution context.

See Also:
  getExecutionContext

## Variable Index

o EXCEPTION_COUNT
  Constant returned by getUpdateCount indicating that an exeception was thrown before the last execution was successfully completed, or no operation has yet been attempted on this context.
o QUERY_COUNT
  Constant returned by getUpdateCount indicating that the last execution produced a result set or iterator.

## Constructor Index

o ExecutionContext()

## Method Index

o cancel()
  The cancel method can be used by one thread to cancel a sql operation that is currently being executed by another thread using this context.
o execute()
  Performs a generic execute on the currently registered statement.
o executeQuery()
  Performs an execute query on the currently registered statement.
o executeUpdate()
  Performs an execute update on the currently registered statement.
o getMaxFieldSize()
  The max field size limit (in bytes) is the maximum amount of data returned for any column value for sql operations subsequently executed using this context; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns.
o getMaxRows()
  The max rows limit is the maximum number of rows that any ResultSetIterator or jdbc ResultSet returned by sql operations subsequently executed using this context can contain.
o getNextResultSet()
  Moves to the currently registered statement's next result.
o getQueryTimeout()
  The query timeout limit is the maxiumum number of seconds sql opeations subsequently executed using this context may take to complete.
o getUpdateCount()
  Returns the number of rows updated by the last sql operation executed using this context.
o getWarnings()
  Returns the first warning reported by the last sql operation executed using this context.
o registerStatement(ConnectionContext, Object, int)
  Creates, registers and returns a statement.
o releaseStatement()
  Releases the currently registered statement, signaling that all execution-related operations have completed.
o setMaxFieldSize(int)
  The max field size limit (in bytes) is the maximum amount of data returned for any column value for sql operations subsequently executed using this context; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns.
o setMaxRows(int)
  The max rows limit is the maximum number of rows that any ResultSetIterator or jdbc ResultSet returned by sql operations subsequently executed using this context can contain.
o setQueryTimeout(int)
  The query timeout limit is the maxiumum number of seconds sql opeations subsequently executed using this context may take to complete.

## Variables

o QUERY_COUNT

     public static final int QUERY_COUNT

  Constant returned by getUpdateCount indicating that the last execution produced a result set or iterator.

  See Also:
    getUpdateCount

o EXCEPTION_COUNT

     public static final int EXCEPTION_COUNT

  Constant returned by getUpdateCount indicating that an exeception was thrown before the last execution was successfully completed, or no operation has yet been attempted on this context.

  See Also:
    getUpdateCount

## Constructors

o ExecutionContext

     public ExecutionContext()

## Methods

o getMaxFieldSize

     public int getMaxFieldSize()

  The max field size limit (in bytes) is the maximum amount of data returned for any column value for sql operations subsequently executed using this context; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns. These columns may be fetched into Java targets of type byte[], String, or stream. The limit effects both out and in-out parameters passed, and the result returned from any executable sql operation. If the limit is exceeded, the excess data is silently discarded.

  By default, the max field size limit is zero (unlimited)

  Returns:
    the current max field size limit; zero means unlimited

o setMaxFieldSize

     public void setMaxFieldSize(int max)

  The max field size limit (in bytes) is the maximum amount of data returned for any column value for sql operations subsequently executed using this context; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns. These columns may be fetched into Java targets of type byte[], String, or stream. The limit effects both out and in-out parameters passed, and the result returned from any executable sql operation. If the limit is exceeded, the excess data is silently discarded. For maximum portability use values greater than 256.

  By default, the max field size limit is zero (unlimited)

  Note: max field size is an optional feature that may not be supported by some implementations. Setting max field size to a non-default value may cause an SQLException to be raised when an SQL operation is executed using this context.

  Parameters:
    max - the new max field size limit; zero means unlimited

o getMaxRows

     public int getMaxRows()

  The max rows limit is the maximum number of rows that any ResultSetIterator or jdbc ResultSet returned by sql operations subsequently executed using this context can contain. If the limit is exceeded, the excess rows are silently dropped.

  By default, the max rows limit is zero (unlimited)

  Returns:
    the current max rows limit; zero means unlimited

o setMaxRows

     public void setMaxRows(int max)

  The max rows limit is the maximum number of rows that any ResultSetIterator or jdbc ResultSet returned by sql operations subsequently executed using this context can contain. If the limit is exceeded, the excess rows are silently dropped.

  By default, the max rows limit is zero (unlimited)

  Note: max rows is an optional feature that may not be supported by some implementations. Setting max rows to a non-default value may cause an SQLException to be raised when an SQL operation is executed using this context.

  Parameters:
    max - the new max rows limit; zero means unlimited

o getQueryTimeout

     public int getQueryTimeout()

  The query timeout limit is the maxiumum number of seconds sql opeations subsequently executed using this context may take to complete. If execution of the sql operation exceeds the limit, a SQLException is thrown.

  By default, the query timeout limit is zero (unlimited)

  Returns:
    the current query timeout limit in seconds; zero means unlimited

o setQueryTimeout

     public void setQueryTimeout(int seconds)

  The query timeout limit is the maxiumum number of seconds sql opeations subsequently executed using this context may take to complete. If execution of the sql operation exceeds the limit, a SQLException is thrown.

  By default, the query timeout limit is zero (unlimited)

  Note: query timeout is an optional feature that may not be supported by some implementations. Setting query timeout to a non-default value may cause an SQLException to be raised when an SQL operation is executed using this context.

  Parameters:
    seconds - the new query timeout limit in seconds; zero means unlimited

o getWarnings

     public SQLWarning getWarnings()

  Returns the first warning reported by the last sql operation executed using this context. Subsequent warnings resultant from the same operation will be chained to this SQLWarning. The SQLWarning chain returned represents those warnings which occured during the execution of the last sql operation and the subsequent binding of any output host variables.

  Returns:
    the first SQLWarning or null if no warnings occurred

o getUpdateCount

     public int getUpdateCount()

  Returns the number of rows updated by the last sql operation executed using this context. 0 is returned if the last sql operation was not a DML statement. QUERY_COUNT is returned if the last sql operation produced an iterator or result set. EXCEPTION_COUNT is returned if an exception occurred before the last sql operation completed execution, or no operation has yet been attempted.

  Returns:
    the number of rows updated by the last operation

o cancel

     public void cancel() throws SQLException

  The cancel method can be used by one thread to cancel a sql operation that is currently being executed by another thread using this context. Note that this method has no effect if there is no statement currently being executed for this execution context.

  Throws: SQLException
    if unable to cancel
  See Also:
    executeUpdate, executeQuery

o registerStatement

     public synchronized RTStatement registerStatement(ConnectionContext connCtx,
                                                       Object profileKey,
                                                       int stmtNdx) throws SQLException

  Creates, registers and returns a statement. This method is called by generated code. Most programmers will not need to call it directly.

  The statement is created by accessing the connected profile within connection context "connCtx" that has the key "profileKey". The statement at index "stmtNdx" in the connected profile is created using the `getStatement` method.

  The statement created is registered and becomes the current statement of this execution context. All warnings are cleared, and updateCount is initialized to EXCEPTION_COUNT.

  For each of the max rows, max field size, and query timeout attributes of this execution context, if the attribute has a non-default value, then the corresponding attribute of the registered statement is set to this value. An exception is raised if the statement does not support setting the attribute. The attributes of the execution context contained by the passed connection context are not used by this method.

  If there is another statement currently executing on this execution context, an exception is raised. Note that if this method throws an exception, no statement will be registered.

  Parameters:
    connCtx - the connection context that contains the profile that contains the statement to register.
    profileKey - the key of the connected profile within the connection context.
    stmtNdx - the 0-based index of the statement within the profile to be registered.
  Throws: SQLException
    if there is another statement currently executing or the max fields size, max rows, or query timeout cannot be set on the registered statement.
  See Also:
    releaseStatement, getStatement, getConnectedProfile

o executeUpdate

     public int executeUpdate() throws SQLException

  Performs an execute update on the currently registered statement. The update count is updated accordingly.

  Note: This method is called by generated code. Most programmers will not need to call it directly.

  Returns:
    the result of calling executeUpdate on the currently registered statement
  Throws: SQLException
    if an error occurs during the execution of the currently registered statement.
  See Also:
    executeUpdate, registerStatement

o executeQuery

     public RTResultSet executeQuery() throws SQLException

  Performs an execute query on the currently registered statement. The update count is set to QUERY_COUNT.

  Note: This method is called by generated code. Most programmers will not need to call it directly.

  Returns:
    the result of calling executeRTQuery on the currently registered statement
  Throws: SQLException
    if an error occurs during the execution of the currently registered statement.
  See Also:
    executeRTQuery, registerStatement

o execute

     public boolean execute() throws SQLException

  Performs a generic execute on the currently registered statement. Under some situations a single SQL CALL statement may return multiple result sets. The "execute" and "getNextResultSet" methods allow navigation through multiple results.

  The "execute" method executes the currently registered statement and returns true if it produced a side-channel result set, false otherwise. The getNextResultSet method is used to obtain the result set. Update count is set to QUERY_COUNT.

  Notes:

  - This method is called by generated code. Most programmers will not need to call it directly. Instead, they will use only "getNextResultSet" to navigate multiple results.
  - If the current operation produces multiple results, it is not released until all results have been processed, and getNextResultSet returns null.
  - If this operation also produces side-channel update counts, they are silently discarded.
  - If an error occurs executing the SQL operation, the current statement is released and an SQLException is raised. Subsequent calls to "getNextResultSet" will return null.

  Returns:
    true if the statement produced a side-channel result set, false otherwise.
  Throws: SQLException
    if an error occurs during the execution of the currently registered statement.
  See Also:
    execute, registerStatement, getNextResultSet

o getNextResultSet

     public ResultSet getNextResultSet() throws SQLException

  Moves to the currently registered statement's next result. The first time this method is called after a SQL operation is executed, the first side-channel result set is returned (if any). Further calls to getNextResultSet will move to any subsequent results. getNextResultSet implicitly closes any open result set previously obtained with getNextResultSet.

  getNextResultSet returns null when there are no further results. null is also returned if the last SQL operation executed did not produce side-channel results, or an SQL operation has not yet been executed on this execution context.

  Notes:

  - If the last SQL operation executed on this execution context produced multiple results, its resources are not released until all results have been processed, and getNextResultSet returns null. In such cases, this execution context cannot be used to execute further SQL operations until all results have been processed.
  - If this operation also produces side-channel update counts, they are silently discarded.
  - If an error occurs during a call to getNextResultSet, the current statement is released and an SQLException is raised. Subsequent calls to getNextResultSet will return null.

  Returns:
    the next side-channel result set, or null if there are no further results.
  Throws: SQLException
    if an error occurs obtaining the next result set.
  See Also:
    getResultSet, getMoreResults, execute, registerStatement

o releaseStatement

     public synchronized void releaseStatement() throws SQLException

  Releases the currently registered statement, signaling that all execution-related operations have completed. After this method has been returned from, it is safe to call registerStatement again. The SQL warnings are updated as reflected by the registered statement.

  This method calls the `executeComplete` method of the registered statement.

  If the execution of the currently registered statement produced multiple results and not all results have been processed, then this operation is a no-op. In such cases, this method will be automatically called to release the statement once all results have been processed and getMoreResults returns NO_MORE_RESULTS.

  Note: This method is called by generated code. Most programmers will not need to call it directly.

  Throws: SQLException
    if an error occurs retrieving the warnings
  See Also:
    registerStatement, executeComplete

Class sqlj.runtime.RuntimeContext

# Class sqlj.runtime.RuntimeContext

    java.lang.Object
       |
       +----sqlj.runtime.RuntimeContext

public abstract class RuntimeContext
extends Object

The runtime context defines system-specific services to be provided by the runtime environment. The runtime context is an abstract class whose implementation may vary according to the Java VM environment.

## Variable Index

o DEFAULT_RUNTIME
  The fully qualified class name of the default runtime implementation used when no other implementation has been defined for a VM environment.
o PROPERTY_KEY
  The key under which the RuntimeContext implementation class name is stored in the system properties.

## Constructor Index

o RuntimeContext()

## Method Index

o getDefaultConnection()
  Returns the default connection object, if one exists, or null otherwise.
o getLoaderForClass(Class)
  Returns a loader associated with a class.
o getRuntime()
  Returns the runtime context associated with the current java virtual machine instance.

## Variables

o PROPERTY_KEY

     public static final String PROPERTY_KEY

  The key under which the RuntimeContext implementation class name is stored in the system properties.

o DEFAULT_RUNTIME

     public static final String DEFAULT_RUNTIME

  The fully qualified class name of the default runtime implementation used when no other implementation has been defined for a VM environment.

  See Also:
    DefaultRuntime

## Constructors

o RuntimeContext

     public RuntimeContext()

## Methods

o getRuntime

     public static RuntimeContext getRuntime()

  Returns the runtime context associated with the current java virtual machine instance. Each java virtual machine instance has a single unique runtime context instance. Subsequent calls to this method within the same VM instace will return the same object. The appropriate runtime context implementation is discovered by examining the value of the RuntimeContext.PROPERTY_KEY System property. If this property is set, it will indicate the full name of a class that is able to be instantiated as a runtime context instance. If no such property is defined or access to this system property is not allowed, the class given by RuntimeContext.DEFAULT_RUNTIME is used.

  Note: all runtime implementations must be able to be constructed via the `Class.newInstance` method. That is, they must have a public no-arg constructor.

  Returns:
    the runtime instance
  See Also:
    PROPERTY_KEY, DEFAULT_RUNTIME

o getLoaderForClass

     public abstract Loader getLoaderForClass(Class forClass)

  Returns a loader associated with a class. Resources and classes loaded from this loader will be found in the same location that the passed class was found in. Note that the definition of location may vary depending on class loading and resolution semantics of the runtime implementation.

  It is assumed that the passed class argument contains enough information that a java virtual machine implementation will be able to determine the location in which to find related resources. Most VM implementations will be able to use the passed class's class loader (or the system class loader if the class has no loader). However, some VM implementations may need additional information to resolve resources. For example, a VM running in a DB server might use the schema in which the passed class is located to search for related resources.

  Parameters:
    forClass - the class with which the resulting loader is to be associated.

o getDefaultConnection

     public abstract Connection getDefaultConnection()

  Returns the default connection object, if one exists, or null otherwise. Some enviornments may have an implicit connection object available. For example, a virtual machine running in a DB server might have an implicit connection associated with the current session.

  Returns:
    the default connection, or null if none exists.

Class sqlj.runtime.StreamWrapper

# Class sqlj.runtime.StreamWrapper

    java.lang.Object
       |
       +----java.io.InputStream
               |
               +----java.io.FilterInputStream
                       |
                       +----sqlj.runtime.StreamWrapper

public class StreamWrapper
extends FilterInputStream

This class wraps a particular InputStream instance. It also extends the InputStream class by providing direct call-throughs to the wrapped InputStream for all methods. Additionally, it supports a length attribute which allows subclasses to be passed as input-parameters to executable sql operations.

See Also:
  InputStream

## Constructor Index

o StreamWrapper(InputStream)
  Creates a new StreamWrapper using the bytes in the passed InputStream.
o StreamWrapper(InputStream, int)
  Creates a new StreamWrapper using the bytes in the passed InputStream.

## Method Index

o getInputStream()
  Returns the underlying input stream which is being wrapped.
o getLength()
  Returns the length in bytes of the wrapped InputStream, as specified during construction or in the last call to setLength().
o setLength(int)
  Sets the length attribute of the wrapped stream to be the passed value.

## Constructors

o StreamWrapper

     protected StreamWrapper(InputStream in)

  Creates a new StreamWrapper using the bytes in the passed InputStream. The length of the input stream is uninitialized.

  Parameters:
    in - the input stream to wrap

o StreamWrapper

     protected StreamWrapper(InputStream in,
                             int length)

  Creates a new StreamWrapper using the bytes in the passed InputStream. The length of the input stream is initialized to the length field passed.

  Parameters:
    in - the input stream to wrap
    length - the length of the input stream in bytes

## Methods

o getInputStream

     public InputStream getInputStream()

  Returns the underlying input stream which is being wrapped. The client is free to get and set this field for reuse with different input streams, but should also set the length attribute to match.

o getLength

     public int getLength()

  Returns the length in bytes of the wrapped InputStream, as specified during construction or in the last call to setLength().

  Returns:
    the length in bytes of the input stream

o setLength

     public void setLength(int length)

  Sets the length attribute of the wrapped stream to be the passed value. This does not effect the wrapped InputStream, but will effect the number of bytes read from it when it is passed as an input parameter to an executable sql operation.

  Parameters:
    length - the new length of the InputStream in bytes

Class sqlj.runtime.UnicodeStream

# Class sqlj.runtime.UnicodeStream

    java.lang.Object
       |
       +----java.io.InputStream
               |
               +----java.io.FilterInputStream
                       |
                       +----sqlj.runtime.StreamWrapper
                               |
                               +----sqlj.runtime.UnicodeStream

public class UnicodeStream
extends StreamWrapper

An InputStream-derived class whose bytes should be interpreted as Unicode. When passing an InputStream as an input parameter to an executable sql operation, both the length of the InputStream and the way to interpret its bytes must be specified. Therefore, an InputStream cannot be passed directly, but rather must be an instance of AsciiStream, BinaryStream or UnicodeStream.

See Also:
  AsciiStream, BinaryStream

## Constructor Index

o UnicodeStream(InputStream)
  Creates a Unicode-valued input stream with an uninitialized length.
o UnicodeStream(InputStream, int)
  Creates a Unicode-valued input stream of given length.

## Constructors

o UnicodeStream

     public UnicodeStream(InputStream in)

  Creates a Unicode-valued input stream with an uninitialized length.

  Note: the length attribute must be set via a call to setLength() before use of an UnicodeStream as an input (or in-out) parameter to a executable sql operation.

  Parameters:
    in - the InputStream to interpret as a UnicodeStream.

o UnicodeStream

     public UnicodeStream(InputStream in,
                          int length)

  Creates a Unicode-valued input stream of given length.

  Parameters:
    in - the InputStream to interpret as an UnicodeStream.
    length - the length in bytes of the UnicodeStream

Class sqlj.runtime.SQLNullException

# Class sqlj.runtime.SQLNullException

    java.lang.Object
       |
       +----java.lang.Throwable
               |
               +----java.lang.Exception
                       |
                       +----java.sql.SQLException
                               |
                               +----sqlj.runtime.SQLNullException

public class SQLNullException
extends SQLException

The SQLNullException class is a particular instance of SQLException used in the case that SQL NULL was attemped to be fetched into a java primitive type. This exception is raised by all conformant runtimes when such a condition occurs.

The SQLState for a SQLNullException is "22002" (null value, no indicator variable).

## Constructor Index

o SQLNullException()
  Create a SQLNullException object.

## Constructors

o SQLNullException

     public SQLNullException()

  Create a SQLNullException object. The SQLState is initialized to 22002, and the vendorCode is set to the SQLException default.