Nonstop Database, HiRDB Version 9 UAP Development Guide

[Contents][Index][Back][Next]

18.4.2 Connection interface

Organization of this subsection
(1) Overview
(2) Methods
(3) Package and class names
(4) Notes

(1) Overview

The Connection interface provides the following principal functions:

(2) Methods

The table below lists the methods of the Connection interface. This interface does not support methods that are not listed in the table. If an unsupported method is specified, the interface throws an SQLException.

Table 18-10 Connection interface methods

Subsection Method Function
(a) clearWarnings() Clears all warnings reported for this Connection object.
(b) close() Closes the connection with HiRDB.
(c) commit() Applies all changes made since the most recent commit or rollback.
(d) createStatement() Creates a Statement object for sending an SQL statement to the database.
(e) createStatement(int resultSetType, int resultSetConcurrency) Creates a Statement object for sending an SQL statement to the database.
(f) createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) Creates a Statement object for sending an SQL statement to the database.
(g) getAutoCommit() Acquires the current automatic commit mode for this Connection object.
(h) getCatalog() Acquires the current catalog name for this Connection object.
(i) getHoldability() Acquires the current holding facility for ResultSet objects that are created by using this Connection object.
(j) getMetaData() Creates a DatabaseMetaData object.
(k) getTransactionIsolation() Acquires this Connection object's current transaction cut-off level.
(l) getTypeMap() Acquires the Map object related to this Connection object.
(m) getWarnings() Acquires as an SQLWarning object the warnings reported by calls related to this Connection object.
(n) isClosed() Acquires a value indicating whether this Connection object is closed.
(o) isReadOnly() Acquires a value indicating whether this Connection object is in read-only mode.
(p) nativeSQL(String sql) Converts any escape clause in a specified SQL statement to a format that can be executed by HiRDB, and then returns the SQL statement.
(q) prepareCall(String sql) Creates a CallableStatement object for executing a CALL statement.
(r) prepareCall(String sql, int resultSetType, int resultSetConcurrency) Creates a CallableStatement object for executing a CALL statement.
(s) prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) Creates a CallableStatement object for executing a CALL statement.
(t) prepareStatement(String sql) Creates a PreparedStatement object for sending an SQL statement with parameters to the database.
(u) prepareStatement(String sql, int resultSetType, int resultSetConcurrency) Creates a PreparedStatement object for sending an SQL statement with parameters to the database.
(v) prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) Creates a PreparedStatement object for sending an SQL statement with parameters to the database.
(w) rollback() Undoes all changes made by the current transaction and releases all database locks currently held by this Connection object.
(x) setAutoCommit(boolean autoCommit) Sets the automatic commit mode status for this connection.
(y) setCatalog(String catalog) This driver ignores this method's specification because HiRDB does not support catalogs.
(z) setHoldability(int holdability) Changes the holding facility for a ResultSet object that is created by using this Connection object.
(aa) setReadOnly(boolean readOnly) This method's value is ignored because HiRDB does not have a dedicated mode.
(ab) setTransactionIsolation(int level) This method's value is ignored because the value is always TRANSACTION_REPEATABLE_READ in HiRDB.
(ac) checkSession(int waittime) Checks the current connection status.
(ad) setHiRDB_Audit_Info(int pos, String userinf) Specifies user-specific connection information (user-added information).
(a) clearWarnings()

Function
Clears all warnings reported for this Connection object.
Once this method has been called, getWarnings() returns null until a new warning is issued for this Connection object.

Format
 
public void clearWarnings() throws SQLException
 

Arguments
None.

Return value
None.

Exceptions
If this Connection object is closed (close), the JDBC driver throws an SQLException.
(b) close()

Function
Closes the connection with HiRDB.

Format
 
public void close() throws SQLException
 

Arguments
None.

Return value
None.

Functional detail
During a normal connection, this method disconnects HiRDB, disables the corresponding objects, and releases any unneeded resources.
In a pooling or XA environment, the physical connection is not closed; instead, PooledConnection.close() is used to close the physical connection.
If execution of Connection.close() results in an error, the method does not throw an SQLException.
If execution of Connection.close() in a pooling or XA environment results in a fatal error and connection pooling becomes unavailable, ConnectionEventListener.connectionErrorOccurred() does not occur.
If the close method is called by a Connection object that is already closed, this method does nothing.

Exceptions
None.
(c) commit()

Function
Applies all changes made since the most recent commit or rollback.
If this method is called while the automatic commit mode is enabled, the method performs commit processing without throwing an exception.

Format
 
public void commit() throws SQLException
 

Arguments
None.

Return value
None.

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • A database access error occurs.
  • close() has already been issued to the Connection object.
(d) createStatement()

Function
Creates a Statement object for sending an SQL statement to the database.

Format
 
public synchronized Statement createStatement() throws SQLException
 

Arguments
None.

Return value
Statement object

Functional detail
This method creates a Statement object for sending an SQL statement to the database.
The holding facility for the ResultSet that is created from the Statement object created by this method is set to the value specified by Connection.setHoldability. If Connection.setHoldability has never been executed, the HIRDB_CURSOR property setting is used.

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • close() has already been issued to the Connection object.
  • Creation of the Statement object resulted in an error.
(e) createStatement(int resultSetType, int resultSetConcurrency)

Function
Creates a Statement object for sending an SQL statement to the database.

Format
 
public synchronized Statement createStatement(int resultSetType, int resultSetConcurrency) throws SQLException
 

Arguments
int resultSetType
Type of result set
int resultSetConcurrency
Parallel processing mode

Return value
Statement object

Functional detail
This method creates a Statement object for sending an SQL statement to the database.
If TYPE_SCROLL_SENSITIVE is specified for the type of the result set, this driver changes it to TYPE_SCROLL_INSENSITIVE and then sets an SQLWarning.
For parallel processing mode, the driver supports only CONCUR_READ_ONLY. If CONCUR_UPDATABLE is specified, the driver changes it to CONCUR_READ_ONLY and then sets an SQLWarning.
The holding facility for the ResultSet that is created from the Statement object created by this method is set to the value specified by Connection.setHoldability. If Connection.setHoldability has never been executed, the HIRDB_CURSOR property setting is used.

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • close() has already been issued to the Connection object.
  • Creation of the Statement object resulted in an error.
  • A value other than a ResultSet literal is specified for the type of the result set.
  • A value other than a ResultSet literal is specified for parallel processing mode.
(f) createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability)

Function
Creates a Statement object for sending an SQL statement to the database.

Format
 
public synchronized Statement createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException
 

Arguments
int resultSetType
Type of result set
int resultSetConcurrency
Parallel processing mode
int resultSetHoldability
Holding facility for ResultSet

Return value
Statement object

Functional detail
This method creates a Statement object for sending an SQL statement to the database.
If TYPE_SCROLL_SENSITIVE is specified for the type of the result set, this driver changes it to TYPE_SCROLL_INSENSITIVE and then sets an SQLWarning.
For parallel processing mode, the driver supports only CONCUR_READ_ONLY. If CONCUR_UPDATABLE is specified, the driver changes it to CONCUR_READ_ONLY and then sets an SQLWarning.

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • close() has already been issued to the Connection object.
  • Creation of the Statement object resulted in an error.
  • A value other than a ResultSet literal is specified for the type of the result set.
  • A value other than a ResultSet literal is specified for parallel processing mode.
  • A value other than a ResultSet literal is specified for the holding facility for the ResultSet.
(g) getAutoCommit()

Function
Acquires the current automatic commit mode for this Connection object.

Format
 
public boolean getAutoCommit() throws SQLException
 

Arguments
None.

Return value
Current automatic commit mode for the Connection object

Exceptions
If close() has already been issued to this Connection object, the JDBC driver throws an SQLException.
(h) getCatalog()

Function
Acquires the current catalog name for this Connection object.
This method always returns null.

Format
 
public synchronized String getCatalog() throws SQLException
 

Arguments
None.

Return value
This method always returns null because there is no catalog in HiRDB.

Exceptions
If close() has already been issued to this Connection object, the JDBC driver throws an SQLException.
(i) getHoldability()

Function
Acquires the current holding facility for ResultSet objects that are created by using this Connection object.
This method's return value will be the holding facility for a ResultSet object if no holding facility was specified when the Statement (PreparedStatement) object was created.

Format
 
public synchronized int getHoldability() throws SQLException
 

Arguments
None.

Return value
One of the following ResultSet types:
  • ResultSet.HOLD_CURSORS_OVER_COMMIT
  • ResultSet.CLOSE_CURSORS_AT_COMMIT

Exceptions
If close() has already been issued to this Connection object, the JDBC driver throws an SQLException.
(j) getMetaData()

Function
Creates a DatabaseMetaData object.

Format
 
public synchronized DatabaseMetaData getMetaData() throws SQLException
 

Arguments
None.

Return value
DatabaseMetaData object

Exceptions
If close() has already been issued to this Connection object, the JDBC driver throws an SQLException.
(k) getTransactionIsolation()

Function
Acquires this Connection object's current transaction cut-off level.
This method always returns TRANSACTION_REPEATABLE_READ.

Format
 
public int getTransactionIsolation() throws SQLException
 

Arguments
None.

Return value
This method always returns TRANSACTION_REPEATABLE_READ.

Exceptions
If close() has already been issued to this Connection object, the JDBC driver throws an SQLException.
(l) getTypeMap()

Function
Acquires the Map object related to this Connection object.
This driver returns an empty java.util.HashMap object that contains no information.

Format
 
public synchronized java.util.Map getTypeMap() throws SQLException
 

Arguments
None.

Return value
Empty java.util.HashMap object

Exceptions
If close() has already been issued to this Connection object, the JDBC driver throws an SQLException.
(m) getWarnings()

Function
Acquires as an SQLWarning object the warnings reported by calls related to this Connection object.

Format
 
public SQLWarning getWarnings() throws SQLException
 

Arguments
None.

Return value
First SQLWarning object (if there is no such SQLWarning object, the method returns null)

Functional detail
This method acquires the SQLWarning object held by the corresponding Connection object.
By executing the getNextWarning method of the acquired SQLWarning object, you can acquire the next warning.

Exceptions
If close() has already been issued to this Connection object, the JDBC driver throws an SQLException.
(n) isClosed()

Function
Acquires a value indicating whether this Connection object is closed.

Format
 
public boolean isClosed()
 

Arguments
None.

Return value
If this Connection object is closed, the method returns true; if not, the method returns false.

Functional detail
This method acquires a value indicating whether this Connection object is closed. The database connection is closed when the close method is called or when a specific fatal error has occurred. This method is guaranteed to return true only when this method is called after the Connection.close method. This method cannot be used to determine whether the database connection is valid.

Exceptions
None.
(o) isReadOnly()

Function
Acquires a value indicating whether this Connection object is in the read-only mode.
This driver always returns false.

Format
 
public synchronized boolean isReadOnly() throws SQLException
 

Arguments
None.

Return value
This method always returns false.

Exceptions
If close() has already been issued to this Connection object, the JDBC driver throws an SQLException.
(p) nativeSQL(String sql)

Function
Converts any escape clause in a specified SQL statement to a format that can be executed by HiRDB, and then returns the SQL statement.

Format
 
public String nativeSQL(String sql) throws SQLException
 

Arguments
String sql
SQL statement that has not been converted

Return value
SQL statement that can be executed by HiRDB (if the sql argument is NULL, the method returns NULL; if it is the null character, the method returns the null character)

Functional detail
This method converts any escape clause in a specified SQL statement to a format that can be executed by HiRDB, and then returns the SQL statement.
The following are the syntax rules for escape clauses:
escape-clause ::= escape-sequence-for-date-or-time-or-timestamp
              | LIKE-escape-sequence
              | outer-join-escape-sequence
              | procedure-call-escape-sequence
              | scalar-function-escape-sequence
              | assignment-escape-sequence
 
escape-sequence-for-date-or-time-or-timestamp ::= date-escape-sequence
                                          | time-escape-sequence
                                          | timestamp-escape-sequence
 
date-escape-sequence ::=
          escape-start-code d default-character-string-representation-of-date-data escape-end-code
 
time-escape-sequence ::=
          escape-start-code t default-character-string-representation-of-time-data escape-end-code
 
timestamp-escape-sequence ::=
          escape-start-code ts default-character-string-representation-of-timestamp-data escape-end-code
 
LIKE-escape-sequence ::=
          escape-start-code escape escape-character escape-end-code
 
outer-join-escape-sequence ::= escape-start-code oj joined-table escape-end-code
 
procedure-call-escape-sequence ::=
          escape-start-code call [authorization identifier.]routine-identifier
          [([argument[,argument]...])] escape-end-code
 
assignment-escape-sequence ::= escape-start-code set assignment-statement escape-end-code
 
scalar-function-escape-sequence ::= escape-start-code fn scalar-function escape-end-code
scalar-function ::= scalar-function-in-default-format#
 
escape-start-code ::= '{'
escape-end-code ::= '}'

#
For details about the scalar function in the default format, see Appendix I. Scalar Functions That Can Be Specified in the Escape Clause.

For details about the underlined parts, see the manual HiRDB Version 9 SQL Reference. Note that an escape clause cannot be specified in an underlined part. Because the JDBC driver does not perform syntax analysis on the underlined parts, they will remain the same after conversion and will be subject to syntax analysis by the HiRDB server.

The following keywords can be used in escape sequences (these keywords are not case sensitive):

  1. d in a date escape sequence
  2. t in a time escape sequence
  3. ts in a timestamp escape sequence
  4. escape in a LIKE escape sequence
  5. oj in an outer join escape sequence
  6. call in a procedure call escape sequence
  7. fn in a scalar function escape sequence
  8. set in an assignment escape sequence

The escape clause entry rules are as follows:

The following table shows the escape clause conversion rules.

Table 18-11 Escape clause conversion rules

Escape clause Before conversion After conversion
Date escape-start-code d default-character-string-representation-of-date-data escape-end-code default-character-string-representation-of-date-data
Time escape-start-code t default-character-string-representation-of-time-data escape-end-code default-character-string-representation-of-time-data
Timestamp escape-start-code ts default-character-string-representation-of-timestamp-data escape-end-code default-character-string-representation-of-timestamp-data
LIKE escape-start-code escape escape-character escape-end-code escape escape-character
Outer join escape-start-code oj joined-table escape-end-code joined-table
Procedure call escape-start-code call [authorization identifier.]routine-identifier[([argument[,argument]...])] escape-end-code

For HiRDB connection:
call[authorization identifier.]routine-identifier([argument[,argument]...])#1

For XDM/RD E2 connection:
call[authorization identifier.]routine-identifier[([argument[,argument]...])]
Scalar function escape-start-code fn scalar-function escape-end-code scalar-function-in-HiRDB-format#2
Assignment escape-start-code set assignment-statement escape-end-code set assignment-statement

#1
If the parentheses following the routine identifier are missing, the driver adds them.

#2
For details about the conversion processing, see conversion processing for the scalar function escape clause below.

The driver converts a scalar function in the default format to the HiRDB format. For an XDM/RD E2 connection, the driver converts it to the XDM/RD E2 format.

If a HiRDB scalar function corresponding to the default format is HiRDB's system-defined scalar function, the driver adds MASTER at the beginning of the function name.

Table 18-12 shows the conversion formats of scalar functions whose default format differs from the HiRDB format of scalar functions, and Table 18-13 shows the conversion formats of scalar functions whose default format differs from the XDM/RD E2 format.

In general, the driver does not check the number of arguments in scalar functions. However, if the scalar function name is LOCATE, the driver converts a comma indicating an argument delimiter to IN or FROM, thereby checking the number of arguments.

Table 18-12 Conversion formats of scalar functions whose default format differs from the HiRDB format

Scalar function Format before conversion Format after conversion (HiRDB format)
Mathematical function CEILING(number) MASTER.CEIL(number)
LOG(float) MASTER.LN(float)
TRUNCATE(number, places) MASTER.TRUNC(number, places)
String functions CHAR(code) MASTER.CHR(code)
INSERT(string1, start, length, string2) MASTER.INSERTSTR(string1, start, length, string2)
LCASE(string) LOWER(string)
LEFT(string, count) MASTER.LEFTSTR(string, count)
LOCATE(string1, string2[, start]) POSITION(string1 IN string2 [FROM start])
RIGHT(string, count) MASTER.RIGHTSTR(string, count)
SUBSTRING(string, start, length) SUBSTR(string, start, length)
UCASE(string) UPPER(string)
Time and date functions CURDATE() CURRENT DATE
CURRENT_DATE() CURRENT DATE
CURTIME() CURRENT TIME
CURRENT_TIME() CURRENT TIME
CURRENT_TIME(time-precision) CURRENT TIME
NOW() CURRENT TIMESTAMP(6)
System function USER() USER

Table 18-13 Conversion formats of scalar functions whose default format differs from the XDM/RD E2 format

Scalar function Format before conversion Format after conversion (XDM/RD E2 format)
Mathematical function LOG(float) LN(float)
String functions LCASE(string) LOWER(string)
LOCATE(string1, string2[, start]) POSITION(string1 IN string2 [FROM start])
LTRIM(string) TRIM(LEADING FROM string)
RTRIM(string) TRIM(TRAILING FROM string)
SUBSTRING(string, start, length) SUBSTR(string, start, length)
UCASE(string) UPPER(string)
Time and date functions CURDATE() CURRENT DATE
CURRENT_DATE() CURRENT DATE
CURTIME() CURRENT TIME
CURRENT_TIME() CURRENT TIME
NOW() CURRENT TIMESTAMP(6)
System function USER() USER

The following shows examples of conversion for HiRDB connection:

Scalar function Before conversion After conversion
Scalar function whose default format is the same as the HiRDB format System built-in scalar function {fn ABS(number)} ABS(number)
System-defined scalar function {fn ASCII(string)} MASTER.ASCII(string)
Scalar function whose default format differs from the HiRDB format System built-in scalar function {fn UCASE(string)} UPPER(string)
System-defined scalar function {fn CEILING(number)} MASTER.CEIL(number)

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • close() has already been issued to this Connection object.
  • The format of an escape clause in the specified SQL statement is invalid:
    [Figure] { and a keyword are specified, but } is missing.
    [Figure] There is no procedure name after {call.
    [Figure] There is no space between {call and the procedure name.
    [Figure] {call procedure-name( is not followed by ).
    [Figure] {? = call is specified.
    [Figure] The LOCATE function is specified in an escape clause, but no argument is specified.
    [Figure] The LOCATE function is specified in an escape clause, but the number of arguments within the parentheses is invalid.
    [Figure] For XDM/RD E2 connection, the LTRIM or RTRIM function is specified in an escape clause, but no argument is specified.
(q) prepareCall(String sql)

Function
Creates a CallableStatement object for executing a CALL statement.

Format
 
public synchronized CallableStatement prepareCall(String sql) throws SQLException
 

Arguments
String sql
SQL statement to be executed (you can specify a statement other than the CALL statement)

Return value
CallableStatement object

Functional detail
This method creates a CallableStatement object for executing a CALL statement.
The holding facility for the ResultSet that is created from the CallableStatement object created by this method is set to the value specified by Connection.setHoldability. If Connection.setHoldability has never been executed, the HIRDB_CURSOR property setting is used.

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • close() has already been issued to this Connection object.
  • Creation of the CallableStatement object resulted in an error.
(r) prepareCall(String sql, int resultSetType, int resultSetConcurrency)

Function
Creates a CallableStatement object for executing a CALL statement.

Format
 
public synchronized CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency) throws SQLException
 

Arguments
String sql
SQL statement to be executed (you can specify a statement other than the CALL statement)
int resultSetType
Type of result set
int resultSetConcurrency
Parallel processing mode

Return value
CallableStatement object

Functional detail
This method creates a CallableStatement object for executing a CALL statement.
If TYPE_SCROLL_SENSITIVE is specified for the type of the result set, this driver changes it to TYPE_SCROLL_INSENSITIVE and then sets an SQLWarning.
For parallel processing mode, the driver supports only CONCUR_READ_ONLY. If CONCUR_UPDATABLE is specified, the driver changes it to CONCUR_READ_ONLY and then sets an SQLWarning.
The holding facility for the ResultSet that is created from the CallableStatement object created by this method is set to the value specified by Connection.setHoldability. If Connection.setHoldability has never been executed, the HIRDB_CURSOR property setting is used.

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • close() has already been issued to this Connection object.
  • Creation of the CallableStatement object resulted in an error.
  • A value other than a ResultSet literal is specified for the type of the result set.
  • A value other than a ResultSet literal is specified for parallel processing mode.
(s) prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)

Function
Creates a CallableStatement object for executing a CALL statement.

Format
 
public synchronized CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException
 

Arguments
String sql
SQL statement to be executed (you can specify a statement other than the CALL statement)
int resultSetType
Type of result set
int resultSetConcurrency
Parallel processing mode
int resultSetHoldability
Holding facility for ResultSet

Return value
CallableStatement object

Functional detail
This method creates a CallableStatement object for executing a CALL statement.
If TYPE_SCROLL_SENSITIVE is specified for the type of the result set, this driver changes it to TYPE_SCROLL_INSENSITIVE and then sets an SQLWarning.
For parallel processing mode, the driver supports only CONCUR_READ_ONLY. If CONCUR_UPDATABLE is specified, the driver changes it to CONCUR_READ_ONLY and then sets an SQLWarning.

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • close() has already been issued to this Connection object.
  • Creation of the CallableStatement object resulted in an error.
  • A value other than a ResultSet literal is specified for the type of the result set.
  • A value other than a ResultSet literal is specified for parallel processing mode.
  • A value other than a ResultSet literal is specified for the holding facility for the ResultSet.
(t) prepareStatement(String sql)

Function
Creates a PreparedStatement object for sending an SQL statement with parameters to the database.

Format
 
public synchronized PreparedStatement prepareStatement(String sql) throws SQLException
 

Arguments
String sql
SQL statement to be executed

Return value
PreparedStatement object

Functional detail
This method creates a PreparedStatement object for sending an SQL statement with parameters to the database.
The holding facility for the ResultSet that is created from the PreparedStatement object created by this method is set to the value specified by Connection.setHoldability. If Connection.setHoldability has never been executed, the HIRDB_CURSOR property setting is used.

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • close() has already been issued to this Connection object.
  • Creation of the PreparedStatement object resulted in an error.
(u) prepareStatement(String sql, int resultSetType, int resultSetConcurrency)

Function
Creates a PreparedStatement object for sending an SQL statement with parameters to the database.

Format
 
public synchronized PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency) throws SQLException
 

Arguments
String sql
SQL statement to be executed (you can specify a statement other than the CALL statement)
int resultSetType
Type of result set
int resultSetConcurrency
Parallel processing mode

Return value
PreparedStatement object

Functional detail
This method creates a PreparedStatement object for sending an SQL statement with parameters to the database.
If TYPE_SCROLL_SENSITIVE is specified for the type of the result set, this driver changes it to TYPE_SCROLL_INSENSITIVE and then sets an SQLWarning.
For parallel processing mode, the driver supports only CONCUR_READ_ONLY. If CONCUR_UPDATABLE is specified, the driver changes it to CONCUR_READ_ONLY and then sets an SQLWarning.
The holding facility for the ResultSet that is created from the PreparedStatement object created by this method is set to the value specified by Connection.setHoldability. If Connection.setHoldability has never been executed, the HIRDB_CURSOR property setting is used.

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • close() has already been issued to this Connection object.
  • Creation of the PreparedStatement object resulted in an error.
  • A value other than a ResultSet literal is specified for the type of the result set.
  • A value other than a ResultSet literal is specified for parallel processing mode.
(v) prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)

Function
Creates a PreparedStatement object for sending an SQL statement with parameters to the database.

Format
 
public synchronized PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException
 

Arguments
String sql
SQL statement to be executed (you can specify a statement other than the CALL statement)
int resultSetType
Type of result set
int resultSetConcurrency
Parallel processing mode
int resultSetHoldability
Holding facility for ResultSet

Return value
PreparedStatement object

Functional detail
This method creates a PreparedStatement object for sending an SQL statement with parameters to the database.
If TYPE_SCROLL_SENSITIVE is specified for the type of the result set, this driver changes it to TYPE_SCROLL_INSENSITIVE and then sets an SQLWarning.
For parallel processing mode, the driver supports only CONCUR_READ_ONLY. If CONCUR_UPDATABLE is specified, the driver changes it to CONCUR_READ_ONLY and then sets an SQLWarning.

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • close() has already been issued to this Connection object.
  • Creation of the PreparedStatement object resulted in an error.
  • A value other than a ResultSet literal is specified for the type of the result set.
  • A value other than a ResultSet literal is specified for parallel processing mode.
  • A value other than a ResultSet literal is specified for the holding facility for the ResultSet.
(w) rollback()

Function
Undoes all changes made by the current transaction and releases all database locks currently held by this Connection object.
If you call this method while the automatic commit mode is enabled, the method performs rollback processing without throwing an exception.

Format
 
public void rollback() throws SQLException
 

Arguments
None.

Return value
None.

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • A database access error has occurred.
  • close() has already been issued to the Connection object.
(x) setAutoCommit(boolean autoCommit)

Function
Sets the automatic commit mode status for this connection.

Format
 
public void setAutoCommit(boolean autoCommit) throws SQLException
 

Arguments
boolean autoCommit
Specifies true to enable the automatic commit mode and false to disable it.

Return value
None.

Functional detail
This method sets the automatic commit mode status for this connection. When a connection is in automatic commit mode, each of its SQL statements is committed as a separate transaction after it has executed. When a connection is not in automatic commit mode, its SQL statements are grouped as transactions to be terminated by a call to the commit method or as transactions to be terminated by a call to the rollback method. The default mode for a new connection is automatic commit mode.
Automatic commit is performed upon completion of an SQL statement. If the SQL statement returns a ResultSet object, the SQL statement is completed when the ResultSet object is closed.
A transaction that is executing when this method is called will not be committed.

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • This Connection object is running under a distributed transaction.
  • close() has already been issued to this Connection object.
(y) setCatalog(String catalog)

Function
This driver ignores this method's specification because HiRDB does not support catalogs.

Format
 
public synchronized void setCatalog(String catalog) throws SQLException
 

Arguments
String catalog
Ignores the specified value because there is no catalog in HiRDB.

Return value
This method always returns false.

Exceptions
If close() has already been issued to this Connection object, the JDBC driver throws an SQLException.
(z) setHoldability(int holdability)

Function
Changes the holding facility for a ResultSet object that is created by using this Connection object.

Format
 
public synchronized void setHoldability(int holdability) throws SQLException
 

Arguments
int holdability
Holding facility literals for ResultSet (ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT)

Return value
None.

Functional detail
This method changes the holding facility for a ResultSet object that is created by using this Connection object.
The value of this method is the setting for createStatement (prepareStatement, prepareCall) that is called without the holding facility specified. It has no effect on an existing Statement or a ResultSet that is created (has been created) by that Statement.
The following table shows the default value for the holding facility.

Table 18-14 Default value for holding facility

HiRDB_CURSOR property value Default value
TRUE ResultSet.HOLD_CURSORS_OVER_COMMIT
FALSE ResultSet.CLOSE_CURSORS_AT_COMMIT
Not specified ResultSet.CLOSE_CURSORS_AT_COMMIT

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • close() has already been issued to this Connection object.
  • A value other than ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT is specified in the holdability argument.
(aa) setReadOnly(boolean readOnly)

Function
This method's value is ignored because HiRDB does not have a dedicated mode.

Format
 
public synchronized void setReadOnly(boolean readOnly) throws SQLException
 

Arguments
boolean readOnly
The specified value is ignored because there is no dedicated mode in HiRDB.

Return value
None.

Exceptions
If close() has already been issued to this Connection object, the JDBC driver throws an SQLException.
(ab) setTransactionIsolation(int level)

Function
This method's value is ignored because the value is always TRANSACTION_REPEATABLE_READ in HiRDB.

Format
 
public void setTransactionIsolation(int level) throws SQLException
 

Arguments
int level
Transaction cut-off level

Return value
None.

Exceptions
If close() has already been issued to this Connection object, the JDBC driver throws an SQLException.
(ac) checkSession(int waittime)

Function
Checks the current connection status.

Format
 
public int checkSession (int waittime) throws SQLException
 

Arguments
int waittime:
Specifies the wait time (in seconds). If 0 is specified, the JDBC driver waits until the time specified by the PDCWAITTIME client environment definition.

Return value
PrdbConnection.SESSION_ALIVE:
The method was able to confirm that a connection is currently established.
PrdbConnection.SESSION_NOT_ALIVE:
Because of a cause other than a timeout within the time specified in the argument, the method was unable to confirm that a connection is currently established.
PrdbConnection.SESSION_CHECK_TIMEOUT:
Because of a timeout within the time specified in the argument, the method was unable to confirm that a connection is currently established.

Exceptions
If the waittime argument is a negative value, the driver throws a java.sql.SQLException.
(ad) setHiRDB_Audit_Info(int pos, String userinf)

Function
Specifies user-specific connection information (user-added information).

Format
 
public void  setHiRDB_Audit_Info(int pos, String userinf) throws SQLException
 

Arguments
int pos
Item number of the user-added information:
1: User-added information 1
2: User-added information 2
3: User-added information 3
String userinf
User-added information. The data specified for user-added information is converted to the character set specified in the ENCODELANG property during connection establishment, or the setEncodeLang method, or the HiRDB server's character codes during HiRDB character data processing. Specify data whose length will not exceed 100 bytes after code conversion. To cancel an existing setting, specify the NULL value.

Return value
None.

Functional detail
This method specifies user-added information, such as the account information for an application that accesses the HiRDB server. The specified user-added information remains in effect until it is canceled. The specified user-added information is output to the audit trail when an SQL statement that uses the Statement, PreparedStatement, or CallableStatement object created by using the corresponding Connection object is executed.
This method corresponds to the specification of user-specific connection information (DECLARE AUDIT INFO SET) in an embedded SQL statement.

Exceptions
The JDBC driver throws an SQLException in the following cases:
  • The corresponding Connection object is closed.
  • Code conversion of user-added information fails.
  • A value other than 1, 2, or 3 is specified in pos.
  • The length of the data obtained after code conversion of the user-added information exceeds 100 bytes.

(3) Package and class names

The names of the package and class for installing this interface are as follows:

Package name: JP.co.Hitachi.soft.HiRDB.JDBC

Class name: PrdbConnection

(4) Notes

(a) Holdability specification

If holdability is specified with one of the methods shown below, the HIRDB_CURSOR specification value in either the URL syntax or the properties can be overwritten for each Statement object (Statement, PreparedStatement or CallableStatement object) and Connection object:

For ResultSet and DatabaseMetaData objects (when the setHoldability method is used) generated by the applicable method, the holdability specifications that become effective change depending on the combinations of these specifications and the HIRDB_CURSOR specifications.

Table 18-5 shows the holdability specifications that become effective for Statement objects generated by the following methods:

 

Table 18-15 Effective holdability specifications (1/2)

HIRDB_CURSOR or setHiRDBCursorMode specification Specification value of resultSetHoldability argument
ResultSet.
HOLD_CURSORS_OVER_COMMIT
ResultSet.
CLOSE_CURSORS_AT_COMMIT
Execution of SELECT statement with UNTIL DISCONNECT specified Execution of other SQL statement
TRUE specified for HIRDB_CURSOR in properties TRUE specified for HIRDB_CURSOR in URL syntax T T F
FALSE specified for HIRDB_CURSOR in URL syntax T T F
FALSE specified for HIRDB_CURSOR in properties TRUE specified for HIRDB_CURSOR in URL syntax T T F
FALSE specified for HIRDB_CURSOR in URL syntax T T F
true specified for setHiRDBCursorMode T T F
false specified for setHiRDBCursorMode T T F

Legend:
T: The JDBC driver operates as if TRUE were specified for HIRDB_CURSOR.
F: The JDBC driver operates as if FALSE were specified for HIRDB_CURSOR.

Table 18-16 shows the holdability specifications that become effective for Statement or DatabaseMetaData objects generated by methods other than the Table 18-15 methods.

Table 18-16 Effective holdability specifications (2/2)

HIRDB_CURSOR or setHiRDBCursorMode specification Specification value of setHoldability method No execution of setHoldability method
ResultSet.
HOLD_CURSORS_OVER_COMMIT
ResultSet.
CLOSE_CURSORS_AT_COMMIT
Execution of SELECT statement with UNTIL DISCONNECT specified Execution of other SQL statement Execution of SELECT statement with UNTIL DISCONNECT specified Execution of other SQL statement
TRUE specified for HIRDB_CURSOR in properties TRUE specified for HIRDB_CURSOR in URL syntax T T F T T
FALSE specified for HIRDB_CURSOR in URL syntax T T F T F
FALSE specified for HIRDB_CURSOR in properties TRUE specified for HIRDB_CURSOR in URL syntax T T F T T
FALSE specified for HIRDB_CURSOR in URL syntax T T F T F
true specified for setHiRDBCursorMode T T F T T
false specified for setHiRDBCursorMode T T F T F

Legend:
T: The JDBC driver operates as if TRUE were specified for HIRDB_CURSOR.
F: The JDBC driver operates as if FALSE were specified for HIRDB_CURSOR.

For details about HIRDB_CURSOR, see 18.2.2 Connecting to HiRDB with the getConnection method.