Nonstop Database, HiRDB Version 9 UAP Development Guide
The getConnection method of the DriverManager class is provided in the following three formats, each with its own set of arguments:
The arguments (url, user, password, and info) in these method formats specify connection information that is needed in order to connect to HiRDB.
When connection to HiRDB is established successfully, the JDBC driver returns a reference to a Connection class instance as the result of calling the method. However, the method throws an SQLException in the following cases:
The following table describes the information to be specified in the getConnection method arguments.
Table 18-1 Specification details of the getConnection method arguments
Argument | Specification details | External driver#1 | Internal driver#2 |
---|---|---|---|
String url | Specifies the URL. For details, see (1) URL syntax. | Y | Y |
String user | Specifies the authorization identifier. If the null value is specified, the JDBC driver assumes that no authorization identifier has been specified. If the character string has a length of 0, the method throws an SQLException and user is set to aa....aaa, which are characters embedded in the KFPJ20212-E message. For details about the specification priorities, see 18.11 Connection information priorities. |
Y | N |
String password | Specifies the password. For details about the specification priorities, see 18.11 Connection information priorities. If the null value is specified, or if a character string of length 0 is specified, the JDBC driver assumes that no password was specified. |
Y | N |
Properties info | Specifies various connection information items. For details, see (2) User properties. | Y | Y |
This section explains the URL syntax supported by the JDBC driver.
You must not specify any spaces within an item or between items in a URL. Note that the item names are case sensitive.
jdbc:hitachi:hirdb[://[DBID=additional-connection-information] [,DBHOST=database-host-name] [,ENCODELANG=conversion-character-set] [,HIRDB_CURSOR=cursor-operation-mode] [,STATEMENT_COMMIT_BEHAVIOR=Statement-object-status-after-commit-execution] [,JDBC_IF=whether-to-obtain-JDBC-interface-method-traces] [,TRC_NO=trace-entries-count] [,SQLWARNING_IGNORE=whether-to-return-warning-information] [,LONGVARBINARY_ACCESS=method-of-accessing-BLOB-and-BINARY-types] [,SQL_IN_NUM=?-parameters-count] [,SQL_OUT_NUM=output-parameters-count] [,SQLWARNING_LEVEL=warning-retention-level] [,LONGVARBINARY_ACCESS_SIZE=LONGVARBINARY-data-access-size] [,MAXBINARYSIZE=maximum-size-of-LONGVARBINARY-data] [,LONGVARBINARY_TRUNCERROR=whether-to-throw-exceptions] [,STATEMENT_CLOSE_BEHAVIOR=whether-to-ignore-preprocessing-results] [,HiRDB_INI=directory-path-of-HiRDB.INI-file] [,USER=user-name] [,PASSWORD=password] [,UAPNAME=application-name] [,BATCHEXCEPTION_BEHAVIOR=whether-to-set-JDBC-standard-compliant-update-count] ] |
@ |
Table 18-2 HiRDB character codes and corresponding conversion character sets
HiRDB character codes (character code set with pdntenv or pdsetup command) |
Conversion character set to be specified |
---|---|
lang-c | ISO8859_1 |
sjis | SJIS or MS932# |
ujis | EUC_JP |
utf-8 | UTF-8 |
chinese | EUC_CN |
chinese-gb18030 | GB18030 |
The notes that follow apply to specification of HIRDB_CURSOR and STATEMENT_COMMIT_BEHAVIOR.
PreparedStatement pstmt1 = con.prepareStatement("lock table tb1"); PreparedStatement pstmt2 = con.prepareStatement("lock table tb2"); pstmt1.execute(); //Does not trigger an error. con.commit(); pstmt2.execute(); //Triggers an error. pstmt1.close(); pstmt2.close(); |
Result set returned by procedure | HIRDB_CURSOR setting | |
---|---|---|
TRUE | FALSE | |
Holdable cursor | Usable after commit processing. | If an operation performed after commit processing involves a database access, an error will result.# |
Non-holdable cursor | If an operation performed after commit processing involves a database access, an error will result. | If an operation performed after commit processing involves a database access, an error will result. |
Table 18-3 Status of ResultSet objects and Statement objects after commit execution
STATEMENT_COMMIT_BEHAVIOR specification value | HIRDB_CURSOR specification value | |
---|---|---|
TRUE | FALSE | |
TRUE |
|
|
FALSE |
|
Table 18-4 Return values of the DatabaseMetaData method
STATEMENT_COMMIT_BEHAVIOR specification value | HIRDB_CURSOR specification value | |
---|---|---|
TRUE | FALSE | |
TRUE |
|
|
FALSE |
|
[A] pstmt1=con.prepareStatement("select c1 from tb1"); [1] [B] rs1=pstmt1.executeQuery(); [2] [C] rs1.next() [3] [D] v1=rs1.getInt(1) [4] [E] rs1.next() [5] [F] v1=rs1.getInt(1) [6] [G] rs1.close() [7] |
COMMIT timing | H=T and S=T#1 | H=F and S=T#2 | H=F and S=F#3 |
---|---|---|---|
[A] | [1]-[7]: Operates normally. | ||
[B] | [1]-[7]: Operates normally. | [1], [2], and [7]: Operates normally. [3]-[6]: Throws an SQLException. |
|
[C] | [1]-[7]: Operates normally. | [1], [2], and [7]: Operates normally. [3]-[6]: Throws an SQLException. |
|
[D] | [1]-[7]: Operates normally. | [1]-[3] and [7]: Operates normally. [4]-[6]: Throws an SQLException. |
|
[E] | [1]-[7]: Operates normally. | [1]-[4] and [7]: Operates normally. [5] and [6]: Throws an SQLException. |
|
[F] | [1]-[7]: Operates normally. | [1]-[5] and [7]: Operates normally. [6]: Throws an SQLException. |
|
[G] | [1]-[7]: Operates normally. |
The table below shows the properties that you can specify in the getConnection method of the DriverManager class. If the null value is specified for a property, the JDBC driver assumes that specification was omitted.
Table 18-5 Properties that can be specified in the getConnection method
Item | Property | Specified information |
---|---|---|
(a) | user | Authorization identifier |
(b) | password | Password |
(c) | UAPNAME | UAP identifier |
(d) | JDBC_IF | Whether or not a JDBC interface method trace is to be obtained |
(e) | TRC_NO | Number of entries in the JDBC interface method trace |
(f) | ENCODELANG | Conversion character set for the HiRDB character codes of the connection destination |
(g) | SQLWARNING_IGNORE | Whether a warning returned from the database is to be retained by the Connection object |
(h) | HIRDB_CURSOR | Cursor operation mode |
(i) | LONGVARBINARY_ACCESS | Method of accessing a JDBC SQL-type LONGVARBINARY (BLOB and BINARY types, which are HiRDB data types) database |
(j) | HiRDB_for_Java_SQL_IN_NUM | Maximum number of input ? parameters in the SQL statements to be executed |
(k) | HiRDB_for_Java_SQL_OUT_NUM | Maximum number of output items for the SQL statements to be executed |
(l) | HiRDB_for_Java_SQLWARNING_LEVEL | Retention level for warning information that is issued during execution of SQL statements |
(m) | HiRDB_for_Java_ENV_VARIABLES | HiRDB client environment variables |
(n) | HiRDB_for_Java_STATEMENT_COMMIT_BEHAVIOR | Statement object status after commit execution |
(o) | HiRDB_for_Java_LONGVARBINARY_ACCESS_SIZE | Length of JDBC SQL-type LONGVARBINARY data to be requested at one time to the HiRDB server |
(p) | HiRDB_for_Java_MAXBINARYSIZE | Maximum data size during acquisition of JDBC SQL-type LONGVARBINARY data |
(q) | HiRDB_for_Java_LONGVARBINARY_TRUNCERROR | Whether or not an exception is to be thrown if truncation occurs during acquisition of JDBC SQL-type LONGVARBINARY data |
(r) | HiRDB_for_Java_STATEMENT_CLOSE_BEHAVIOR | Whether preprocessing results are to be ignored during execution of the close method of the Statement (Statement, PreparedStatement, and CallableStatement classes) |
(s) | HiRDB_for_Java_DBID | Additional connection information |
(t) | HiRDB_for_Java_DBHOST | Host name |
(u) | HiRDB_for_Java_HiRDB_INI | Directory path of the HiRDB.INI file |
(v) | HiRDB_for_Java_BATCHEXCEPTION_BEHAVIOR | Whether an update count that is compliant with the JDBC standard is to be set |
Specifies the authorization identifier.
If the null value is specified, the JDBC driver assumes that no authorization identifier was specified. If the character string has a length of 0, the JDBC driver throws an SQLException.
If this specification is omitted, either the PDNAMEPORT HiRDB client environment definition specified by HiRDB_for_Java_ENV_VARIABLES in the Properties argument of the getConnection method, or the PDUSER value in the HiRDB environment variable group specified for DBID in the URL takes effect. For details about the specification priorities, see 18.11 Connection information priorities.
If neither value is specified, the JDBC driver throws an SQLException when the getConnection method is executed.
Note that this property specification is ignored for an internal driver.
Specifies the password.
If the specification value is the null or has a length of 0, the JDBC driver assumes that no password was specified.
For details about when this specification is omitted, see 18.11 Connection information priorities.
Note that this property specification is ignored for an internal driver.
Specifies UAP identification information (UAP identifier) for accessing the HiRDB server.
In the following cases, the JDBC driver assumes that no authorization identifier was specified:
For details about character strings that can be specified, see the description of the PDCLTAPNAME client environment definition in 6.6.4 Environment definition information.
For details about when this specification is omitted, see 18.11 Connection information priorities.
Note that this property specification is ignored for an internal driver.
Specifies whether or not a JDBC interface method trace is to be obtained.
If this specification is omitted, OFF is assumed.
If any other value is specified, the JDBC driver throws an SQLException.
This property is ignored in the following cases:
For details about the JDBC interface method trace, see 18.14 JDBC interface method trace.
~<unsigned integer>((10-1000))<<500>>
Specifies the number of entries in the JDBC interface method trace.
The specification of this property is enabled when both of the following conditions are satisfied:
Note that this property specification is ignored for an internal driver.
If the specification of this property is enabled but the specification value is invalid, the JDBC driver throws an SQLException.
For details about a JDBC interface method trace, see 18.14 JDBC interface method trace.
Specifies the conversion character set for the HiRDB character codes of the connection destination when the JDBC driver uses the String class to exchange data with HiRDB.
Select a specifiable conversion character set from the encoding list shown under Internationalization in the JavaTM 2 SDK, Standard Edition documentation.
For the character codes of HiRDB and their corresponding conversion character sets, see Table 18-2 HiRDB character codes and corresponding conversion character sets.
If OFF is specified, the JDBC driver operates assuming that the applicable conversion character set for the HiRDB character codes, as shown in Table 18-2 HiRDB character codes and corresponding conversion character sets, was specified. If the HiRDB character codes are sjis, the conversion characters determined by the OS running the JDBC driver are as follows:
Note that the specification is case sensitive (except for OFF).
If a conversion character set that the Java Virtual Machine does not support is specified, the JDBC driver throws an SQLException during connection with the HiRDB server.
If this specification is omitted, the JDBC driver converts characters using the conversion character set specified by ENCODELANG in the URL.
Specifies whether warnings returned from the database are to be retained by the Connection object.
If this specification is omitted, the value specified for SQLWARNING_IGNORE in the URL takes effect. If the specified value is neither TRUE nor FALSE, the JDBC driver throws an SQLException.
Retention of warnings for the Connection object is determined by the value of HiRDB_for_Java_SQLWARNING_LEVEL. For details about the warning retention levels, see 18.4.12(2)(b) Issuing conditions for SQLWarning objects. Note that the value of this property is not case sensitive.
Specifies whether objects of the ResultSet class are to be validated or invalidated after HiRDB executes commit processing.
If this specification is omitted, the value specified by HIRDB_CURSOR in the URL becomes valid. If a value other than TRUE or FALSE is specified, the JDBC driver throws an SQLException.
If an invalidated ResultSet object executes an operation other than calling the close method, the JDBC driver throws an SQLException.
Specifies the method of accessing a JDBC SQL-type LONGVARBINARY (BLOB and BINARY types, which are HiRDB data types) database.
If this specification is omitted, REAL is assumed.
If any other value is specified, the JDBC driver throws an SQLException.
Table 18-6 Differences in how the HiRDB driver gets BLOB and BINARY data (HiRDB data types)
Execution method | LONGVARBINARY_ACCESS specification value# | ||
---|---|---|---|
REAL | LOCATOR | ||
CallableStatment.execute ResultSet.next |
Acquires all the BLOB or BINARY data from the connected database. | Acquires the locator that indicates the BLOB or BINARY data in the connected database, instead of the actual BLOB or BINARY data. | |
CallableStatement.getBytes CallableStatement.getString CallableStatement.getObject ResultSet.getBytes ResultSet.getString ResultSet.getObject |
Uses the BLOB or BINARY data obtained by ResultSet.next. | Acquires from the connected database all BLOB or BINARY data in segments of ACCESSSIZE x 1024 bytes. | |
Blob.getBytes | Extracts the range of data specified by the argument from the BLOB or BINARY data obtained by ResultSet.next. | Acquires from the connected database the range of BLOB or BINARY data specified by the argument in segments of ACCESSSIZE x 1024 bytes. | |
CallableStatement.getBinaryStream ResultSet.getBinaryStream ResultSet.getAsciiStream ResultSet.getUnicodeStream Blob.getBinaryStream |
When the InputStream read method obtained by the executed method is executed, the JDBC driver extracts data from the BLOB or BINARY data obtained by ResultSet.next. | When the InputStream read method obtained by the executed method is executed, the JDBC driver acquires data from the connected database. | |
Blob.length | Acquires the data length from the BLOB or BINARY data obtained by ResultSet.next. | Acquires the data length from the connected database. | |
Blob.position | Acquires the position of the data matching the search pattern from the BLOB or BINARY data obtained by ResultSet.next. | Acquires the position of the data matching the search pattern from the connected database. | |
InputStream obtained by CallableStatement.getBinaryStream, ResultSet.getBinaryStream, or Blob.getBinaryStream | InputStream.available | Returns a value equal to or less than the length of the actual data indicated by the locator. | Returns a value equal to or less than ACCESSSIZE x 1024 bytes. |
InputStream.skip | Skips reading data up to the range equal to or less than the length of the actual data indicated by the locator. | Skips reading data up to the maximum range of ACCESSSIZE x 1024 bytes. | |
CallableStatement.getCharcterStream ResultSet.getCharcterStream |
When the Reader read method obtained by getCharcterStream is executed, the JDBC driver extracts data from the BLOB or BINARY data obtained by ResultSet.next. | When the Reader read method obtained by getCharcterStream is executed, the JDBC driver acquires data from the connected database. |
~<unsigned integer>((1-30000))<<300>>
Specifies the maximum number of input ? parameters in the SQL statements to be executed.
This specification becomes the number of input ? parameters that are obtained during SQL preprocessing. If the actual number of input ? parameters is greater than the specification value of this property, the JDBC driver gets the input ? parameter information from the HiRDB server after SQL preprocessing.
If the specification value is invalid, the JDBC driver throws an SQLException.
~<unsigned integer>((1-30000))<<300>>
This specification becomes the number of output items obtained during SQL preprocessing. If the actual number of output items is greater than the specification value of this property, the JDBC driver gets output item information from the HiRDB server after SQL preprocessing.
If the specification value is invalid, the JDBC driver throws an SQLException.
Specifies the retention level for warning information that is issued during execution of SQL statements. For details about the retention levels for warning information, see 18.4.12(2)(b) Issuing conditions for SQLWarning objects.
If this specification is omitted, SQLWARN is assumed.
If the specification value is invalid, the JDBC driver throws an SQLException.
Specifies HiRDB client environment definitions in the following format:
variable-name=value;variable-name=value;...;variable-name=value |
For details about client environment definitions supported by the JDBC driver, see 18.10 Supported client environment definitions. If a client environment definition that is not supported by the JDBC driver is specified in a variable name, the JDBC driver ignores the specification. Note that variable names are case sensitive.
For details about the priorities for connection information that can be specified in multiple ways, see 18.11 Connection information priorities.
java.util.Properties prop; prop=new java.util.Properties(); prop.setProperty("HiRDB_for_Java_ENV_VARIABLES", "PDFESHOST=FES1;PDCWAITTIME=0");
Specifies whether Statement objects are to be validated or invalidated after HiRDB executes commit processing.
If this specification is omitted, the value specified for STATEMENT_COMMIT_BEHAVIOR in the URL becomes effective.
~<unsigned integer>((0-2097151))<<0>> (kilobytes)
Specifies the length of JDBC SQL-type LONGVARBINARY data to be requested at one time to the HiRDB server. If LONGVARBINARY_ACCESS specifies data other than LOCATOR data, this specification is invalid.
For example, suppose that 20 is specified for this property and the getBytes method of ResultSet attempts to get 100 kilobytes of JDBC SQL-type LONGVARBINARY data stored in the database. In such a case, the JDBC driver gets and returns the data by dividing the operation into five executions of 20 kilobytes each. If 0 is specified, the JDBC driver requests the data all at once.
If the specification value is invalid, the JDBC driver throws an SQLException.
~<unsigned integer>((0-2147483647)) (bytes)
Specifies the maximum data size during acquisition of JDBC SQL-type LONGVARBINARY data.
When the JDBC driver is getting JDBC SQL-type LONGVARBINARY data, it allocates memory of the defined length because it cannot determine the actual data length until it actually gets the data. Therefore, to get the value of a string for which the specified size is large (for example, 2,147,483,647 bytes, which is the maximum length for HiRDB's BINARY and BLOB data types), the JDBC driver attempts to allocate 2,147,483,647 bytes of memory, because that is the defined length. Consequently, a memory shortage may occur, depending on the execution environment.
You should specify for this property the maximum length of the data that is actually stored. If the data length of the BINARY or BLOB data to be acquired is larger than the size specified by this property, the JDBC driver truncates the acquired data to the specified size. When the JDBC driver does truncate data, it receives a warning from the HiRDB server when it executes the next method of ResultSet. In response to the received warning, the JDBC driver throws an SQLException or generates (or ignores) an SQLWarning, as determined by the specification of setLONGVARBINARY_TruncError.
If no upper limit is set by this property, the defined length of the target acquisition data becomes the upper limit.
If the specification value is invalid, the JDBC driver throws an SQLException.
Specifies whether an exception is or is not to be thrown if truncation occurs during acquisition of JDBC SQL-type LONGVARBINARY data.
If this specification is omitted, TRUE is assumed.
If IGNORE is specified for HiRDB_for_Java_SQLWARNING_LEVEL, the JDBC driver operates as if FALSE were specified for this property.
Any truncation that occurs during acquisition of JDBC SQL-type LONGVARBINARY data indicates that the following condition is satisfied:
Actual length of JDBC SQL-type LONGVARBINARY data obtained during SQL execution > data length specified by HiRDB_for_Java_MAXBINARYSIZE |
Specifies whether preprocessing results are to be ignored during execution of the close method of Statement (Statement, PreparedStatement, and CallableStatement classes) when the Statement or ResultSet object is specified to remain valid after commit processing.#1
This specification can be made by using the HiRDB_for_Java_STATEMENT_CLOSE_BEHAVIOR system property.
If the server is XDM/RD E2, this specification is ignored.
If the specified value is invalid, the JDBC driver throws an SQLException.
The value of this property is not case sensitive.
If this specification is omitted, the value of the STATEMENT_CLOSE_BEHAVIOR item in the URL takes effect. If this item is omitted in the URL, FALSE is assumed as the value of the property.
If NO is set in both the PDDDLDEAPRP and the PDDDLDEAPRPEXE client environment definitions and another user executes a definition SQL statement for a schema resource (table or index) to be accessed by an SQL statement (SELECT, INSERT, DELETE, UPDATE, PURGE TABLE, or CALL statement), the definition SQL statement is placed on lock-release wait status. This lock-release wait status is released at the times described below. Note that if you specify TRUE, you can release this status during commit processing.
If TRUE is specified and the Statement or ResultSet object is specified to remain valid after commit processing, HiRDB creates a transaction and executes DEALLOCATE PREPARE processing when the Statement is closed. Therefore, if the PDSWAITTIME client environment variable is specified, the interval monitoring specified in PDSWAITTIME begins. If automatic commit is disabled and neither an SQL execution, nor commit, nor disconnection is performed by another statement for an extended period after the Statement was closed, HiRDB closes the connection based on the interval monitoring.
If Cosminexus is connected and the connection pooling function is used by using the Type4 JDBC driver from DB Connector, you must specify FALSE. When the connection pooling function is used, connection returns to the pool and the transaction remains even if a close method for connection is called from the application. Therefore, you must execute commit processing after Statement is closed.
If you use the statement pooling facility, you must either omit this specification or specify FALSE.
Specifies the port number of HiRDB (information corresponding to PDNAMEPORT) or the HiRDB client's environment variable group file name. For details about the specification, see the explanation about DBID in 18.2.2(1)(b) Explanation of URL items.
Specifies the host name of HiRDB. For details about the specification, see the explanation about DBHOST in 18.2.2(1)(b) Explanation of URL items.
Specifies the absolute path of the directory that contains the HiRDB.INI file. This property is applicable when the HiRDB client environment variables specified in the HiRDB.INI file are to be in effect, in which case the HiRDB client environment variables in the HiRDB.ini file located in the specified directory will take effect. If the specified directory does not contain a HiRDB.ini file and this is an interval driver, this specification is ignored.
If this specification is omitted, the value specified for the HiRDB_INI item in the URL is assumed. If the HiRDB_INI item is omitted in the URL, the contents of this file are ignored.
Specifies whether an update count that is compliant with the JDBC standard is to be set for the return value of the getUpdateCounts method of java.sql.BatchUpdateException.
This property is applicable when the version of the connection-target HiRDB is 08-02 or later.
The value of this property is not case sensitive.
If this specification is omitted, the BATCHEXCEPTION_BEHAVIOR value in the URL items takes effect. If this specification is omitted in the URL, the JDBC driver assumes that TRUE is specified.
All Rights Reserved. Copyright (C) 2011, Hitachi, Ltd.