Tutorial: Create a Visual Data Access Application
In this tutorial, you will create a Data Access application by generating parts in Data
Access Builder and in Visual Builder. The application connects to a database table
called Department (or Dept), which contains records with information about departments in
a company. You can see a summarized list of all the departments, and you can select
a single department and view all the table's columns of information for that department.
Preparing for the Tutorial
- Create a working directory, x:\IBMVAC\Working\datutorial, where
x:\IBMVAC is the directory where the product is installed.
- If you want your application to use a DB2 database, create the DB2 sample database, if
it is not created. To create the sample database, enter the following commands, one
after the other, from a DB2 command line:
db2sampl
Note:
If you choose to use ODBC, rather than DB2, you will use
CPPASAMP40, the sample database provided with Data Access Builder.
Creating the Project and Target
- Start the IDE. On the Welcome page, select Create a new project and
click OK. If the Welcome page does not appear, then select Create
Project from the Project Workbook menu.
- In the Project SmartGuide, enter the project name DataApp. Set the
project directory to x:\IBMVAC\Working\datutorial. Click Next.
- Ensure the New Target setting is Executable. Click Add
Target to launch the Target SmartGuide.
- Enter the target name DataApp. Set the target directory to x:\IBMVAC\Working\datutorial.
- In the Program Type list, select Win IOC or OS/2 IOC,
depending on which operating system you are working on. Click Next.
Creating Parts for the Application
For this application, you will be creating three parts:
- a data access part
- a visual part
- a nonvisual part
Creating the Data Access Part
The data access part generated will provide access to a database table and also the
actions needed to retrieve rows in the table.
- In the New Part drop-down list, select Data Access Part. Click Create
Part. This launches the Data Access SmartGuide.
- On the Select Database and Mapping Method page, select either DB2 or ODBC
from the Database Source drop-down list.
- If you selected DB2, select SAMPLE from the Databases
list. If you selected ODBC, select CPPASAMP40.
- Ensure the mapping method By selecting database tables or views is
selected. Click Next.
- If you selected DB2 for the Database source, select DB2 Call Level Interface
(CLI) as the Access Method. Click Next. You will not
see this page if you selected ODBC.
- Click Get Tables. If you selected DB2, select the table userid.DEPARTMENT.
If you selected ODBC, select the table DEPT. Click OK to
exit the Data Access SmartGuide and return to the Target SmartGuide.
Creating the Visual Part
The visual part will provide a window on which the GUI for the application sits.
- In the New Part drop-down list, select Visual Part. Click Create
another part.
- Enter the Visual Part name MainView. Click Next.
- Select the base class IFrameWindow. Click Next.
- Select the client area IMultiCellCanvas. Click OK to
return to the Target SmartGuide.
Creating the Nonvisual Part
The nonvisual part is the main code that launches the application.
- In the New Part drop-down list, select Nonvisual / Class Interface Part.
Click Create another part.
- Enter the Nonvisual Part name DataApp.
- On the Base Class page, select the Nonvisual radio button, and select IVBMain
from the Base Class drop-down list. Click OK.
All three parts have now been added to the DataApp target. Click OK
in the Target SmartGuide and Finish in the Project SmartGuide. When
asked if you want to open the project in the IDE, click Yes. When
asked if you want to build it, click No.
Modifying the Data Access Part
Go to the Data Access page in the Project tab. Select Refresh View from
the pop-up menu in the upper pane. Select the data access part, called DATAAPP.DAX,
and click Edit Session. This will launch the Data Access Builder
main window.
If you were creating an application that required customized data access, then this is
when you would customize the mapping to suit your needs. However, for this tutorial,
the default mapping, with the following modifications, is sufficient:
- Double-click on the mapping icon
.
- If you are using the DB2 sample database, SAMPLE, then change the mapping name so that
the instructions that follow are easy to follow. Change both Class Name and
File Stem from Department to Dept.
- Ensure that the Generate Forms option is enabled.
- Click OK.
- Select Save from the File menu. When asked
whether you want to remove the old .vbf objects from the configuration file, click Yes.
Close Data Access Builder. Go to the Parts page and refresh the parts view.
Adding the Connection Canvas Part to the Configuration File
The Data Access Class Library includes a class called IDSConnectCanvasBase that provides a
visual front end to connecting to and disconnecting from a database. You need this
class for the application, so it must be added to the configuration file.
IDSConnectCanvasBase is in a source file called idsccabs.vbf, in the product's include
directory. To add it:
- Click the Configuration tab.
- On the Source page, add the line source "idsccabs.vbf", so that
the list of source files looks like this (the added line is shown third from the bottom):
source "DeptManagerTemplate.vbf"
source "DeptManagerBase.vbf"
source "DeptManager.vbf"
source "DeptForm.vbf"
source "DeptDatastore.vbf"
source "Dept.vbf"
source "DataApp.dax"
source "idsccabs.vbf"
source "MainView.vbf"
source "DataApp.vbf"
- Type Ctrl+S to save the configuration file.
- Return to the Parts page in the Project and refresh the view.
Setting Up the Nonvisual Main Part
To set up the nonvisual main part that you created:
- In the Parts page, select the nonvisual part, DataApp.
- Click Edit Part to launch Visual Builder.
- Select Add Part from the Options menu.
- Enter the class name MainView (which is the visual part you
generated). Click OK.
- Click in the upper left-hand area of the Visual Builder canvas to place the window.
- Click mouse button 2 on the canvas. Select Connect, ready.
- Your pointer will now have a line attached to it. Click on the MainView part and select Show.
A arrow points from the canvas to the MainView part, indicating that the nonvisual
executable will open the MainView visual part.
- Select Save from the File menu, and then exit.
Creating the Data Access Application GUI
The next step is creating the GUI that uses the data access parts to retrieve database
table contents. The GUI is built on MainView, the visual part you generated. In the
upcoming steps, you will add the following parts to the main view:
- A connection panel that lets you click buttons to connect, disconnect, commit, and
rollback.
- A message box that informs you if an error occurred.
- A list that shows all the departments in the database by department number and name.
- A form that shows all column values for a department when you select it in the list.
- The data access parts that let the GUI actually access and display the contents of the
Department table.
To create the GUI and connect it to the data access parts:
- In the Parts page of the IDE, select the visual part, MainView, and click Edit
Part. The Visual Builder will start. The MainView part, with the Cancel
connection made, is shown.
- Create GUI for connecting to the database:
- Select Add Part from the Options menu. Enter the class
name IDSConnectCanvasBase and click OK. Note:
An alternative to typing in the whole class name is clicking the List
button. In the list, type in the first few letters of the class name, and then select it
from the list and click OK.
- Click in the upper left-hand corner of the MainView window to place the part.
- Similarly add the part DeptDatastore, but drop it off the MainView window,
on the canvas.
- From the new DeptDatastore part's pop-up menu, select Connect, this.
With a line attached to your mouse pointer, click on the IDSConnectCanvasBase part.
From the pop-up menu, select All Features. From the attributes
list, select datastoreBase.
The application can now connect to the Department table in the sample database, commit
or rollback changes, and disconnect from it, all by clicking the buttons on the connection
canvas. You will see this in action later, when you run the application.
- Create GUI for listing the departments by department number and name:
- From the Visual Builder parts pallet, select the Lists category, and the IVBContainer
part.
- Drop it on MainView, just below the connection canvas. Stretch the part so that it
fills up the space below the connection canvas.
- Double-click on the new container. In the Properties list, click on viewType.
Select showDetailsView from the drop-down list.
- Click mouse button 2 on the IVBContainer part and select Change Template
Arguments from the pop-up menu. Select the class Element item
and type Dept* in the entry field. Click OK. This sets
the table to be list of pointers to Dept objects (rows from the Department table).
- From the pallet, select the IContainerColumn part and click on the IVBContainer on
MainView. Select it again, and drop another column on the container. The
container now has two columns, one for department numbers, and the other for department
names.
- Double-click on the left-hand column.
- Select the Column Definition property and click the ...
button.
- Select the Use an attribute from the part radio button, and select deptNoAsString
from the Attributes list. Click OK.
- Select the headingText property and enter Dept No.
Click OK.
The column is now set to display deptno attributes (department numbers) from Dept
objects.
- Double-click on the right-hand column.
- Select the Column Definition property and click the ...
button.
- Select the Use an attribute from the part radio button, and select deptnameAsString
from the Attributes list. Click OK.
- Select the displayWidth property and enter 200.
- Select the headingText property and enter Dept Name.
Click OK.
The column is now set to display deptname attributes (department names) from Dept
objects.
- Connect the list GUI to the data access part that accesses rows in the table:
- Select Add Part from the Options menu. Enter the
class name DeptManager and click OK. Click on the canvas to
drop the part.
- From the new DeptManager part's pop-up menu, select Connect, items.
With a line attached to your mouse pointer, click on the IVBContainer object. Be
very careful not to click on one of the columns; the red dotted line should highlight the
entire IVBContainer part. From the pop-up menu, select items.
- Create connection to show list departments when a successful database connection
is made:
- From the pop-up menu for the DeptDatastore part, select Connect, All
Features. From the Events list, select Connected. With a
line attached to your mouse pointer, click the DeptManager part. From the pop-up menu,
select select.
- The connection line that you just made is dotted because the select method requires a
parameter: an SQL statement that indicates which rows to select. Double-click the
dotted line and click Set Parameters button.
- Select the clause parameter and enter the following string, which will select all rows
in the table and display them in order of department number:
1=1 order by deptno
- Click OK twice.
- Handle exceptions:
- If an error occurs while the application is connecting to the database or retrieving the
rows, you need to pass the error message on to the user. Add a message box for the
error message by selecting the Other category on the pallet. Select the IMessageBox part
button and drop the part near the connection you just made (on the canvas).
- Click mouse button 2 on the connection line. From the pop-up menu, select Connect,
exceptionOccurred. With a line attached to your mouse pointer,
click the new IMessageBox part. From the pop-up menu, select showException.
- Create a form that shows details of a selected department:
- To add the data access form part in this step, you may have to stretch the MainView part
so that everything will fit in. Click on the MainView window's title bar, and then
grab the black square at the bottom right-hand corner of the window. Drag it down
and to the right to make the window larger. You can also move the nonvisual parts
(DeptDatastore, DeptManager, and MessageBox) by clicking and dragging them. The
connections will remain.
- Select Add Part from the Options menu. Enter the
class name DeptForm and click OK. Drop the part in the
right-hand section of the MainView window, next to the IVBContainer. The form shows
each of the Department table's columns as an attribute. When the application runs,
the fields will show the column values for the department selected in the IVBContainer.
- Select the IVBContainer (be sure not to select one of its columns). From its
pop-up menu, select Connect, selectedItem. With a
line attached to your mouse pointer, click the new DeptForm part. Select All
Features from the pop-up menu. From the Action list, select targetAsDept.
Click OK. The connection line created is very short, between the
IVBContainer and the DeptForm part.
- You have now created the entire GUI and made all necessary connections. Select Save
and Generate, Part Source from the File
menu. Exit Visual Builder.
Building and Running the Visual Data Access Application
In the IDE, click the Save all changes and build button in the
toolbar. The build process may take a few minutes, depending on your system.
To run the application from within the IDE, go to the Debug page of the Project, and
click the Run button. To run it from the VisualAge for C++ command
line, go to x:\IBMVAC\Working\datutorial and type DataApp.
Browsing the Application
The application you just created has a graphical front end to a real database table.
If you had implemented an update feature, changes made in the application would actually
change the content of the table. This application, however, only lets you look at
the contents of the table. The database table itself contains records for
departments in a company. The application shows a list of all the department names
and numbers, ordered by number. When you select a department, the application shows
all column values for that department, including the manager's employee number, the
administrating department, and the department's location.
To connect to the database and retrieve the list of all departments, click Connect.
If you are not logged in to your system under the same user ID with which you created the
sample database, fill in the User ID and Password
fields; use a user ID that has access to the sample database.
In the list of departments, select one by clicking on it with the mouse or by using the
arrow keys on the keyboard. The contents of the selected department are displayed in
the form on the right.
When you are done, click Cancel. In the tutorial steps, you did
not provide functionality for the OK or Help buttons, so
they do nothing.