Rational Application Developer
WebSphere Developer for zSeries
Accessing DB2 for z/OS Setup
Author: Mark Evans.
Rational – EGL Development
IBM Software Group
Page 1 of 28
Connecting to DB2 for z/OS using the DB2 Universal Driver JDBC
Note: prior to starting to setup, you will need:
1. A valid DB2 Connect license as this is the product that allows JDBC access between a client
machine (e.g. Windows and DB2 on z/OS) and the host server machine.
To have a valid license, you need to either:
a. Have DB2 Connect (any version) installed on your machine (no configuration is required)
b. Have DB2 UDB installed and have access to a licensed copy of the
db2jcc_license_cisuz.jar file and it is in a folder accessible to your machine
c. Have access to DB2 Connect on a Gateway Server
The rest of these setup instructions assume you have either used option a.) or b.) and the
resulting db2jcc_license_cisuz.jar is contained in the <DB2installdir>java folder.
2. DB2 for z/OS configured to accept TCP/IP requests from a client.
This would done using the Distributed Data Facility
3. Connection information for the DB2 on z/OS database.
You will need the following information in order to configure your connection to DB2 for z/OS.
a. DB2 on z/OS Location Name (NRARDSN7 below)
b. TCP/IP Domain name that the DB2 system (or hostname) runs on
c. TCP/IP port (TCPPORT below) that DB2 on z/OS listens on for incoming requests
NOTE: This information is written to the z/OS system console when the Distributed Data
Facility (DDF) of DB2 for z/OS is started (see next screen shot). Your DB2 on z/OS DBA
should be able to provide this information.
For this document, the following values are used for the DB2 on z/OS system:
Page 2 of 28
When using EGL to access a DB2 on z/OS database there are 3 places that you might need to specify a
connection to your DB2 for z/OS database depending on what functionality you are using to access the
database – which includes:
1. Using the EGL SQL Retrieve functionality to create record definitions.
2. Using the EGL Data Parts or EGL Data and Pages Wizard
3. Accessing the database from a Web Application running with the WebSphere Application Server
V6 installed with Rational Application Developer V6.
Each will be explained in the following pages:
Page 3 of 28
1. Using the EGL SQL Retrieve functionality
EGL SQL Retrieve contains functionality that allows a developer to retrieve the database definitions from
the DB2 database catalog.
Database connection information needs to be specified to enable the retrieve functionality. This is done
using the EGL preferences named SQL Database Connections. Please see the following steps to
configure this preference.
Open up the Preferences dialog under the Window Menu option
Expand the EGL category in the preferences dialog and choose the SQL Database
Connections subcategory and change the following fields to specify the details for the host
system (see following screen shot for final values).
o Connection URL: jdbc:db2://hostname:tcpport/location
o Database: Location Name
o User ID: Valid Logon ID for z/OS system (in upper case)
o Password: Valid password for Userid (in Upper Case)
o Database Vendor: DB2 Universal Database for your DB2 on z/OS level
o JDBC Driver: IBM DB2 Universal Driver
o JDBC Driver Class: com.ibm.db2.jcc.DB2Driver
o Class Location (use browse button if necessary):
d:sqllibjava would be either your DB2 install directory or the directory
where the required jar files are copied.
db2jcc.jar contains the base DB2 functionality to access any database
db2jcc_license_cisuz.jar contains the DB2 connect license to enable
access to a z/OS DB2 database.
o Secondary Authentication ID: Specifies an alternate schema name if using unqualified
table names (no schema) in the EGL SQL Record definitions (not used in our scenario)
Page 4 of 28
Screen shot with Final Setting for the EGL->SQL Database Connections
Page 5 of 28
2. Connections for – and using the EGL Data Parts or EGL Data Parts
and Pages Wizard
EGL provides a wizard to allow you to build EGL Data parts (Records and data items) and additionally
web pages based on the DB2 Table Definitions. The starting point for this wizard is to identify a
database to connect to in order to retrieve the list of available tables. The details of the database
connection can be specified as one of the first steps of the wizard or a connection definition can be setup
independently and then referred to in the data parts wizard. This document will show how to setup the
connection definition independently and then how to refer to it in the wizard.
Open the Data Perspective by selecting Window->Open Perspective->Data
The Data Perspective will appear as follows:
Page 6 of 28
Select anywhere in the Database Explorer View (lower left hand corner), right-mouse click,
select New Connection. You will see the following:
Select the Choose a database manager and JDBC driver radio button, and give the connection
a descriptive name. (as shown below)
Page 7 of 28
Select Next> to continue to the following screen
o Expand DB2 Universal Database and select for z/OS and OS/390 V7 (or V8 depending
on your host system)
o For the JDBC driver, choose IBM DB2 Universal. from the pull down
o Enter the following to be able to connect the DB2 Database on your host system:
Our Example Settings
Database (location) NRARDSN7
Host (domain) carmvs1.pok.ibm.com
Port Number (tcpport) 3504
Class location: d:sqllibjavadb2jcc.jar;d:sqllibjavadb2jcc_license_cisuz.jar
NOTE: Your default class location may be different, but correct. You can use the browse
button to navigate to confirm the file location or find them if they are somewhere else )
o User ID (host user id): MEVANS
o Password: (host password) ********
NOTE the connection URL format: jdbc:db2://<host:port/DBNAME> is built for you as
you enter values.
Page 9 of 28
You can Test the Connection by clicking on the Test Connection button:
Select OK to clear the confirmation screen and then click on the Next > button.
Page 10 of 28
A dialog is presented to allow you to specify which schemas to use when the information is
retrieved. This dialog will be modified as noted below and the resulting screen capture is below:
Because we don’t want to import every table in the our database (e.g. NRARDSN7) database we
would want to filter everything out except the schema we will use on our project. To do this:
o Select the Meet all conditions radio button.
o Click on the Add button and in the Filter entry field, enter the schema we would like to
use (e.g DRBRUCE in this case)
o Click on the OK button to continue.
o When done the screen will look like the New Database Connection screen capture
Page 11 of 28
Continue on by selecting the Next > button.
Unless you need to specify a different package owner or Build owner, then use the defaults
Continue on by selecting the Next > button. You will see the following confirmation screen:
Page 12 of 28
Click on the Finish button. Respond no when asked if you want to copy the contents to a Project
Once connected you would see the following in the Database Explorer View. This represents
the list of tables qualified with the defined schema
You are now connected to DB2 on the Host via the DB2 Universal DB2 Driver in the data
If using the EGL Data Parts wizard, you can choose this named Connection as shown below:
NOTE: If you want to change any details related to the connection such as changing your user
id, changing your password, or changing the schema filter, then you can edit the connection by
selecting the connection in the Database Explorer View, right-mouse click, and select edit
Page 14 of 28
3. Connections for Accessing DB2 for z/OS from WAS V6
With EGL you can write web applications whose database logic can be generated in Java code running in
the WebSphere Application Server. This Java code can access DB2 on z/OS databases. For test
purposes, by default a copy of the WebSphere Application Server V6 is installed with either Rational
Application Developer or WebSphere Developer for z/Series. This copy of the server is used to test
your EGL program.
When you test an EGL web application, the EGL program connects through something called a JNDI
name. This is a symbolic name that refers to a data source connection which in turn maps to the real
database. This mapping and the details of the database connection are specified within the WebSphere
Application Server and are used when the application requests a connection to the JNDI name.
In our scenario, we are going to use the JNDI name, jdbc/NRARDSN7 in our setup info to connect to the
NRARDSN7 database on the z/OS host.
The JNDI name needs to be named in the EGL build descriptor used for generation or debug and also
listed as a reference in the Web Archive deployment descriptor (the file web.xml). If you specified the
JNDI name when you created the web project, then the reference will be created for you. If you did not,
then you will need to add the reference to your web deployment descriptor (found in <webprojectname>
WebContentWEB-INFweb.xml on the references tab). Below is a screen capture of an already specified
reference using the JNDI name. If you don’t have this, then click the Add button and fill in the rest of the
entry fields as shown.
Page 15 of 28
After confirming/setting up the reference, the next step is to define the database (using a datasource) and
the mapping to the JNDI name to the WebSphere application Server. To do this:
Make sure you are in a Web Perspective
Start the WebSphere Application Server as it has to be started to use the WAS Administrative
Console which is needed for this setup. The can be done by either:
o Choosing the JSP and with the right-mouse click, select Run->run on server. If it is not
started, it will start the server for you.
o Switch to the servers view and selecting the server and choosing Start (from the context
Once the server is started, choose to Run the Administration Console by selecting the server in
the Servers view and then right-mouse click, Run administrative console
Page 16 of 28
The Admin Console view will open up. Maximize it by double-clicking on the tab where the words
“Admin Console” are written.
Page 17 of 28
Enter any User ID (arbitrary within your test WAS) and press Log In. The following screen will
Page 18 of 28
First, you need to define a userid and password to use in the connection to the DB2 on z/OS
system. This is done using the Security section of the Admin Console. So, expand Security
and select Global Security. The following screen should appear:
Expand the JAAS Configuration on the right hand side, and select J2C Authentication Data.
The following screen will appear
Page 19 of 28
You may or may not already have entries depending on what other web application testing you
have already been doing.
Click the New button to add a new entry for the host User id and Password. The following screen
appears and should be filled in as described following the screen shot.
Alias Arbitrary name (e.g. HostMEVANS)
User ID Host Logon User ID (in upper case)
Password Host Logon Password (in upper case)
Page 20 of 28
Click the Apply button and then choose save (the link) in the Messages box (see below)
Click the Save button to confirm saving the information
Page 21 of 28
Expand the Resource category and choose JDBC providers. The following screen will appear:
If there is already a DB2 Universal JDBC Driver Provider in the list of providers, select the link to
continue and skip this step.
If not, then click New to define a new JDBC provider. On the first screen to appear (below) select
the following values:
Step 1: Database Provider DB2
Step 2: Select the Provider Type DB2 Universal JDBC Driver Provider
Step 3: Select in the implementation type Connection Pool Data Source
Page 22 of 28
Click Next and on the next screen (not shown), use the defaults (values specified will be in the
screen shot for the next step).
Click Apply and save on this screen (as noted above for the user id settings). You will be
returned to the panel above with the listing of the JDBC Providers. Select the DB2 Universal
JDBC Driver Provider link.
Page 23 of 28
The following screen shot appears when the DB2 Universal JDBC Driver Provider Link is
Page 24 of 28
Select Data Sources under Additional Properties, and the following screen appears
Choose New to add the data source (database connection) information and the following screen
Change fields in the upper half as follows:
Name (Arbitrary, but meaningful) NRARDSN7
JNDI name (name in web.xml reference) jdbc/NRARDSN7 note…case must match
Page 25 of 28
Scroll down to the bottom of the page
Set the following:
Component Managed authentication alias Alias created in previous security step
Container-managed authentication alias Alias created in previous security step
Database Name (location) NRARDSN7
Driver Type 4 (default)
Server Name (domain/hostname) carmvs1.pok.ibm.com
Port Number (TCPPORT) 3504
After setting these fields, click Apply and then save (as in previous steps) (may need to scroll to
The new data source should appear in the list.
Page 26 of 28
When you defined the JDBC provider, by default, WebSphere Application Server uses a variable
named “DB2UNIVERSAL_JDBC_DRIVER_PATH” to identify the path/directory of the DB2 jar
files. Therefore, you need to set the value of this variable to the path/directory.
To do this, expand the Environment category and select WebSphere Variables. The following
screen should appear.
Page 27 of 28
If not already set (the column has a blank value), then select the
DB2UNIVERSAL_JDBC_DRIVER_PATH by clicking on it. The following dialog will appear:
Set the value field to the path/directory that contains the Db2 jar files (e.g. db2jcc.jar). In this
case, they are in my DB2 install directory, d:sqlllibjava.
Click the Apply button and save the configuration as before.
Logout of the Admin Console, by clicking logout in options at top of the page and close the
In the servers view, restart the server.
Congratulations….you should be ready to use the DB2 for z/OS with your EGL web
application when running under WAS!!!
Page 28 of 28