HTTP.doc

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 machinec. 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 onc. 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 NRARDSN7Domain/hostname carmvs1.pok.ibm.com

Page 2 of 27

TCPPORT 3504

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 Connection URL: jdbc:db2://hostname:tcpport/locationo Database: Location Nameo 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 Drivero JDBC Driver Class: com.ibm.db2.jcc.DB2Driver o Class Location (use browse button if necessary):

D:\sqllib\java\db2jcc.jar;D:\sqllib\java\db2jcc_license_cisuz.jar

where: 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.

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 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 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 downo Enter the following to be able to connect the DB2 Database on your host system:

Our Example Settings

Database (location) NRARDSN7Host (domain) carmvs1.pok.ibm.comPort Number (tcpport) 3504Class location: 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 User ID (host user id): MEVANSo 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 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 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 Arbitrary name (e.g. HostMEVANS)User ID Host Logon User ID (in upper case)Password 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) NRARDSN7 JNDI name (name in web.xml reference) 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