0306alazzawe1 PDF

8/6/2019 0306alazzawe1 PDF

1/20

Binding DB2 Stored Procedures to Visual C#WinFormsSkill Level: Introductory

Abdul Al-Azzawe ([email protected])IBM

19 Jun 2003

This tutorial demonstrates how to use the DB2 Development Add-In for Visual Studio.NET to build a WinForm Visual C# project targeting a DB2 for z/OS and OS/390database to access stored procedures.

Section 1. Tutorial introduction

What is this tutorial about?

This tutorial demonstrates the use of the Visual C# WinForms project template andthe IBM DB2 Development Add-In to create a client application that accesses storedprocedures and tables residing in a DB2 for z/OS database. To showcase the easeof building data-bound client forms, we will walk you through the steps required tobuild a sample application, Department, which manages a list of employees in adepartment and their salaries for a small company.

In this tutorial, you will learn how to do the following:

Build databound WinForms C# applications.

Create and configure a toolbox data adapter for a DB2 stored procedure.

Create and configure a toolbox data set for a data adapter.

Drag and drop procedures and tables onto WinForms.

Binding DB2 Stored Procedures to Visual C# WinForms Trademarks Copyright IBM Corporation 2003. All rights reserved. Page 1 of 20
mailto:[email protected]://www.ibm.com/developerworks/ibm/trademarks/http://www.ibm.com/legal/copytrade.shtmlhttp://www.ibm.com/legal/copytrade.shtmlhttp://www.ibm.com/developerworks/ibm/trademarks/mailto:[email protected]


2/20

Create and configure a data adapter for a DB2 table.

Generate a dataset for the data adapter.

Modify the data adapter to use a stored procedure command.

Bind and configure data grids to data sets.

Add DB2 command parameters and bind them to form controls.

Notes:

This tutorial requires an existing EmpSp stored procedure and EmpTbltable developed in an earlier tutorial Developing DB2 Projects in VisualStudio .Net.

Although this tutorial is targeting the DB2 for z/OS V7 server, the sametutorial may be adopted to target the other DB2 servers such as DB2 forLinux, UNIX, or Windows V8 servers, as long as the prerequisite tutorialwas executed on that DB2 platform.

Should I take this tutorial?

You should take this tutorial if:

You want to learn about the data-bound WinForms in Visual Studio .NET.

You want an example of developing a Visual C# WinForm application

using the DB2 .Net managed provider.

You want to see an example of binding an ADO.NET Command inputparameter to a form control.

You are familiar with developing ADO.NET applications and you want tosee how easy it is to develop similar applications targeting the DB2 forz/OS server.

You want to see the power of the DB2 ADO.NET drag and drop codegeneration and object tooling.

You want to learn how to configure a toolbox data adapter and data setfor a stored procedure command.

You want to explore an example of modifying a drag and drop table dataadapter to use a stored procedure command.

You want to learn more about the advanced features of the DB2Development Add-In for Visual Studio .NET.

developerWorks ibm.com/developerWorks

http://www.ibm.com/developerworks/ibm/trademarks/http://www.ibm.com/legal/copytrade.shtmlhttp://www.ibm.com/legal/copytrade.shtmlhttp://www.ibm.com/developerworks/ibm/trademarks/


3/20

Tools used in this tutorial

To complete the steps in this tutorial, you need the following software:

IBM DB2 V8.1 Application Development Client.

IBM DB2 .NET enablement package which is available as part of DB2V8.1.2 or later. Otherwise, you will need to download the .NETenablement beta.

IBM DB2 for z/OS V7 to be installed and and configured on themainframe server, or any other DB2 server having the EmpSP storedprocedure and EmpTbl table created using the pre-requisite tutorialDeveloping DB2 Projects in Visual Studio .Net.

Microsoft Visual Studio .NET

Microsoft Windows 2000, 2003, XP, or NT operating system.

Section 2. Tutorial overview

Application overview

The Departments application is a simple Visual C# ADO.NET application thatprovides you with three forms to view and manage a list of department employeeswith salary and commission information. These forms will access a server storedprocedure and table using ADO.NET objects to query, modify, add, and removedepartment employee entries.

The Department LaunchPad is the main form that allows you to launch the othertwo forms.

The ViewDepartment form allows you to view the list of all employee entries in adepartment using the EmpSP stored procedure. The form provides a read-onlyinterface to the database EmpTbl table.

The ManageDepartment form allows you to query the list of employees in a givendepartment and then be able to add, remove, and modify entries in that list. This isaccomplished using a combination of the EmpSp stored procedure and EmpTbltable.

ibm.com/developerWorks developerWorks



4/20

Section 3. Department application setup

Step 1: Create the Visual C# project

In this step, we will create our WinForm C# project and add the required forms asfollows:

1. Launch Visual Studio .NET

2. From the Visual Studio .NET IDE, select the menu File => New =>

Project. This will launch the New Project dialog.

3. From the New Project dialog, open the Visual C# Projects folder andselect the Windows Application project template.

4. Type Department for the project name and click OK.

You should now see the Department solution and project in the Solution Explorer ofyou Visual Studio .NET IDE. A blank form, Form1, should now be open in designmode.




5/20

Step 2: Adding the project forms

To add the required forms to the project, follow these steps:

1. Select the Department project folder from the Solution Explorer.

2. Right click on the project folder and select the Add => Add New Itempop-up menu. This will launch the Add New Item dialog.

3. Select the Windows Form item template.

4. Type ViewDepartment.cs in the Name field.

5. Click OK.

You should now see the ViewDepartment.cs item added to you project.

Repeat the same steps to add the ManageDepartment.cs form to your project.

Step 3: Setting up the main project form

In this step, we will setup the main application form as follows:




6/20

1. From your Department project folder, select the Form1.cs project item.

2. Right click on Form1.cs and select the Rename pop-up menu.

3. Rename Form1.cs to Main.cs

4. Double click the Main.cs to open the form designer.

5. In the Properties dialog, specify the value LaunchPad for the Nameproperty.

6. In the Properties dialog, specify the value Department Launchpad forthe Text property.

7. In the Properties dialog, select the drop-down value FixedToolWindowfor the FormBorderStyle property.

8. Right click on the Main project form and select View Code pop-up menuentry. This should display the code for Main.cs

9. To the LaunchPad class definition, add the following declarations:

public Department.ViewDepartment frmViewDepartment = null;public Department.ManageDepartment frmManageDepartment = null;

10. From the editor's methods list, select the LaunchPad() method and insertthe following code below the InitializeComponent method:

this.frmViewDepartment = new Department.ViewDepartment();this.frmManageDepartment = new Department.ManageDepartment();

11. From the editor's methods list, select the Main() method and change theForm1 name with LaunchPad as follows:

Application.Run(new LaunchPad());

12. Save the project.

Step 4: Linking the ViewDepartment form

In this step, we will enable launching the ViewDepartment form from theLaunchPad from as follows:




7/20

1. Right click on the Main project form and select View Designer pop-upmenu entry. This should open the form's designer view.

2. From the Toolbox, drag a button control and drop it on the Main form.

3. Select the New button.

4. In the Properties dialog, specify the value btnViewDepartment for theName property.

5. In the Properties dialog, specify the value View Department... for theText property.

6. Double click on the btnViewDepartment button. This should open thecode view.

7. In the btnViewDepartment_Click method, type the following code:

this.frmViewDepartment.Show();


Step 5: Linking the ManageDepartment form

In this step, we will enable launching the ManageDepartment form from the

LaunchPad from as follows:

1. Right click on the Main project form and select View Designer pop-upmenu entry. This should open the form's designer view.

2. From the Toolbox - Windows Forms, drag a button control and drop it onthe Main form.


4. In the Properties dialog, specify the value btnManageDepartment for the

Name property.

5. In the Properties dialog, specify the value Manage Department... for theText property.

6. Double click on the btnManageDepartment button. This should open thecode view.




8/20

7. In the btnManageDepartment_Click method, type the following code:

this.frmManageDepartment.Show();


Section 4. Adding the DB2 data connections

Adding the DB2 data connection

In order to access DB2 server catalogs and develop new DB2 database project, youwill first need to add the target DB2 server connection to the data connections folderof the IBM Explorer.

We assume that you have already cataloged the ZOS_DEMO database as per theinstructions detailed in the Developing DB2 Projects in Visual Studio .Netprerequisite tutorial.

To add the ZOS_DEMO database connection, follow these steps:

1. Launch the IBM Explorer using View => IBM Explorer.

2. Select the Data Connections folder of the IBM Explorer, and click on theAdd Connection pop-up menu action. This will launch the DatabaseConnection Properties dialog.

3. Select the ZOS_DEMO database alias and specify an appropriate username and password. For our tutorial, we will use a user name of demo01and a password of demo01.

4. Click the Test Connection button to ensure that you have proper

connectivity.

5. Click OK to add the connection.

Note:

You can choose any other DB2 database server, provided that the databasecontains the required EmpSp stored procedure and EmpTbl table.


http://www7b.software.ibm.com/dmdd/library/tutorials/0305alazzawe/index.htmlhttp://www.ibm.com/developerworks/ibm/trademarks/http://www.ibm.com/legal/copytrade.shtmlhttp://www.ibm.com/legal/copytrade.shtmlhttp://www.ibm.com/developerworks/ibm/trademarks/http://www7b.software.ibm.com/dmdd/library/tutorials/0305alazzawe/index.html


9/20

Step 2: Validating the DB2 data connection

This tutorial relies on the existing EmpSp stored procedure and EmpTbl table in theZOS_DEMO database. These objects were created in the Developing DB2 Projects

in Visual Studio .Net prerequisite tutorial.

To validate the existence and content of the EmpSP stored procedure, do thefollowing:

1. Expand the ZOS_DEMO data connection folder.

2. Expand the Procedures folder.

3. Right click on the EmpSP entry and select the Run Stored Procedurepop-up menu entry. This will show the Parameter Values dialog.

4. Specify a value of 17 for the QDEP parameter.

5. Click OK.

You should see a DB2 Data Result data grid. If you expand the RESULTSET entry,you should see all the employees for that department.

To validate the existence and content of the EmpTbl table, do the following:

1. Expand the ZOS_DEMO data connection folder.

2. Expand the Tables folder.

3. Right click on the EmpTbl entry and select the Retrieve Table Datapop-up menu entry.

You should see a DB2 Data Result data grid showing the row entries found in theEmpTbl table.

Section 5. Implementing View Department form

Step 1: Setting up the View Department form


http://www7b.software.ibm.com/dmdd/library/tutorials/0305alazzawe/index.htmlhttp://www7b.software.ibm.com/dmdd/library/tutorials/0305alazzawe/index.htmlhttp://www.ibm.com/developerworks/ibm/trademarks/http://www.ibm.com/legal/copytrade.shtmlhttp://www.ibm.com/legal/copytrade.shtmlhttp://www.ibm.com/developerworks/ibm/trademarks/http://www7b.software.ibm.com/dmdd/library/tutorials/0305alazzawe/index.htmlhttp://www7b.software.ibm.com/dmdd/library/tutorials/0305alazzawe/index.html


10/20

In this step, we will drop the required controls on the form as follows:

1. Right click on the ViewDepartment project form and select ViewDesigner pop-up menu entry. This should open the form's designer view.

2. From the Toolbox - Windows Forms, drag a TextBox and drop it on theform.

3. Select the new TextBox.

4. In the Properties dialog, specify the value txtDeptNo for the Nameproperty and the value 15 for the Text property.

5. From the Toolbox - Windows Forms, drag a button and drop it on theform.


7. In the Properties dialog, specify the value btnRefresh for the Nameproperty and the value Refresh for the Text property.

8. From the Toolbox - Windows Forms, drag a DataGrid and drop it on theform.


Step 2: Adding the ADO.NET objects to the formIn this step, we will drop the required ADO.NET objects to the form as follows:


2. From the Procedures folder of the ZOS_DEMO data connection in theIBM Explorer, drag the EmpSP stored procedure and drop it onViewDepartment form. This should create a db2Connection1 anddb2SPCommand1 objects in the component tray of the form.

3. From the Toolbox - Data, drag a DB2DataAdapter and drop it on theform. This should create dB2DataAdapter1 object in the component trayof the form.

4. Select the dB2DataAdapter1 object.




11/20

5. In the Properties dialog, select the db2SPCommand1 drop down entry asthe value of the dB2DataAdapter1 SelectCommand property.

6. From the Toolbox - Data, drag a DataSet and drop it on the form. Thisshould launch the Add Dataset dialog.

7. In the Add Dataset dialog, select the Untyped dataset radio button.

8. Click OK. You should now see the dataSet1 object in the component trayof the form.


Step 3: Binding the View Department form controls

In this step, we will bind the form controls to the data adapter and retrieve the datafrom the database.





12/20

2. Select the data grid.

3. In the Properties view, choose the dataSet1 drop-down value for theDataSource property.

4. Double click on the btnRefresh button. This should open the code view ofthe form.

5. Type the following code in the btnRefresh_Click method:

this.db2SPCommand1.Parameters[0].Value = this.txtDeptNo.Text;this.dataSet1.Clear();this.dB2DataAdapter1.Fill(this.dataSet1);

// Re-bind the data grid now that we have a table in the data set.this.dataGrid1.SetDataBinding(this.dataSet1,"Table");


Notes:

Although we chose to reference the parameter of the db2SPCommand1by index (i.e. 0), you can certainly reference the parameter by name.Simply pass in the quoted name of the parameter in place of the index.You will need to ensure that you type the exact parameter name,including all trailing blanks, as defined in thedb2SPCommand1.Parameters.Add metod call in the initialize section for

this command. Since we are dealing with a stored procedure command, there is no

pre-defined table mapping. This means that you will not get a pre-definedtable mapping entry for the data set. When you click the Refresh buttonin this form, the result set will not be automatically expanded; rather, youwould have to expand the "Table" entry to show the result set from thestored procedure call.To overcome this minor usability issue, we have added theSetDataBinding call for the data grid after filling the data set. This wouldensure that the result set will be expanded automatically.

Setp 4: Optional data grid configurations

To improve the usability of the data grid control, we need to properly anchor thecontrol and switch it to read-only mode, and to expand it so that it shows the singleresult set.




13/20

To properly configure the data grid control, follow these optional steps:


2. Select the datagrid.

3. Resize and re-position the data grid so that it is almost touching thebottom, left, and right form borders. Leave enough space in the top of theform for the textbox and button controls.

4. Modify the Anchor property of the data grid to be "Top, Bottom, Left,Right."

5. Specify the value True for the ReadOnly behavior property.

6. Specify the value False for the RowHeadersVisible display property.

7. Specify the value False for the CaptionVisible display property.

You can also choose to display the data grid in a different style. This can beaccomplished as follows:



3. Click the Auto Format command link in the Properties view.

4. Choose a more pleasing format, such as the Classic format.

Section 6. Implementing Manage Department form

Step 1: Setting up the View Department form

In this step, we will drop the required controls on the form as follows:

1. Right click on the ManageDepartment project form and select View




14/20

Designer pop-up menu entry. This should open the form's designer view.

2. From the Toolbox - Windows Forms, drag a TextBox and drop it on theform.

3. Select the new TextBox.

4. In the Properties dialog, specify the value txtDeptNo for the Nameproperty and the value 15 for the Text property.

5. From the Toolbox - Windows Forms, drag a button and drop it on theform. Repeat for a second button.

6. Select the first new button.

7. In the Properties dialog, specify the value btnRefresh for the Nameproperty and value Refresh for the Text property.

8. Select the second new button.

9. In the Properties dialog, specify the value btnUpdate for the Nameproperty and the value Update for the Text property.

10. From the Toolbox - Windows Forms, drag a DataGrid and drop it on theform.


Step 2: Adding the ADO.NET objects to the form

In this step, we will drop the required ADO.NET objects to the form as follows:

1. Right click on the ManageDepartment project form and select ViewDesigner pop-up menu entry. This should open the form's designer view.

2. From the Tables folder of the ZOS_DEMO data connection in the IBMExplorer, drag the EmpTbl table and drop it on ManageDepartmentform. This should create a db2Connection1 and db2DataAdapter1

objects in the component tray of the form.

3. From the Procedures folder of the ZOS_DEMO data connection in theIBM Explorer, drag the EmpSP stored procedure and drop it onManageDepartment form. This should create a db2SPCommand1object in the component tray of the form.




15/20

4. Select the db2DataAdapter1 object from the component tray and click onthe Generate Dataset command link in the Properties view. This shoulddisplay the Generate Dataset dialog.

5. Select to create a new DataSet and click OK. The file, DB2DataSet1.xsd,should be added to your Department project, and the object,db2DataSet11, should be added to the component tray of theManageDepartment form.


Step 3: Updating the data adapter to call a stored procedure

In this step, we will modify the data adapter's select command to use the storedprocedure command in place of the default table select command.

Follow these steps:


2. Select the db2DataAdapter object from the component tray.

3. Choose the value db2SpCommand1 from the drop-down combo box forthe SelectCommand data adapter property.


We have simply modified the data adapter to use the stored procedure command inplace of the SELECT SQL to retrieve the department information. We have kept theremaining INSERT, UPDATE, and DELETE commands as is to propagate updatesback to the EmpTbl table.

This trick basically allows us to re-use the update commands as well as the mappinginformation required to define a proper data set for our form.

This is possible because the stored procedure will return the exact same set ofcolumns as the original SELECT statement.

Step 4: Binding the Manage Department form controls

In this step, we will bind the form controls to the data adapter and retrieve the datafrom the database.




16/20


2. Select the data grid.

3. In the Properties view, choose the db2dataSet11.EMPTBL drop-downvalue for the DataSource property.

4. Double click on the btnRefresh button. This should open the code view ofthe form.

5. Type the following code in the btnRefresh_Click method:

this.db2SPCommand1.Parameters[0].Value = this.txtDeptNo.Text;this.db2DataSet11.Clear();this.db2DataAdapter1.Fill(this.db2DataSet11);

6. Double click on the btnUpdate button. This should open the code view ofthe form.

7. Type the following code in the btnUpdate_Click method:

this.db2DataAdapter1.Update(this.db2DataSet11);


Step 5: Optional data grid configurations

To improve the usability of the data grid control, we need to properly anchor thecontrol.

To properly configure the data grid control, follow these optional steps:



3. Resize and re-position the data grid so that it is almost touching thebottom, left, and right form borders. Leave enough space in the bottom ofthe form for other button controls.

4. Modify the Anchor property of the data grid to be"Top, Bottom, Left,




17/20

Right."

5. Specify the value False for the CaptionVisible display property.

You can also choose to display the data grid in a different style. This can beaccomplished as follows:



3. Click the Auto Format command link in the Properties view.

4. Choose a more pleasing format, such as the Classic format.

Section 7. Testing the Employees application

Step 1: Testing the View Department form

To test the ViewDepartment application form, follow these steps:

Run the Department application.

In the Department LaunchPad form, click View Department. Thisshould launch the ViewDepartment form.

In the ViewDepartment form, specify a department number of 15, 17, orany other one and click Refresh. This should display the up-to-date list ofdepartment employees returned from the EmpSP stored procedure.

Step 2: Testing the Manage Department form

To test the ManageDepartment application form, follow these steps:

Run the Department application.

In the Department LaunchPad form, click Manage Department. Thisshould launch the ManageDepartment form.




18/20

In the ManageDepartment form, specify a department number of 15, 17,or any other one and click Refresh. This should display the up-to-date listof department employees returned from the EmpSP stored procedure.

You can modify, add, and remove records to this table using the

read/write data grid. Make sure to click the Update button to propagatethe changes to the database server.

Section 8. Summary and resources

Summary

In this tutorial you learned how easy it is to build a Visual C# data-bound WinFormsapplication targeting a DB2 for z/OS and OS/390 database to access a storedprocedure and its associated table. You saw how you can use the IBM Explorer andthe DB2 .NET managed provider tooling that are part of the IBM DB2 DevelopmentAdd-In for Microsoft Visual Studio .NET to make client application development asnap.

You also learned how to:

Create and configure a toolbox data adapter for a DB2 stored procedure.

Create and configure a toolbox data set for a data adapter.

Drag and drop procedures and tables onto WinForms.

Create and configure a data adapter for a DB2 table.

Generate a dataset for the data adapter.

Modify the data adapter to use a stored procedure command.

Bind and configure data grids to data sets.

Add DB2 command parameters and bind them to form controls.

All of the tasks required to build this application were done within the IDE itself,demonstrating the tight integration of the DB2 application development tooling in thisenvironment. The same skills you learned in building this DB2 for z/OS and OS/390database project can be applied towards building any DB2 cross-platform databaseproject.




19/20




20/20

Resources

Learn

DB2 developer domain for additional technical articles and tutorials

Developing DB2 for z/OS projects in Visual Studio .Net (Pre-requisite tutorial)

DB2 Database Project for Visual Studio .Net

Get products and technologies

DB2 Universal Database Version 8.1

Discuss

Participate in the discussion forum for this content.

About the author

Abdul Al-Azzawe

Abdul Al-Azzawe is the DB2 Tools architect for Visual Studio .NET. Hejoined IBM in 1990 and worked in the Toronto lab for ten years as partof the DB2 engine development team with special focus on theWindows platform. In March of 2000, Abdul joined the IBM Siliconvalley lab to architect the release of the DB2 integrated SQL debugger,the DB2 Development Center, and the DB2 Development Add-Ins forVisual Studio 6.0. In May of 2002, Abdul joined the IBM San Francisco

team to architect the integration with Visual Studio .NET, one of hisproudest achievements in his career at IBM. Abdul has writtennumerous technical articles under the DB2 developer domain coveringa variety of DB2 application development topics. Abdul appreciateshearing feedback from actual developers about DB2 tools, andwelcomes any suggestions for ways to improve these products.

Trademarks

IBM, DB2, and DB2 Universal Database are registered trademarks of the IBMCorporation in the United States and/or other countries.

Other company, product and service names may be trademarks or service marks ofothers.

Microsoft, Windows, Visual Studio, and CLR are registered trademarks of MicrosoftCorporation in the United States, other countries, or both.


http://www.ibm.com/developerworks/db2http://www.ibm.com/developerworks/db2/library/tutorials/0305alazzawe/index.htmlhttp://www.ibm.com/developerworks/db2/library/tutorials/0305alazzawe/index.htmlhttp://www.ibm.com/developerworks/db2/library/techarticle/0304alazzawe1/0304alazzawe1.htmlhttp://www.ibm.com/developerworks/downloads/?S_TACT=105AGX11&S_CMP=tuthttp://www.ibm.com/developerworks/community/http://www.ibm.com/developerworks/ibm/trademarks/http://www.ibm.com/legal/copytrade.shtmlhttp://www.ibm.com/legal/copytrade.shtmlhttp://www.ibm.com/developerworks/ibm/trademarks/http://www.ibm.com/developerworks/community/http://www.ibm.com/developerworks/downloads/?S_TACT=105AGX11&S_CMP=tuthttp://www.ibm.com/developerworks/db2/library/techarticle/0304alazzawe1/0304alazzawe1.htmlhttp://www.ibm.com/developerworks/db2/library/tutorials/0305alazzawe/index.htmlhttp://www.ibm.com/developerworks/db2

Documents

0306alazzawe1 PDF