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

  1. Create a working directory, x:\IBMVAC\Working\datutorial, where x:\IBMVAC is the directory where the product is installed.
  2. 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

  1. 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.
  2. In the Project SmartGuide, enter the project name DataApp.  Set the project directory to x:\IBMVAC\Working\datutorial.  Click Next.
  3. Ensure the New Target setting is Executable.  Click Add Target to launch the Target SmartGuide.
  4. Enter the target name DataApp.  Set the target directory to x:\IBMVAC\Working\datutorial.
  5. 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:

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.

  1. In the New Part drop-down list, select Data Access Part.  Click Create Part.  This launches the Data Access SmartGuide.
  2. On the Select Database and Mapping Method page, select either DB2 or ODBC from the Database Source drop-down list.
  3. If you selected DB2, select SAMPLE from the Databases list.  If you selected ODBC, select CPPASAMP40.
  4. Ensure the mapping method By selecting database tables or views is selected.  Click Next.
  5. 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.
  6. 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.

  1. In the New Part drop-down list, select Visual Part.  Click Create another part.
  2. Enter the Visual Part name MainView.  Click Next.
  3. Select the base class IFrameWindow.  Click Next.
  4. 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.

  1. In the New Part drop-down list, select Nonvisual / Class Interface Part.  Click Create another part.
  2. Enter the Nonvisual Part name DataApp.
  3. 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:

  1. Double-click on the mapping icon nxcclspp.gif (1017 bytes).
  2. 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.
  3. Ensure that the Generate Forms option is enabled.
  4. Click OK.
  5. 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:

  1. Click the Configuration tab.
  2. 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" 
  3. Type Ctrl+S to save the configuration file.
  4. 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:

  1. In the Parts page, select the nonvisual part, DataApp.
  2. Click Edit Part to launch Visual Builder.
  3. Select Add Part from the Options menu.
  4. Enter the class name MainView (which is the visual part you generated).  Click OK.
  5. Click in the upper left-hand area of the Visual Builder canvas to place the window.
  6. Click mouse button 2 on the canvas.  Select Connect, ready.
  7. 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.
  8. 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:

To create the GUI and connect it to the data access parts:

  1. 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.
  2. Create GUI for connecting to the database:
    1. 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.
    2. Click in the upper left-hand corner of the MainView window to place the part.
    3. Similarly add the part DeptDatastore, but drop it off the MainView window, on the canvas.
    4. 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.

  3. Create GUI for listing the departments by department number and name:
    1. From the Visual Builder parts pallet, select the Lists category, and the IVBContainer part.
    2. Drop it on MainView, just below the connection canvas.  Stretch the part so that it fills up the space below the connection canvas.
    3. Double-click on the new container. In the Properties list, click on viewType.  Select showDetailsView from the drop-down list.
    4. 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).
    5. 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.
    6. Double-click on the left-hand column.
      1. Select the Column Definition property and click the ... button.
      2. Select the Use an attribute from the part radio button, and select deptNoAsString from the Attributes list. Click OK.
      3. Select the headingText property and enter Dept No.  Click OK.

      The column is now set to display deptno attributes (department numbers) from Dept objects.

    7. Double-click on the right-hand column.
      1. Select the Column Definition property and click the ... button.
      2. Select the Use an attribute from the part radio button, and select deptnameAsString from the Attributes list. Click OK.
      3. Select the displayWidth property and enter 200.
      4. Select the headingText property and enter Dept Name.  Click OK.

      The column is now set to display deptname attributes (department names) from Dept objects.

  4. Connect the list GUI to the data access part that accesses rows in the table:
    1. Select Add Part from the Options menu.  Enter the class name DeptManager and click OK. Click on the canvas to drop the part.
    2. 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.
  5. Create connection to show list departments when a successful database connection is made:
    1. 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.
    2. 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.
    3. 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
    4. Click OK twice.
  6. Handle exceptions:
    1. 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).
    2. 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.
  7. Create a form that shows details of a selected department:
    1. 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.
    2. 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.
    3. 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.
  8. 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.