 | Level: Intermediate Laurence England (englandl@us.ibm.com), STSM, IBM
Mel Fowler (fowlerm@us.ibm.com), Senior Software Engineer, IBM
13 Mar 2008 IBM® Rational® Developer for System z™ V7.1
provides an Eclipse-based integrated development environment (IDE) that you can use
to access applications and resources directly on z/OS. Using the Eclipse concept of
perspectives –- an arrangement of views and editors dedicated for a specific set of
activities –- you are able to use one IDE to work with a database, write a COBOL
application, build the application, and debug the application. In this article,
follow to the steps necessary to create a batch COBOL application that accesses a
DB2 for z/OS database using Rational Developer for System z.
Introduction
IBM Rational Developer for System z V7.1 (hereafter called Developer for z)
provides an Eclipse-based integrated development environment (IDE), giving access
to applications and resources directly on z/OS. This article describes how to
work with a DB2 for z/OS database, and how to build, run, and debug a batch COBOL
application that accesses the DB2 for z/OS database.
You should have some familiarity with Eclipse, Developer for z, COBOL, and DB2
for z/OS, as well as a basic understanding of SQL. A rudimentary understanding of
Job Control Language (JCL) and JCL procedures is also required.
This article assumes you have already a valid userid on the z/OS system where you
will be running your DB2/COBOL application and that you have properly configured
Developer for z to communicate with that z/OS system. Further, this article
assumes you have access to DB2 for z/OS with the appropriate authorizations to
perform the tasks described below. The examples shown in this article will use
the userid ENGLAND, and it will also be the high-level qualifier for dataset
names.
Overview of steps
- Create a connection to the DB2 for z/OS in the data perspective
- Declare the sample database schema and table
- Populate the DB2 table
- Create a z/OS project and subproject to organize your work
- Create the COPYBOOK that maps the DB2 table using DCLGEN
- Create a second subproject to organize the DB2/COBOL application code and
properties
- Create the batch COBOL application using the COPYBOOK from the previous step
- Bind the application
- Debug the DB2/COBOL application
Set up the database artifacts
This section describes how to set up the sample database table that is used in
the example. In order to set up the sample database table, you need a database
schema, if you do not already have one, along with the appropriate authorities.
You also need to create a connection to your z/OS database; from the connection,
you'll be able to create the database table and insert values into the table.
Create a connection to DB2 for z/OS in the data
perspective
You need to create a connection to your DB2 for z/OS database in the data
perspective. There are different types of connections that you can make to your
z/OS database in the data perspective. Depending on what you plan on doing, you
may choose one connection type over another. This document describes creating a
connection to your z/OS database using the Universal JDBC driver.
- Open the data perspective in Developer for z:
- Selecting Window > Open Perspective >
Other…, as shown in Figure 1:
Figure 1. Opening a perspective
- Select Data from the dialog box, as shown in Figure 2:
Figure 2. Selecting the data
perspective
- Once the data perspective is open, right-click on the Connections
folder in the Database Explorer, and select New Connection… , as shown in
Figure 3:
Figure 3. Starting to create a new
database connection
- The Connection Wizard will guide you through connecting to a DB2 for z/OS
database. Some key fields you will need to supply are:
-
Location: This is the name of the database location. You would
see this name if you were to look at the entries in the SYSIBM.LOCATIONS
table. In the example, the location name used is DSN8, which is a DB2 for
z/OS V8 database in New Function Mode (NFM). You can get the location name
from the Database Administrator (DBA).
-
Host: This is the IP address of the z/OS system to which you are
connecting. The example shows stplex4a.svl.ibm.com.
-
Port number: This is the port that is used for the JDBC
connection. You may need to get the port number for your system from the
DBA. The port assigned to DSN8 in the example is 8028.
After filling the information into the wizard, you can click on Test
Connection to see if you have access to DB2 for z/OS. Make adjustments as
necessary so that the test connection succeeds.
The New Connection window used in this example is shown in Figure 4:
Figure 4. New Connection window used in
the example
Please take note of the various options on the connection panel.
Create a database table
A schema is a named collection of database tables and artifacts and their
relationships. You may already have a schema. If you do not have a defined
schema and do not have the authority to create a schema, request your DBA create a
schema for you. If you do not have the authority to create a database table, you
will need to request your DBA to create a table for you.
To limit the number of nodes displayed in the Database Explorer tree, a filter
has been established in the example. To do so, right-click on the Schemas
node, and specify the filter, as shown in Figure 5:
Figure 5. Specifying a filter to limit
the number of database schemas displayed
Once you have a connection to a DB2 for z/OS database created and you have a
schema defined with a filter, it should look similar to Figure 6:
Figure 6. Database Explorer with a
filtered schema
In the example, my userid, ENGLAND, has been granted CREATEIN, ALTERIN, and
DROPIN authorities for the database schema ENGLAND.
Assuming you have the appropriate authorities to create a table, highlight the
Tables node in the tree, right-click, and select New >
With SQL Editor.
A new edit session with skeleton SQL in the edit session opens, and you can edit
this SQL to obtain your desired results. The SQL used to create the table is shown
in Listing 1:
Listing 1. SQL to create the table used in
the example
CREATE TABLE ENGLAND.FRIENDZ (
FNAME CHAR(10) NOT NULL,
LNAME CHAR(10) NOT NULL,
PHONE CHAR(10) NOT NULL,
EMAIL CHAR(30) NOT NULL
)
AUDIT NONE
DATA CAPTURE NONE
CCSID EBCDIC; |
To run the SQL, place the cursor in the edit session, right-click, and select
Run SQL. You will see the results in the Data Output view, as shown in
Figure 7:
Figure 7. Data Output view showing the
results of running the SQL
Insert values into the table
Inserting values into a table is very easy using the table editor within the data
perspective. To use the table editor, find the table in the Database Explorer. You
may need to refresh the Tables node to show the newly created table, as shown in
Figure 8:
Figure 8. Database Explorer with expanded
Tables node
Highlight the table FRIENDZ, right-click, and then select Data
> Edit. An edit window will open and you can type directly into
the tabular form, as shown in Figure 9:
Figure 9. Editing the table contents
You need to save the document using the two-key combination of Ctrl-S. You will
see a confirmation in the Data Output view, as shown in Figure 10:
Figure 10. Data Output view displaying
the results of the table edit
Create and build the DB2/COBOL application
This section describes the DB2/COBOL application and the steps necessary to build
it. With your database table created and the sample data inserted, you are now
ready to create and build the COBOL program that will access this data. The z/OS
projects perspective is used to create the COBOL program.
In a manner similar to opening the data perspective, open the z/OS projects
perspective -- select the Window > Open Perspective >
Other…, and then select z/OS Projects.
In the example, the system stplex4a has been defined using stplex4a.svl.ibm.com
and the connection details, as provided by the system programmer. Once defined,
connect to the z/OS system -- highlight stplex4a (or your system node),
right-click, and select Connect. Provide your userid and password for the
z/OS system.
The userid used in the example is ENGLAND. Once connected, there are four nodes
directly under the system node. These nodes are JES (Job Output), MVS Files, TSO
Commands, USS Files, and USS Shells. As shown in Figure 11
below, for the nodes JES and MVS Files, a few filters are defined for direct
access and limiting the number of artifacts on the resource tree. The Remote
Systems explorer in the example is shown in Figure 11:
Figure 11. Remote Systems connected to
stplex4a with filters defined for MVS Files
Create the z/OS project and subproject
To help organize the set of artifacts, create a top-level project with two
subprojects — one subproject for the artifacts related to the DCLGEN, and
one subproject for the DB2/COBOL application. After the two subprojects are
created, it should look similar to the z/OS Projects view in Figure 12:
Figure 12. z/OS Projects view with one
project and two subprojects defined
The example will use the name DB2Project as the top-level project and
DCLGenProject as an MVS subproject, which holds the two DCLGEN-related artifacts.
The second subproject, which will hold the batch COBOL application accessing DB2
for z/OS, is called RDZCobolProject in the example.
The following sequence populates the MVS subproject:
- Define the top-level project (DB2Project) by selecting File >
New > Project....
- Select z/OS Project, as shown in Figure 13. The
wizard will guide you through the setup of the project and the MVS subproject.
Figure 13. Creating a z/OS project
- Define the MVS subproject (
DCLGenProject).
- Accept all of the default properties as you progress through the wizard.
- Create the JCL for the DCLGEN. The details are shown in
Listing
2.
- Drag and drop the PDS member ENGLAND.SOURCE.JCL(DCLGEN) from the Remote
Systems Explorer (RSE) to the DCLGenProject.
- Submit the JCL, which will create a PDS member containing the COBOL
declarations. In the example, the member created is
ENGLAND.COBOL.COPYLIB(RDZDCLS) and can then be found in the RSE.
- Drag and drop the PDS member ENGLAND.COBOL.COPYLIB(RDZDCLS) to the
DCLGenProject.
Create the COBOL COPYBOOK using DCLGEN
The first step in creating the DB2/COBOL application is to create a COBOL
COPYBOOK that will be used to define the table and the COBOL record structure to
hold the data defined by the columns. To create the COPYBOOK, the DB2 utility
DCLGEN is used. The sample JCL of a DCLGEN for the table ENGLAND.FRIENDZ is in
Listing 2. You will need to alter the JCL to conform to
your system and your database.
Listing 2. Sample JCL for DCLGEN
//DCLGEN JOB ,
// MSGCLASS=H,TIME=(,4),REGION=28M,COND=(16,LT)
/*JOBPARM S=SY4A
//JOBLIB DD DISP=SHR,DSN=DSN.DSN8.SDSNLOAD
// DD DISP=SHR,DSN=DSN.DSN8.SDSNEXIT
//* ************************************************************
//* This will create a COBOL COPYBOOK from the table definition
//* ************************************************************
//DCLGEN EXEC PGM=IKJEFT01
//SYSPRINT DD SYSOUT=*
//SYSTSPRT DD SYSOUT=*
//SYSTSIN DD *
DSN SYSTEM(DSN8)
DCLGEN TABLE(ENGLAND.FRIENDZ) LIBRARY('ENGLAND.COBOL.COPYLIB(RDZDCLS)')-
LANGUAGE (COBOL) STRUCTURE (FRIENDZRECORD) APOST
// |
To create a new JCL member in an existing Partitioned Dataset (PDS), highlight
the target dataset in the Remote System Explorer view (in my example, it is called
ENGLAND.SOURCE.JCL), right-click, and select Create
PDS Member …. Fill in the member name, and select Finish. Expand the
PDS, and open the newly created member in an edit session. Copy the above JCL into
the edit session. Update the JCL to the requirements of your system, such as where
DB2 for z/OS libraries exist, the JOB Card requirements, and the location of the
resulting COPYBOOK member. Save the JCL using the two-key combination of Ctrl-S.
To submit the JCL, place the cursor in the edit session for the JCL, right-click,
and select Submit. This will submit the job to the Job Entry Subsystem
(JES). You may view the results of the job by expanding the RSE view, the JES
node, and My Jobs node. You may need to refresh the jobs displayed --
highlight My Jobs, right-click, and select Refresh. Find the job in
the tree and double-click on the DCLGEN job, opening the output in an edit
session. Verify the job ran successfully.
The job created the COBOL COPYBOOK member
ENGLAND.COBOL.COPYLIB(RDZDCLS) and should be similar to
Listing 3:
Listing 3. Output generated by DCLGEN
******************************************************************
* DCLGEN TABLE(ENGLAND.FRIENDZ)
* LIBRARY(ENGLAND.COBOL.COPYLIB(RDZDCLS))
* LANGUAGE(COBOL)
* STRUCTURE(FRIENDZRECORD)
* APOST
* ... IS THE DCLGEN COMMAND THAT MADE THE FOLLOWING STATEMENTS
******************************************************************
EXEC SQL DECLARE ENGLAND.FRIENDZ TABLE
( FNAME CHAR(10) NOT NULL,
LNAME CHAR(10) NOT NULL,
PHONE CHAR(10) NOT NULL,
EMAIL CHAR(30) NOT NULL
) END-EXEC.
******************************************************************
* COBOL DECLARATION FOR TABLE ENGLAND.FRIENDZ
******************************************************************
01 FRIENDZRECORD.
10 FNAME PIC X(10).
10 LNAME PIC X(10).
10 PHONE PIC X(10).
10 EMAIL PIC X(30).
******************************************************************
* THE NUMBER OF COLUMNS DESCRIBED BY THIS DECLARATION IS 4
****************************************************************** |
To add the PDS members to the z/OS subproject, drag and drop the desired members
from the Remote Systems view to the z/OS Projects view, releasing the member on
the target subproject. In the example, the PDS members
ENGLAND.COBOL.COPYLIB(RDZDCLS) and ENGLAND.SOURCE.JCL(DCLGEN) were dragged and
dropped to the DCLGenProject subproject. This will give rapid access to these
artifacts in case you need to resubmit the job or inspect the generated COBOL
COPYBOOK in the future.
Create the subproject for the DB2/COBOL application
The first subproject is now created and populated with the DCLGEN-related
artifacts. Now it's time to create the second subproject containing the DB2/COBOL
application.
While in the z/OS perspective, select the top-level project DB2Project,
right-click, and select New > MVS Subproject ….
The MVS subproject wizard will walk you through the setting of properties needed
for the building and execution of the DB2/COBOL application. Only the properties
of interest will be discussed and shown. All other properties can be skipped by
simply clicking Next.
-
Job card – Here, the JOB card is customized for the specific system. In
the example, the job name is RDZDB2, and a JOBLIB points to the DB2 V8 datasets
and is shown in Figure 14. Verify with your system programmer the names of the
DB2 V8 datasets for your installation.
Figure 14. Setting the job card
details
-
COBOL compile step options – On the initial COBOL properties page,
ensure the Use DB2 check box is selected. Expand the ELAXFCOC
tree, exposing the COBOL step, and click on Edit Step, which will bring
up the properties page shown in Figure 15. You may wish
to include
TEST(NONE,SYM,SEPARATE) in the compiler
options entry field if these are not the default for your system. Further, the
DBRM PDS is nominated and the DB2 BIND instructions are shown in the SYSTSIN
entry field. In the example, I nominated the PDS member ENGLAND.DB2.BIND(RDZDB2)
as the input for the SYSTSIN. The DB2 bind instructions are shown in
Listing 4.
Figure 15. Setting the COBOL compile
options
-
Assembler step options – Even though there is no user-written assembler
in the example, the assembler properties are necessary. The properties specified
for the assembler section are used when a CEEUOPT CSECT is generated in support
of a debugging build. For a debugging build, the TEST run-time option is
generated with the TCP/IP address of your workstation. The properties needed are
shown in Figure 16:
Figure 16. Specifying the assembler
build properties for a debugging build
-
Link step options – The link libraries constitute the search order for
the language environment libraries and the DB2 for z/OS library. The link
properties used in the example are shown in Figure 17:
Figure 17. Link edit properties used
to link edit the DB2/COBOL application
-
Run-time step options – The radio button "Run in batch with debugger",
when selected, causes the generation of the CEEUOPT assembler CSECT containing
the TEST run-time option. This is necessary to create a load module that will
invoke the Debug Tool when the application is run. Specify the ELAXFTSO JCL Proc
for the invocation in the Run Procedure Name entry field. This will
generate the execution JCL to run the application under TSO. Also, pay special
attention to the "Additional JCL" entry field. It contains the details on how
the TSO invocation will occur. The full set of properties needed for the example
is found in Figure 18:
Figure 18. Running the DB2/COBOL
application in a debugger mode under TSO
Select Finish to create the subproject and the associated properties.
In the Remote System Explorer, create a new, empty COBOL source file -- highlight
the PDS to contain the new member, right-click, and select Create PDS Member
…. A wizard will prompt you for the new member name. In this example, the PDS
is ENGLAND.SOURCE.COBOL, and the new member is RDZDB2. The COBOL source is found
in Listing 3.
Once the MVS subproject is defined, add the following two PDS members to the MVS
subproject RDZCobolProject using a drag-and-drop operation from the Remote
System Explorer view to the subproject:
- ENGLAND.SOURCE.COBOL(RDZDB2)
- ENGLAND.COBOL.COPYLIB(RDZDCLS)
The project structure is shown in Figure 19:
Figure 19. z/OS Project with two
subprojects populated with source
Notice you have the same artifact in both subprojects. This is okay since the
z/OS projects display a logical organizational structure.
Write the DB2/COBOL application
In Listing 4 below, you will find the DB2/COBOL sample
application that issues an SQL SELECT against the newly
created table. Open the PDS member in the editor from the z/OS projects view --
double-click on the PDS member, and add the following source. You may need to
alter the source slightly, such as the CONNECT
statement or the details of the SELECT statement.
Editing from within the z/OS projects environment allows you to perform a
syntax-check that leverages all of the properties of the project/subproject. To
perform a syntax check on the DB2/COBOL source, highlight the source file name in
the subproject (ENGLAND.SOURCE.COBOL(RDZDB2).cbl in the example), right-click, and
select Syntax Check > Remote. Any errors will be posted to
the remote error list.
Listing 4. Sample DB2 / COBOL source
CBL CODEPAGE(1140) TRUNC(BIN),RENT, SQL
IDENTIFICATION DIVISION.
PROGRAM-ID. RDZDB2.
AUTHOR. MEL, LEE.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
*****************************************************
* VARIABLES FOR ERROR-HANDLING *
*****************************************************
01 ERROR-MESSAGE.
02 ERROR-LEN PIC S9(4) COMP VALUE +960.
02 ERROR-TEXT PIC X(120) OCCURS 10 TIMES
INDEXED BY ERROR-INDEX.
77 ERROR-TEXT-LEN PIC S9(9) COMP VALUE +120.
01 REPREC PIC X(120).
/****************************************************
* FIELDS SENT TO MESSAGE ROUTINE *
*****************************************************
01 MAJOR PIC X(07) VALUE 'RDZDB2'.
01 MSGCODE PIC X(4).
01 OUTMSG PIC X(69).
01 MSG-REC1.
02 OUTMSG1 PIC X(69).
02 RETCODE PIC S9(9).
01 MSG-REC2.
02 OUTMSG2 PIC X(69).
/****************************************************
* SQL INCLUDE FOR SQLDA / SQLCA
*****************************************************
EXEC SQL INCLUDE SQLDA END-EXEC.
EXEC SQL INCLUDE SQLCA END-EXEC.
COPY RDZDCLS.
LINKAGE SECTION.
PROCEDURE DIVISION.
Main Section.
Display "Starting RDZDB2".
EXEC SQL WHENEVER SQLERROR GOTO DBERROR END-EXEC.
EXEC SQL WHENEVER SQLWARNING GOTO DBERROR END-EXEC.
EXEC SQL CONNECT TO DSN8 END-EXEC.
MOVE 'Larry ' to FNAME .
EXEC SQL
SELECT FNAME, LNAME, PHONE, EMAIL
INTO :FNAME, :LNAME, :PHONE, :EMAIL
FROM ENGLAND.FRIENDZ
WHERE FNAME = :FNAME
END-EXEC.
Display "Firstname = ", FNAME.
Display "Lastname = ", LNAME.
Display "Phone nbr = ", PHONE.
Display "Email addr= ", EMAIL.
GOBACK.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* SQL Error *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
DBERROR.
MOVE SQLCODE TO RETCODE OF MSG-REC1.
Display REPREC.
CALL 'DSNTIAR' USING SQLCA ERROR-MESSAGE ERROR-TEXT-LEN.
IF RETURN-CODE = ZERO
PERFORM ERROR-PRINT VARYING ERROR-INDEX
FROM 1 BY 1 UNTIL ERROR-INDEX GREATER THAN 10.
Display "SQL Error. Time to go away".
GOBACK.
*****************************************************
* PRINT MESSAGE TEXT *
*****************************************************
ERROR-PRINT.
Display ERROR-TEXT(ERROR-INDEX). |
Perform the DB2 BIND
The COBOL step options dialog has an entry field that allows you to identify the
DB2 BIND parameters by either providing an in-line
version or by pointing to a PDS member that contains the DB2 bind instructions. In
this example, the SYSTSIN DD statement refers to the PDS member
ENGLAND.DB2.BIND(RDZDB2) for the DB2 bind instructions.
Create the PDS member with the contents shown in Listing 5:
Listing 5. DB2 BIND parameters
DSN SYSTEM(DSN8)
BIND PACKAGE(DSN8.ENGLAND)-
OWNER(ENGLAND) -
MEMBER(RDZDB2) -
LIBRARY('ENGLAND.DB2DBRM') -
ACTION(REPLACE) -
SQLERROR(NOPACKAGE)-
FLAG(I) -
EXPLAIN(NO) -
VALIDATE(BIND)
BIND PLAN(LEETBL) -
PKLIST(DSN8.ENGLAND.*)
END |
Now, drag and drop the PDS member ENGLAND.DB2.BIND(RDZDB2) from the Remote System
Explorer view to the z/OS subproject RDZCobolProject. The project
structure is augmented to look similar to Figure 20:
Figure 20. RDZCobolProject with the PDS
member containing the DB2 Bind statements
To build the load module, highlight the subproject RDZCobolProject,
right-click, and select Rebuild Subproject. The properties that were
specified in the wizard are used in the dynamic construction of JCL to perform the
build. If the build succeeds, a set of new artifacts are added to the project to
produce the structure found Figure 21:
Figure 21. z/OS project and subprojects
fully populated after successful build
If the build fails, compile errors will be posted to the remote error list, and,
if need be, the job output can be found in the Remote Systems Explorer view.
Refresh My Jobs, and double-click on the build job to open the output in the
editor view. The job name is RDZDB2, which was specified in the job card
properties, as shown in Figure 14. An example of the
Remote Systems Explorer showing the job used to build the application is
illustrated in Figure 22:
Figure 22. Remote Systems Explorer
displaying the jobs under the JES node
Double-click on the job name RDZDB2 to open the job output in the editor.
In the example, the job output is partially displayed in Figure 23:
Figure 23. Viewing the job output in the
editor
Correct any errors and complete the build of the DB2/COBOL application.
Debug the DB2/COBOL application
The set of properties specified when creating the RDZCobolProject subproject
indicate the creation a "Debugging" executable in the run-time step options.
To initiate a debug session, highlight the executable
(ENGLAND.EXEC.LOAD(RDZDB2)), right-click, and select Run Application. JCL
will be dynamically built and submitted. The perspective will be automatically
switched to the debug perspective. You may need to dismiss a dialog notifying you
of the switch of perspectives. This dialog is shown in Figure 24:
Figure 24. Confirmation dialog when
switching to the debug perspective
Once in the debug perspective, you are able to debug the application using the
full capabilities of the Debug Tool. The debug perspective has the following
arrangement of views, as Figure 25 shows:
Figure 25. The debug perspective
The power behind the debug perspective is the set of products consisting of Debug
Tool for z/OS V8.1 and Debug Tool Utilities and Advanced Functions V8.1. These two
products work in concert with one another to provide the debugging engine running
on z/OS with the user interface displayed in the debug perspective in Developer
for z.
While in the debug perspective, you can do a number of actions, such as:
- Establish a breakpoint -- double-click on the left margin of the source
editor.
- Monitor the value of a variable -- select the variable, right-click, and
select Monitor Expression. The variable will be visible within the
Monitors view.
- View the variable values of the statement about to be executed in the
Variables view.
- View the current value of a variable -- place the cursor over the variable
within the edit window.
- Step the execution of the COBOL application one statement at a time -- click
on the Step Into action button within the Debug view.
Conclusion
By using the various perspectives available in Rational Developer for System z,
you can perform all of the activities to build a DB2/COBOL application and debug
it.
The ability to easily define a DB2 for z/OS connection, define a DB2 table,
populate the table with test data, create the necessary COBOL COPYBOOK to map the
table, create the DB2/COBOL application, build it, and debug the application –-
all from the same integrated development environment –- provides a very powerful
tool.
Now you have the basics to create a DB2/COBOL application and explore various
capabilities not detailed in this article. Leverage the use of projects and
subprojects to help organize your work. Have some fun!
Resources Learn
Get products and technologies
- Build your next
development project with
IBM trial software,
available for download directly from developerWorks.
Discuss
About the authors | 
| | Laurence (Larry) England is a Senior Technical Staff Member at IBM's Silicon Valley Lab in San Jose, California. He has architectural responsibilities for application development tools on System z. |
| | | Mel Fowler is a Senior Software Engineer at IBM's Silicon Valley Lab in San
Jose, California and a lead programmer for Rational Developer for System z. |
Rate this page
| |
