Rational Application Developer
&
WebSphere Developer for zSeries
Version 6.0.1.1
Accessing DB2 for z/OS Setup
Instructions
Author: Mark Evans.
Rational – EGL Development
IBM Software Group
Page 1 of 27
Connecting to DB2 for z/OS using the DB2 Universal Driver JDBC
driver
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:
Location
Domain/hostname
TCPPORT
NRARDSN7
carmvs1.pok.ibm.com
3504
Page 2 of 27
Overview:
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 27
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
o
o
o
o
o
o
o
Connection URL:
jdbc:db2://hostname:tcpport/location
Database:
Location Name
User ID:
Valid Logon ID for z/OS system (in upper case)
Password:
Valid password for Userid (in Upper Case)
Database Vendor: DB2 Universal Database for your DB2 on z/OS level
JDBC Driver:
IBM DB2 Universal Driver
JDBC Driver Class: com.ibm.db2.jcc.DB2Driver
Class Location (use browse button if necessary):
D:\sqllib\java\db2jcc.jar;D:\sqllib\java\db2jcc_license_cisuz.jar
where:



o
d:\sqllib\java 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.
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 27
Screen shot with Final Setting for the EGL->SQL Database Connections
Page 5 of 27
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 27

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 27
Page 8 of 27

Select Next> to continue to the following screen

Here we
o
o
o
Expand DB2 Universal Database and select for z/OS and OS/390 V7 (or V8 depending
on your host system)
For the JDBC driver, choose IBM DB2 Universal. from the pull down
Enter the following to be able to connect the DB2 Database on your host system:
Our Example Settings
Database (location)
Host (domain)
Port Number (tcpport)
Class location:
NRARDSN7
carmvs1.pok.ibm.com
3504
d:\sqllib\java\db2jcc.jar;d:\sqllib\java\db2jcc_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
o
User ID (host user id):
MEVANS
Password: (host password) ********
NOTE the connection URL format: jdbc:db2://<host:port/DBNAME> is built for you as
you enter values.
Page 9 of 27

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 27

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
o
Select the Meet all conditions radio button.
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
above.
Page 11 of 27

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 27

Click on the Finish button. Respond no when asked if you want to copy the contents to a Project
folder.

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
Perspective.

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
connection.
Page 13 of 27
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>\WebContent\WEB-INF\web.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 14 of 27
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
menu).

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 15 of 27

The Admin Console view will open up. Maximize it by double-clicking on the tab where the words
“Admin Console” are written.
Page 16 of 27

Enter any User ID (arbitrary within your test WAS) and press Log In. The following screen will
appear:
Page 17 of 27

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 18 of 27
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
User ID
Password
Arbitrary name (e.g. HostMEVANS)
Host Logon User ID (in upper case)
Host Logon Password (in upper case)
Page 19 of 27

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 20 of 27

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 21 of 27
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 22 of 27

The following screen shot appears when the DB2 Universal JDBC Driver Provider Link is
selected.
Page 23 of 27

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
appears.
Change fields in the upper half as follows:
Name (Arbitrary, but meaningful)
JNDI name (name in web.xml reference)
NRARDSN7
jdbc/NRARDSN7  note…case must match
Page 24 of 27

Scroll down to the bottom of the page
Set the following:
Component Managed authentication alias
Alias created in previous security step
e.g. mevansT40Node01/HostMEVANS
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
top)

The new data source should appear in the list.
Page 25 of 27

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 26 of 27

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:\sqlllib\java.

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
Admin Console.

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 27 of 27