Registering the JDBC driver

Before using JDBC to access data in a server database file, you need to register the IBM® Toolbox for Java™ JDBC driver with the DriverManager.

You can register the driver either by using a Java system property or by having the Java program register the driver:
  • Register by using a system property

    Each virtual machine has its own method of setting system properties. For example, the Java command from the JDK uses the -D option to set system properties. To set the driver using system properties, specify the following:

          "-Djdbc.drivers=com.ibm.as400.access.AS400JDBCDriver"
  • Register by using the Java program

    To load the IBM Toolbox for Java JDBC driver, add the following to the Java program before the first JDBC call:

          Class.forName("com.ibm.as400.access.AS400JDBCDriver");

    The IBM Toolbox for Java JDBC driver registers itself when it is loaded, which is the preferred way to register the driver. You can also explicitly register the IBM Toolbox for Java JDBC driver by using the following:

          java.sql.DriverManager.registerDriver (new com.ibm.as400.access.AS400JDBCDriver ());

    Calling DriverManager.registerDriver() results in the IBM Toolbox for Java JDBC driver getting registered twice. Once when AS400JDBCDriver is loaded by the JVM and once for the explicit call to the registerDriver() method. This is a result of the DriverManager implementation, which IBM Toolbox for Java has no control over. Having a driver being listed twice in the DriverManager's registry is normally not a problem. Although there may be situations where both registered driver listings get used. For example, this could happen when trying to get a connection with an incorrect password. The DriverManager will fail on the first registered driver to obtain a connection and so it will then try the second registered driver.

The IBM Toolbox for Java JDBC driver does not require an AS400 object as an input parameter like the other IBM Toolbox for Java classes that get data from a server. An AS400 object is used internally, however, to manage default user and password caching. When a connection is first made to the server, the user may be prompted for user ID and password. The user has the option to save the user ID as the default user ID and add the password to the password cache. As in the other IBM Toolbox for Java functions, if the user ID and password are supplied by the Java program, the default user is not set and the password is not cached. See Managing connections in Java programs for information about managing connections.

Using the JDBC driver to connect to a database on the server

You can use the DriverManager.getConnection() method to connect to the server database. DriverManager.getConnection() takes a uniform resource locator (URL) string as an argument. The JDBC driver manager attempts to locate a driver that can connect to the database that is represented by the URL. When using the IBM Toolbox for Java driver, use the following syntax for the URL:

      "jdbc:as400://systemName/defaultSchema;listOfProperties"
Note: Either systemName or defaultSchema can be omitted from the URL.

To use Kerberos tickets, set only the system name (and not the password) on your JDBC URL object. The user identity is retrieved through the Java Generic Security Services (JGSS) framework, so you also do not need to specify a user on your JDBC URL. You can set only one means of authentication in an AS400JDBCConnection object at a time. Setting the password clears any Kerberos ticket or profile token. For more information, see AS400 class and J2SDK, v1.4 Security Documentation Link outside information center.

Examples: Using the JDBC driver to connect to a server

Example: Using a URL in which a system name is not specified

This example results in the user being prompted to type in the name of the system to which he or she wants to connect.

    // Connect to unnamed system.
    // User receives prompt to type system name.
    Connection c = DriverManager.getConnection("jdbc:as400:");

Example: Connecting to the server database; no default SQL schema or properties specified

    // Connect to system 'mySystem'. No
    // default SQL schema or properties are specified.
    Connection c  = DriverManager.getConnection("jdbc:as400://mySystem");

Example: Connecting to the server database; default SQL schema specified

    // Connect to system 'mySys2'. The
    // default SQL schema 'myschema' is specified.
    Connection c2 = DriverManager.getConnection("jdbc:as400://mySys2/mySchema");

Example: Connecting to the server database and using java.util.Properties to specify properties

The Java program can specify a set of JDBC properties either by using the java.util.Properties interface or by specifying the properties as part of the URL. See IBM Toolbox for Java JDBC properties for a list of supported properties.

For example, to specify properties using the Properties interface, use the following code as an example:

     // Create a properties object.
     Properties p = new Properties();

     // Set the properties for the connection.
     p.put("naming", "sql");
     p.put("errors", "full");

     // Connect using the properties object.
     Connection c = DriverManager.getConnection("jdbc:as400://mySystem",p);

Example: Connecting to the server database and using a uniform resource locator (URL) to specify properties

     // Connect using properties. The
     // properties are set on the URL
     // instead of through a properties object.
     Connection c = DriverManager.getConnection(
                        "jdbc:as400://mySystem;naming=sql;errors=full");

Example: Connecting to the server database and specifying user ID and password

     // Connect using properties on the
     // URL and specifying a user ID and password
     Connection c = DriverManager.getConnection(
                        "jdbc:as400://mySystem;naming=sql;errors=full",
                        "auser",
                        "apassword");

Example: Disconnecting from the database

To disconnect from the server, use the close() method on the Connecting object. Use the following statement to close the connection created in the previous example:

     c.close();