The Driver class provides the following functions:

• Database connection
• Validity checking on a specified URL
• Acquisition of the connection properties specified with the DriverManager.getConnection method
• Acquisition of driver version information

For details about and usage of each method provided with the Driver class, see the applicable JDBC manual. This section explains the database connection procedure and the URL syntax unique to this JDBC driver.

To execute DB connection using the DriverManager class provided by the Java execution environment:

1. Register the Driver class in the Java Virtual Machine.
2. Call the DriverManager.getConnection method using the connection information as the argument.

(a) Registering in Java Virtual Machine with the Driver class

Register the Driver class in the Java Virtual Machine by using the Class.forName method or by registering in the system properties. The package name and Driver class name of the JDBC driver specified for registration are as follows:

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

Driver class name: PrdbDriver

• Using the Class.forName method
  Call the Class.forName method from within the application as follows:
  

  Class.forName("JP.co.Hitachi.soft.HiRDB.JDBC.PrdbDriver");

• Registering in the system properties
  Call the System.setProperty method from within the application as follows:
  

  System.setProperty("jdbc.drivers","JP.co.Hitachi.soft.HiRDB.JDBC.PrdbDriver");

(b) Defining the connection information and establishing a database connection

To connect to the database, use one of the following methods:

• Using the DriverManager.getConnection method
  

  Connection con = DriverManager.getConnection(String url, String user, String password) ; or Connection con = DriverManager.getConnection(String url, Properties info) ;

• Specification with an internal driver
  When an internal driver is used, the information called by the routine at the HiRDB side is assumed as the connection information (such as the authorization identifier). However, when a trace is acquired within the JDBC driver, INNER is assumed as the authorization identifier.
  

  Specification for internal driver only: Connection con = DriverManager.getConnection(String url) ;

• Directly calling the connect method in the Driver class
  

  Driver drv = new JP.co.Hitachi.soft.HiRDB.JDBC.PrdbDriver(); Connection con = drv.connect(String url, Properties info) ;

In the arguments of the previous methods, specify the information required for database connection.

If a database connection is successful, the JDBC driver returns a Connection object as a result of the method call. If required information is not specified in each argument, or invalid information is specified, the JDBC driver throws an SQLException as a result of the method call.

Table 16-2 lists the arguments of the getConnection method, and Table 16-3 lists the information to be specified for Properties info.

Table 16-2 Arguments of the getConnection method

Argument	Description	Specification
String url	URL; For URL, see (3) URL syntax.	R
String user	Authorization identifier1	R2
String password	Password	O
Properties info	See Table 16-3.

Legend:

R: Required.

O: Optional.

: Not applicable.

¹ If null or space characters are specified for the authorization identifier, this method throws an SQLException. The method also throws an SQLException if the driver-converted character codes and, as a result, the size of the character string specified for the authorization identifier exceed 30 bytes. For details about character code conversion, see 16.12.2 Character code conversion facility.

² The argument can be omitted, if specified with the internal driver.

Table 16-3 Information to be specified for Properties info

Key	Description	Specification
user	Authorization identifier1	R2
password	Password	O
ENCODELANG	In a Java program, Unicode is used for the character codes. Therefore, during character data processing with HiRDB, the JDBC driver performs mutual character code conversion between HiRDB's character data and Unicodes. For this character code conversion processing, the JDBC driver uses the encoder and decoder provided by the Java Virtual Machine. You must specify the character set names specified by the JDBC driver for the provided encoder and decoder. The settings can be for any character set (such as MS932) supported by Java. For details about this operation if you specify OFF or have not specified anything in Properties info (including the settings using the DataSource.setEncodeLang method and ENCODELANG of the URL), see 16.11.5 setEncodeLang.	O
COMMIT_BEHAVIOR	When HiRDB commits, this key specifies whether or not the following classes are to remain valid after commit has executed: ResultSet class Statement class, PreparedStatement class, and CallableStatement class For details about the specification values, see 16.11.19 setCommit_Behavior. Note: See Notes on COMMIT_BEHAVIOR following this table.	O
BLOCK_UPDATE	Specifies whether or not multiple parameters are to be processed at one time when the ? parameter is used to update databases. When this information is omitted, FALSE is assumed. TRUE: Processes multiple parameters at one time. FALSE: Processes parameter sets individually. Other: Assumes that FALSE is specified. Notes: When TRUE is set, the batch update function supports HiRDB facilities using arrays. Only INSERT, UPDATE, and DELETE SQL statements can use facilities using arrays. All other SQL statements are processed sequentially, not in batch mode. Even the SQL statements that can use facilities using arrays are processed sequentially, not in batch mode, if they do not satisfy the conditions for facilities using arrays. To use facilities using arrays, see 16.3.2 Batch updating. For details about the facilities using arrays, see 4.8 Facilities using arrays. This function can also be specified using the HiRDB_for_Java_BLOCK_UPDATE system property. However, when BLOCK_UPDATE is set, the HiRDB_for_Java_BLOCK_UPDATE system property setting is ignored.	O
LONGVARBINARY_ACCESS	Specifies the access method for a LONGVARBINARY database (column attribute is BLOB or BINARY). When this key is omitted, REAL is assumed. REAL: Accesses real data from HiRDB. LOCATOR: Uses the HiRDB locator. Other: Assumes that REAL is specified.	O
HiRDB_for_Java_SQL_IN_NUM	Specifies the maximum number of input or input/output ? parameters in the SQL statements to be executed. This is the number of input or input/output ? parameter information items that is acquired during SQL preprocessing. If the actual number of input or input/output ? parameters is greater than this property value, the input or input/output ? parameter information is acquired after the SQL preprocessing. The permitted value range is from 1 to 30,000 (default is 64). Specifying any other value or non-numeric value results in an error. Notes: This item can also be specified using the HiRDB_for_Java_SQL_IN_NUM system property. However, when HiRDB_for_Java_SQL_IN_NUM is specified for Properties info, the system property setting is ignored. If you do not execute any SQL statement that uses input or input/output ? parameters, we recommend that you specify a value of 1. This property value is applicable only when the version of the connected HiRDB server is 07-02 or later.	O
HiRDB_for_Java_SQL_OUT_NUM	Specifies the maximum number of output items for the SQL statement to be executed. This is the number of output items that is acquired during SQL preprocessing. If the actual number of output items is greater than this property value, the output items are acquired after the SQL preprocessing. The permitted value range is from 1 to 30,000 (default is 64). Specifying any other value or non-numeric value results in an error. Note: This item can also be specified using the HiRDB_for_Java_SQL_OUT_NUM system property. However, when HiRDB_for_Java_SQL_OUT_NUM is specified for Properties info, the system property setting is ignored. If you do not execute any SQL statement that contains a search item or output or input/output ? parameter, we recommend that you specify a value of 1. This property value is applicable only when the version of the connected HiRDB server is 07-02 or later.	O
HiRDB_for_Java_SQLWARNING_LEVEL	Specifies the retention level of warning information that has been issued during execution of the SQL statement. The permitted warning retention levels are as follows: IGNORE SQLWARN (default) ALLWARN In this method, information specified in the arguments is not case sensitive. For details about the above values, see 16.2.9 SQLWarning class.	O
HiRDB_for_Java_CLEAR_ENV	Specifies whether or not the HiRDB client environment definition set as OS environment variables is to be ignored during database connection. TRUE: Ignores the HiRDB client environment definition registered as OS environment variables when the database is connected for the first time after the process has started. When TRUE is specified, you can apply the value of the HiRDB client environment definition that has been set by a method other than the OS environment variables (such as environment variable groups). FALSE (default): Does not ignore the HiRDB client environment definition registered as OS environment variables. Notes: In this method, information specified in the arguments is not case sensitive. Once the database is connected, the HiRDB client environment definition set as OS environment variables is not ignored even if an attempt is made to specify TRUE within a native method installed by a method such as C language. Once the database is connected with TRUE specified, the client environment definition value remains ignored even if FALSE is specified the next time the database is connected.	O

Legend:

R: Required.

O: Optional.

¹ If null or space characters are specified for the authorization identifier, this method throws an SQLException. This method also throws an SQLException if the driver-converted character codes and, as a result, the size of the character string specified for the authorization identifier exceed 30 bytes. For details about character code conversion, see 16.12.2 Character code conversion facility.

² The key can be omitted, if specified with the internal driver.

Notes on COMMIT_BEHAVIOR

• If another user specifies CLOSE or PRESERVE to execute a definition SQL on a resource (such as a table or index) that is being accessed by SELECT, INSERT, DELETE, UPDATE, PURGE TABLE, or CALL, and PDDDLDEAPRP in the client environment definition is set to NO, the definition SQL goes into lock-release wait status until the connection to the resource is disconnected.
  If PDDDLDEAPRP in the client environment definition is set to YES, the preprocessing result becomes invalid. If an SQL for which the preprocessing result has been invalidated in this manner is executed, an SQLException exception occurs (the value acquired by the getErrorCode method is -1542).
  
• When PRESERVE is specified, the JDBC driver uses HiRDB's holdable cursor.
• By specifying¹ CLOSE or PRESERVE, the only precompiled SQL statements that are valid after commit² are SELECT, INSERT, DELETE, UPDATE, PURGE TABLE, and CALL (SQL statements can be precompiled by executing the Connection.prepareStatement method or the Connection.prepareCall method).
  Other precompiled SQL statements become invalid during commit even though you specify CLOSE or PRESERVE for COMMIT_BEHAVIOR.
  When SQL statements that include these invalid SQL statements are executed with the PreparedStatement class object or CallableStatement object, an error occurs. An example of such an error is shown below:
  Example
  

  PreparedStatement pstmt1 = con.prepareStatement("lock table tb1"); PreparedStatement pstmt2 = con.prepareStatement("lock table tb2"); pstmt1.execute(); //No error occurs. con.commit(); pstmt2.execute(); //An error occurs. pstmt1.close(); pstmt2.close();

Explanation

Because the SQL statement to be executed is a LOCK statement, even though COMMIT_BEHAVIOR specifies CLOSE, PreparedStatement becomes invalid after commit and an error occurs.

¹ Refers to specification of one of the following:

COMMIT_BEHAVIOR=CLOSE specified for the URL specified by the getConnection method.

COMMIT_BEHAVIOR=PRESERVE specified for the URL specified by the getConnection method.

setCommit_Behavior method of the JdbhDataSource, JdbhConnectionPoolDataSource, or JdbhXADataSource class used to specify CLOSE.

setCommit_Behavior method of the JdbhDataSource, JdbhConnectionPoolDataSource, or JdbhXADataSource class used to specify PRESERVE.

² Means one of the following:

Explicit commit using the commit method

Implicit commit by automatic commit

Execution of a definition SQL statement

Execution of a PURGE TABLE statement

Explicit rollback by rollback method

Implicit rollback by an SQL execution error

This section explains the URL syntax supported by the JDBC driver. Do not place any space inside each item or between items in a URL. To specify both an additional connection information item and a database host name item, separate them by a comma (,).

(a) URL syntax

  jdbc:hitachi:PrdbDrive[://[DBID=additional-connection-information]
                        [[{://|,}]DBHOST=database-host-name]
                        [[{://|,}]ENCODELANG=conversion-character-set]
                        [[{://|,}]COMMIT_BEHAVIOR=cursor-operation-mode]
                        [[{://|,}]CLEAR_ENV=environment-variable-invalidation-setting]]

(b) URL items

jdbc:hitachi:PrdbDrive

This is the protocol name and the subprotocol name. This item is required.

additional-connection-information

Specify HiRDB's port number (this corresponds to PDNAMEPORT in the client definitions). Alternatively, specify a HiRDB environment variable group.

If this item is omitted, the default value for PDNAMEPORT is assumed.

Notes about specifying a HiRDB environment variable group in additional connection information

• When you specify the name of a HiRDB environment variable group, place @ at the beginning of the group name.
• If the environment variable name contains single-byte spaces or single-byte @ characters, enclose the name in single-byte quotation marks ("). When an environment variable group name is enclosed in single-byte quotation marks, all characters following the last single-byte quotation mark up to the next item or all characters through the end of the character string are ignored. An environment variable group name containing single-byte quotation marks or single-byte commas cannot be specified.
• The environment variables registered in an environment variable group have precedence over the user environment variables and the environment variables registered by HiRDB.INI.
• The following priority applies to the specification of additional connection information and database host name:
  1. HiRDB environment variable group specified in the additional connection information
  2. Database host name or the port number specified in the additional connection information
  For example, if a HiRDB environment variable group name has been specified in DBID, information about the HiRDB environment variable group takes effect. A database host name does not take effect even if it is specified in DBHOST in the URL. In this case, if PDHOST is omitted in the HiRDB environment variable group, a connection error results.
  

database-host-name

Specify HiRDB's host name. This corresponds to PDHOST in the client definitions.

If this item is omitted, the default value for PDHOST is assumed.

conversion-character-set

Specify the conversion character set to be used for character type conversion.

cursor-operation-mode

Specify whether the cursor is valid following COMMIT.

environment-variable-invalidation-setting

Specifies whether or not the HiRDB client environment definition set as OS environment variables is to be ignored during database connection. For details about the specification value and notes, see HiRDB_for_Java_CLEAR_ENV in Table 16-3.

(c) Example of specifying a HiRDB environment variable group name in additional connection information

• In UNIX

In this example, the path of the HiRDB environment variable group name is /HiRDB_P/Client/HiRDB.ini:

 
String url = "jdbc:hitachi:PrdbDrive://DBID=@HIRDBENVGRP=/HiRDB_P/Client/HiRDB.ini";
 

• In Windows

1. In this example, the environment variable group name registered using the tool for registering HiRDB client environment variables is HiRDB_ENV_GROUP:
   

   String url = "jdbc:hitachi:PrdbDrive://DBID=@HIRDBENVGRP=HiRDB_ENV_GROUP";

2. In this example, the path of the HiRDB environment variable group name is C:\HiRDB_P\Client\HiRDB.ini:
   

   String url = "jdbc:hitachi:PrdbDrive://DBID=@HIRDBENVGRP=C:\\HiRDB_P\\Client\\HiRDB.ini";

3. In this example, the path of the HiRDB environment variable group name is C:\ProgramFiles\HITACHI\HiRDB\HiRDB.ini (: single-byte space character):
   

   String url = "jdbc:hitachi:PrdbDrive://DBID=@HIRDBENVGRP=" + "\"C:\ProgramFiles\\HITACHI\\HiRDB\\HiRDB.ini\"";