Level: Intermediate Bob Swart (drbob@chello.nl), Author, Trainer, Consultant, and Webmaster, Bob Swart Training and Consultancy
20 May 2004 This article shows how to build a Web server application using Kylix 3, exposing the IBM DB2 UDB SAMPLE database on the Web.
Introduction
In this article, I will use Borland® Kylix™ 3 for C++ on Linux to work with IBM® DB2® Universal Database™ (UDB) tables. Kylix 3 produces native Linux executables, and is available for Delphi™ and C++ as a development language.
My previous article, Kylix 3 for C++ and IBM DB2 UDB v8.1 on Linux, used the C++ edition of Borland® Kylix™ 3 to work with IBM® DB2® Universal Database™ (UDB) v8.1 database tables, creating Linux desktop applications. However, Linux is especially renowned for its (Web) server capabilities, so this time I want to take you through the steps to build a Web server application using Kylix 3, exposing the IBM DB2 UDB SAMPLE database on the Web.
Starting with WebSnap
For the example project, you need Kylix 3 as well as DB2 UDB v8.1 installed on a distribution of Linux. I'm using Red Hat 7.2, which works best for my needs. Note that you can download the trial edition of Kylix 3 Enterprise from the Borland Web site.
You may also want to install the Apache Web server, but as I'll show you shortly, this is not absolutely required for your development machine. Kylix 3 includes its own means to allow you to test and debug your Web applications (without Apache).
Start Kylix 3, do File | New - Other, go to the WebSnap page of the Object Repository, and double-click on the WebSnap Application icon. This will produce the New WebSnap Application wizard, shown in Figure 1.
Figure 1. New WebSnap Application
As you can see, you can create CGI stand-alone executables, or more powerful Apache Shared Modules (DSO). As a third option, you can build a Web App Debugger executable, which turns the Web server application into a client for the so-called Web App Debugger - which can be seen as a personal mini-Web server included with Kylix 3. Note that although you need to make a choice now, you can always modify the generated project from one target to another, or even create a project group with multiple targets that all share the same functionality (as explained in more detail in the online help).
CGI, DSO, or Web App Debugger only affects the application "wrapper" around the internal functionality that counts. For now, select a Web App Debugger executable, and give it the name DB2WAD. You should also give the application module a nice page name, like Employees in this case (since I want to list the EMPLOYEE table from the IBM DB2 UDB SAMPLE database).
Before you click on OK to produce the WebSnap application, you should first set some Page Options, so click on that button, which produces the dialog in Figure 2.
Figure 2. Application Module Page Options
The type of producer is set to PageProducer by default, but you should change that to an AdapterPageProducer. This special PageProducer can be used by the special WebSnap components to display the fields (records) as well as actions (navigate, edit, post, etc.) of the IBM DB2 database tables, as you'll see in a moment.
Note that the Login Required option is not checked by default. If you wish to use login capabilities for Linux Web applications, you need to be aware of the fact that this takes additional efforts (described in detail in an article mentioned at the end of this paper in the references section).
Changing the producer type to AdapterPageProducer is the only change required, so click on OK to close the Application Module Page Options dialog, and then on the OK button in the New WebSnap Application dialog in order to produce the actual WebSnap application.
The new project consists of a number of files. First of all, you get an empty form, which is part of the Web App Debugger client (you do not get this form in a CGI or DSO target). You can save this in file WADForm.pas. You also have a Page Module, called Employees, which can be saved in file pmEmployees.pas. The project itself can be saved in WAD.dpr.
Modeling the data
For a Web server application that consists of multiple pages, all sharing the same database tables, it's a good idea to have a central place where the actual data access is concentrated. With Kylix 3, this is done in a data module, and for a Kylix 3 WebSnap project it means adding a special WebSnap Data Module.
Do File | New - Other, go to the WebSnap tab of the Object Repository again, and this time double-click on the WebSnap Data Module icon. This will give you the New WebSnap Data Module dialog, where you only need to click on OK to produce a new WebSnap data module. You can save the new unit in file wDataMod.pas.
You can now add the dbExpress components to connect to the IBM DB2 UDB SAMPLE database. So, place a TSQLConnection component on the new WebSnap Data Module. Right-click on the TSQLConnection component and start the dbExpress Connections Editor. You must configure the connection to the DB2 UDB database here, specifying the correct database name, the UserName, and the Password (unless you want to pass that in code at run-time). Note that the login prompt is not very useful in a Web server application, as the login prompt would be shown on the server, and not on the client machines (resulting in a non-responsive application, which isn't very useful). You can use the Test button (with the checkmark) to verify the connection, as shown in Figure 3 (note that this will still give you the login prompt dialog if the password doesn't match).
Figure 3. dbExpress Connections Editor - Successfully Connected
Once the connection to the DB2 UDB SAMPLE database is verified, you can close the dbExpress Connections Editor. Note that you must now explicitly set the LoginPrompt property of the TSQLConnection component to False.
Now, place a TSQLDataSet component on the WebSnap data module, and connect its SQLConnection property to the TSQLConnection component. The CommandType property of the TSQLDataSet component should be set to ctQuery already, so you can enter an SQL command in the CommandText property, such as:
select * from EMPLOYEE
Note that you can also click on the ellipsis for the CommandText property to display the CommandText Editor, and that can be used to assist in producing the SQL statement (showing the available tables and fields for you). Also note that tablenames are case sensitive - at least on Linux - so be sure to call the table EMPLOYEE and not Employee or employee.
Providing the key
Before you continue, you should now point out which field(s) is (or are) the keyfields for the EMPLOYEE table, so the WebSnap components that follow will be able to identify the means to uniquely search, update, or delete records from this dataset. In order to specify this field, first right-click on the TSQLDataSet component and select the Fields Editor. Then, right-click inside the Fields Editor and select Add All Fields to show all available fields. Now, pick the EMPNO field, go to the Object Inspector and expand the ProviderFlags property. Set the pfInKey property to True, to indicate that the EMPNO field can be considered unique for all records inside the EMPLOYEE table.
Adapting the data
Once you have a TSQLDataSet that sends a SQL SELECT command to the DB2 UDB SAMPLE database, you must prepare it for use in the WebSnap application. This is done with a special component called the TDataSetAdapter, which can be found on the WebSnap tab of the Kylix 3 Component Palette.
Place the TDataSetAdapter component on the WebSnap Data Module, and connect its DataSet property to the TSQLDataSet component. Now, right-click on the TDataSetAdapter component and start the Fields Editor. Adapter Fields correspond to the columns of the dataset, in this case the columns from the select * from EMPLOYEE resultset. Right-click on the Fields Editor and choose Add All Fields, which results in the display in Figure 4.
Figure 4. TDataSetAdapter Fields Editor
You can select individual fields and use the Object Inspector to configure properties like ViewAccess and ModifyAccess (allowing access only to people logged in under a specific name; see the end of this article for some helpful references).
Close the Fields Editor, and right-click on the TDataSetAdapter again to start the Actions Editor. Instead of fields that point to data, the actions point to (dataset) methods. Right-click on the Actions Editor to Add All Actions, with the following results shown in Figure 5.
Figure 5. TDataSetAdapter Actions Editor
Close the Actions Editor. The TDataSetAdapter now contains the adapter fields and actions that map the contents of the EMPLOYEE table from the DB2 UDB SAMPLE database to something that you can use to build Web pages.
Building the overview
As a first example, you'll build an overview of all Employees. This can be done on the first Web page (in pmEmployees), so go to that unit in the Kylix IDE. It already contains a number of WebSnap components, but the one you should focus on now is the TAdapterPageProducer. This is the one you added (in Figure 2), remember?
Before you can continue, you must first make sure that the Employees Page Module knows about the WebSnap Data Module. Press Alt+F11 to get a list of modules, and select the wDataMod unit. Click on OK to add it to the uses clause automatically.
Now, right-click on the TAdapterPageProducer and start the Web Page Editor. This is the visual designer where you can connect the DataSetAdapter's fields and actions to the HTML and script sections that will be generated by the WebSnap TAdapterPageProducer.
The Web Page Editor is divided into three parts. In the upper-right corner, you get a tree of all controls, with the child controls of the selected node in the upper-right corner. The bottom half of the Web Page Editor contains the HTML and Script that will be generated, which should give you a good idea of how the final page will look.
To start designing the Employees overview, right-click on the AdapterPageProducer node in the upper-left corner of the Web Page Editor, and select New Component. This will give you a dialog that lists the new components that you can add. You can do this at any place in the treeview, and you will always only get a list of components that are relevant to add as child nodes for the selected components. Right now, the choice is between an AdapterForm or a LayoutGroup. The latter can be used to control the layout (multiple columns, etc.) but right now you just want to get the job done, so select an AdapterForm and click OK. Select the newly generated AdapterForm node, right-click on it and select New Component again. This time, the choice is between an AdapterCommandGroup, AdapterErrorList, AdapterFieldGroup, AdapterGrid, and - again - the LayoutGroup. Right now, you want to show the records from the EMPLOYEE table in a grid, so select the AdapterGrid and click on OK.
You are almost there, and only need to connect the AdapterGrid to the list of adapter fields from the TDataSetAdapter (on the WebSnap Data Module). Select the AdapterGrid component, and use the Object Inspector to point its Adapter property to WebDataModule1.DataSetAdapter1. This will bind the fields from the TDataSetAdapter to the AdapterGrid, and show all fields automatically.
Apart from the fields, you also want to add a button to the grid, and have that button take you to a detail page that shows more detailed information about the selected EMPLOYEE. In order to do this, you first have to explicitly add all columns to the AdapterGrid. Right-click on the AdapterGrid, and do Add Columns, which gives you a dialog where you can select all columns that you want to display. These columns are based on the available adapter fields, which are based on the fields that are the result of the "select * from EMPLOYEE" query.
Figure 6 shows this dialog, and I've selected the EMPNO, FIRSTNME, LASTNAME, and JOB fields to be used in the AdapterGrid. I do not want to display the other fields, but want to leave them for the detail page instead.
Figure 6. Web Page Editor - Add Columns
Now, close the Add Columns dialog, and right-click on the AdapterGrid again. This time, select the New Component option, which results in a dialog where you can select a new component to add: a choice between an AdapterCommandColumn, AdapterDisplayColumn, and AdapterEditColumn. Select the AdapterCommandColumn, which will be represented by a button (one for each row in the AdapterGrid).
Now, right-click on the AdapterCommandColumn and do Add Commands, so that you can specify which command(s) will be displayed in this column. In the dialog (which lists all available commands), select only the BrowseRow command, since that's the only "neutral" action available.
After you've added the BrowseRow command, select this node in the upper-right area of the Web Page Editor (since the individual fields or actions cannot have any child nodes, they are only listed in the upper-right area). In order for the BrowseRow button to navigate to a details page, you must specify the name of the new page, and put that value in the PageName property of the BrowseRow component. Since the overview page is called Employees, the detail page should be called Employee (without the "s" at the end), so specify Employee as value for the PageName property of the BrowseRow.
Apart from the PageName property, you may also want to change the Caption property, for example to Details. Now, close the Web Page Editor, since the design of the Employees overview is ready.
Although you can compile and run the application at this time, it would be better to add the Employee detail page and view the finished result.
Before you can build the Employee detail page, you must first ensure that the information regarding which Employee record should be shown will be passed along with the Details button as well. This information will be passed "behind the scenes" if you add a TSessionsService component (from the WebSnap tab of the Component Palette) to the Employees Application Module. See Figure 7.
Figure 7. SessionsService
Showing the details
In order to show the details, you must now add a page module called Employee. Do File | New, Other. Go to the WebSnap tab of the Object Repository again, and double-click on the WebSnap Page Module icon. This will give the New WebSnap Page Module dialog shown in Figure 8, where you need to specify the producer type (change from regular PageProducer to AdapterPageProducer), as well as the name: make sure it's set to Employee.
Note the Published checkbox, which is checked by default. You should consider unchecking that, since it will prevent the details page from being displayed (and you only want to make it available as a result from using the Details button in the AdapterGrid).
Figure 8. New WebSnap Page Module
Click on OK to produce the new WebSnap Page Module, and save it in pmEmployee.pas. Press Alt+F11 and add the wDataMod unit to the uses clause of this Page Module as well.
Now, right-click on the AdapterPageProducer on this detail Page Module, and start the Web Page Editor again. This time, you want to produce a detail view of the EMPLOYEE record from the DB2 UDB SAMPLE database, so you don't need the AdapterGrid. Instead, you first need to add an AdapterForm to the AdapterPageProducer, and on the AdapterForm you need to add an AdapterCommandGroup as well as an AdapterFieldGroup. The former will show the actions (navigation, edit, etc.) while the latter will show the actual fields of the selected record.
You need to point the DisplayComponent property of the AdapterCommandGroup to the AdapterFieldGroup (so the actions know on which set of fields they need to operate), and the Adapter property of the AdapterFieldGroup to the WebDataModule1.DataSetAdapter1. If you wish, you can right-click on the AdapterCommandGroup or the AdapterFieldGroup to limit the number of Buttons (related to actions) or Text fields (related to fields) that will be shown in the browser. By default, all actions and fields will be displayed.
Testing and debugging
It's now time to compile and run the application. The Web App Debugger client will run as a regular desktop application, showing the empty form. In order to actually "connect" to it, you also need to run the Web App Debugger itself, available from the Tools menu. In the Web App Debugger dialog, you can click on the Start button to make it "listen" to the specified port (for example, 8081), as shown in Figure 9.
Figure 9. Kylix 3 Web App Debugger
With the Web App Debugger running, you can connect to the example application WAD with Web App Debugger module DB2WAD (see Figure 1 again) as http://localhost:8081/WAD.DB2WAD (as shown in Figure 10).
Figure 10. DB2 Web Server App on Linux
The localhost needs to be replaced with the server name or exact IP address if you connect from a different machine. As a test, I've connected to this Kylix 3 WebSnap application from a Windows 2000 machine using Internet Explorer, which can be seen in Figure 11.
Figure 11. IE6 on Windows 2000
When clicking on a Details button for Eva Pulaski, for example, you go to that particular details page (shown in Figure 12). You can use the Command and Navigation buttons here to operate on the record and navigate through the dataset.
Figure 12. Employee Details Page
Obviously, if you do not want to allow people to Delete or Edit the detail records, you can remove the Command button from the Web Page Editor, or remove the actions from the DataSetAdapter in the WebSnap Data Module.
This example project has shown the way to connect to and expose the data from the EMPLOYEE table in the DB2 UDB SAMPLE database as a Web server application. I leave further customization as an exercise for you.
Summary
In this article, you have seen what it takes to build a Web server application using Kylix 3, exposing the IBM DB2 UDB SAMPLE database on the Web. With WebSnap, you can map the data fields from the IBM DB2 UDB database tables to adapter fields that are displayed as static HTML text, and the IBM DB2 database operations to adapter commands that are displayed as command buttons. Note that you didn't have to write any code, so you could have used both the Delphi and the C++ edition of Kylix 3 to build the application.
Apart from visual Web server applications, you can also use Kylix 3 to build non-visual Web service "engine" applications that use DB2 as the underlying DBMS, exposing data and functionality as SOAP objects. This is the objective of my next article, when I will use Kylix 3 to expose the IBM DB2 UDB SAMPLE database tables as a SOAP Web Service on Linux.
Download | Name | Size | Download method |
|---|
| source.zip | 7 KB | FTP |HTTP |
Resources
About the author | | |
Bob Swart (aka Dr.Bob - www.drbob42.com) is an author, trainer, consultant and Webmaster working for his own company, called Bob Swart Training & Consultancy (eBob42), in Helmond, The Netherlands. Bob, who writes his own Delphi training material, has spoken at Delphi and Borland Developer Conferences since 1993. Bob has written hundreds of articles, and is co-author of the Revolutionary Guide to Delphi 2, Delphi 4 Unleashed, C++Builder 4 Unleashed, C++Builder 5 Developer's Guide, Kylix Developer's Guide, Delphi 6 Developer's Guide, and the C++Builder 6 Developer's Guide. |
Rate this page
| 
