ReportBuilder

Server Edition

Developer’sGuide
Second Edition
Server Edition
Developer's Guide
Copyright © 2002 - 2007 by Digital Metaphors Corporation
 i

CONTENTS
SERVER FUNDAMENTALS
Report Application vs. Report Server Application ..............................................3
Socket To Me .....................................................................................................5
Building a Report Server Application .................................................................7
Talking To The Server From A Thin Client ........................................................9
Registering Reports With The Server ..............................................................11
Spelunking With The Report Explorer .............................................................15
Publishing Reports to the Web ........................................................................17
Making Web Browser Content Printable With PDF .........................................19
Troubleshooting the WebTier ..........................................................................21
FAQ .................................................................................................................23

TUTORIALS
Building a Report Server Application for Reports on Forms
Overview ..........................................................................................................29
Copy Existing Report Application to a New Directory ......................................29
Convert the Application to a Server .................................................................30
Register the Reports On the Server ................................................................30
Make the Data Access Components Thread-Safe ..........................................30
Run the Server Application ..............................................................................31
Create a Thin-Client Application ......................................................................31
Building a Report Server Application for Reports in Files
Overview ..........................................................................................................33
Copy Existing Report Application to a New Directory ......................................33
Create a Thread-Safe Data Module .................................................................34
Register the File-Based Reports ......................................................................34
Move the Report Event Handlers to the Data Module .....................................34
Convert the Application to a Server .................................................................35
Run the Server Application ..............................................................................35
Create a Thin-Client Application ......................................................................36

Building a Report Server Application for Reports in a Database

Overview ..........................................................................................................37
Copy Existing Report Application to a New Directory ......................................37
Update the Path of the Database Component .................................................37
Create a Thread-Safe Data Module .................................................................38
Register the Databased Reports .....................................................................38
Move the Report Event Handlers to the Data Module .....................................38
Convert the Application to a Server .................................................................39
Run the Server Application ..............................................................................39
Create a Thin-Client Application ......................................................................40
ii

Building a Report Server Application for an Explorer Database

Overview ..........................................................................................................41
Copy Existing Report Application to a New Directory ......................................41
Create a Thread-Safe Data Module .................................................................42
Register the Databased Reports .....................................................................42
Convert the Application to a Server .................................................................43
Run the Server Application ..............................................................................43
Create a Thin-Client Application ......................................................................43

Building a Report Server Application for Report Archives

Overview ..........................................................................................................45
Copy Existing Report Application to a New Directory ......................................45
Register the Report Archives ...........................................................................46
Convert the Application to a Server .................................................................46
Run the Server Application ..............................................................................46
Create a Thin-Client Application ......................................................................47
Run a Report Server Application from a Windows Service
Overview ..........................................................................................................49
Install the Windows Service .............................................................................49
Create a Service Compatible Report Server Application .................................50
Update the File Directory of the Report Volume ..............................................50
Designate the Report Server Application from the Windows Service ..............50
Run the Thin-Client Application .......................................................................50

Publish Reports to the Web

Overview ..........................................................................................................53
Create a Directory for the Web Tier .................................................................53
Create a Virtual Directory on IIS ......................................................................54
Create an ISAPI DLL .......................................................................................54
Add a Default Action to the ..............................................................................55
WebModule ......................................................................................................55

Scaling the Web Tier with a Server Farm

Overview ..........................................................................................................57
Create a Report Server Application .................................................................57
Copy the Report Server Application to a Network Folder ................................57
Deploy the Report Server Application ..............................................................58
Check Each Server via Thin Client ..................................................................58
Configure a Web Tier Using Round Robin ......................................................59
Test via Web Browser ......................................................................................59
Configure a Web Tier Using Minimum Load ....................................................60
SERVER FUNDAMENTALS

Report Application vs. Report Server Application 3

Socket To Me 5
Building A Report Server Application 7
Talking To The Server From A Thin Client 9
Registering Reports With The Server 11
Spelunking With The Report Explorer 15
Publishing Reports To The Web 17
Making Web Browser Content Printable With PDF 19
Troubleshooting the WebTier 21
FAQ 23
 Report Application vs. Report Server Application
SERVER FUNDAMENTALS 3
Report Application vs. Report Server Application
ReportBuilder Server Edition makes it easy to cre- The diagram below depicts a typical report applica-
ate a report server application. A report server tion. When the Preview Form is displayed, the first
application is quite different from a standard Del- page of the report is requested by the Screen
phi report application. The key differences are: Device via a call to the RequestPage method. The
report object checks a cache for the requested page,
1 The server application must be able to commu-
and if the page cannot be found, passes the request
nicate across the network in order to satisfy the
along to the report engine. The report engine
requests of client applications. In a traditional
attempts to generate the requested page, and then
application, objects may pass freely through the
triggers an OnSendPage event, which returns the
system, with “communication” taking the form of
page to the report. The report then calls the
method calls. In a server application, objects or
ReceivePage method of the Screen Device, causing
data must be converted to a network compatible
the page to be displayed. Notice that all of the
format, sent across the network to the client and
objects exist in the same memory space: method
then converted back to objects or data by the client.
calls and events are used to pass information from
2 The server application must be able to run each object to object.
report within the context of a thread. This means
that the data access components and the report
components must be thread-safe: that is, multiple
instances of these objects must be able to co-exist
and run “side-by-side”, without any conflicts
created by the use of shared resources. This is not a
requirement for a standard reporting application,
which usually generates reports one at a time.
 Report Application vs. Report Server Application
4 SERVER FUNDAMENTALS

In ReportBuilder Server Edition, this application is Any objects which were passed freely between
divided into two parts: client and server. The server these two areas in the standard reporting applica-
portion of the application will contain the data tion will now be passed across the network.
access components and the reports. The client por-
tion of the application will contain the Preview
Form and any devices necessary to process the
pages.

Obviously the complexity of this reporting solution The Server Edition makes this conversation happen
is much greater than the complexity of the standard via a technology known as sockets (depicted in the
application; two applications must communicate in diagram below); a topic we discuss briefly in the
order for this solution to function effectively. next section.
 Socket To Me
SERVER FUNDAMENTALS 5
The nature of this conversation is as follows:
Socket To Me
In the Server Edition communication between the
server and client application occurs via sockets. A
low level feature of the Windows operating sys-
tem, sockets were invented by the team which
modified Unix in order to create the early internet. Sockets give us an excellent pipeline for bytes –
To function properly, sockets require a machine but objects are hardly bytes. Before we can send an
address (IP address like 192.168.1.120) and a port object over the wire, we must convert it to a
(number between 1 – 65535.) Given these values, stream. This is done using a customized version of
two-way communication can be established Delphi streaming. Once an object has been con-
between applications. verted to a stream, it is compressed, converted to
alphanumeric characters (Base64), wrapped in the
When creating a report server application, the Port
body of a SOAP message and sent, piece-by-piece
property of the rsServer component is used to
through the socket to the client. The client reas-
establish the port to which the application will “lis-
sembles the stream, extracts the element from the
ten” when communicating with clients. Of course,
SOAP message and then uses the same customized
you should avoid port numbers which conflict with
Delphi streaming logic to instantiate an exact rep-
other applications that may be running on the
lica of the original object. When the client needs to
server machine.
send a message to the server, the same sequence
Ports for typical services appear in the table below. occurs in the opposite direction.

ftp 21
telnet 23
smtp 25
http 80
pop3 110
nntp 119

The machine address (IP address) is not set on the

server component, because the address used for the
socket is always the address of the machine on
which the server application is running.

The client application is in a rather different situa-

tion. It must specify both the machine address and
the port for the server to which it will connect.
These values are set on the ServerConnection prop-
erty of the rsClientReport component. The
machine address can either be a set of four num-
bers, or a valid DNS name (i.e. www.mycom-
pany.com) Armed with these two values, the client
application can initiate a conversation with the
server.
 Building a Report Server Application
SERVER FUNDAMENTALS 7
Building a Report Server Application
Our basic goal is to create a Delphi application that Actually the server will respond with something a
will respond from the host machine on a certain little more concise than that, it will say: “No vol-
port. Any application which wishes to talk to the umes exist.” In the context of the Server Edition, a
report server, must know the IP address of the volume is a collection of reports in the Report Cat-
server machine and the port of the server applica- alog. Volumes are the natural consequence of reg-
tion. Armed with these two pieces of information, a istering reports with the server – they are
client can begin a conversation with the server. ReportBuilder’s way of attaching a name and an
access mechanism to a group of reports.
In the Server Edition, we specify the port in the
Server component. This non-visual component So let’s create a volume. Assume we’ve got a
serves as the heart of the application. The most report component on a Delphi form. All of the data
important setting is the Port property, and we will access components for the report are on the form as
accept the default value: 1333. This value was well. We add this form to our Report Server
chosen as the default because it does not conflict project, open it and place the following code at the
with any of the port values used by common oper- bottom of the unit:
ating system software. initialization
TrsReportCatalog.RegisterReport(‘Accounting’,
The screen shot below shows a TrsServer compo- ‘By Quarter’,
nent on a Delphi form. In order to get the server ‘rptByQuarter’,
frmByQuarter);
running, we have added a “Power” button to the end;
form. When we run the application and click the
The first parameter is the volume name, the second
button, the following code fires:
is the report alias (the name the user will see from
rsServer1.Active := spbPower.Down; the client), the third is the name of the actual report
component (i.e. the value of the TCompo-
nent.Name property) and the fourth is the name of
the form. When the application runs, this initializa-
tion section will register the report with the server.

Now, we’ve almost got enough here to serve this

report, but we need two more things. This form is
perfectly good for running a report in a Delphi
application. But in the context of the server, this
form will actually be running within a thread. The
BDE-based data access components on our form
Once the server is active, it will begin listening for will not like this; they will blow unless we add a
requests. At this point the server does not have TDatabase object – specifying where the database
access to any reports and so can’t do much except is located and a TSession object.
respond with “I got nuthin’.”
 Building a Report Server Application
8 SERVER FUNDAMENTALS

The AutoSessionName property of the session

must be set to True, so that when this form is
instantiated, the session will be uniquely named
within the context of the entire application. With
these two details out of the way, we are now ready
to serve the report. We run the application and
click the “Power” button. Great, now, how do we
tell if the server is actually working? The answer:
create a thin-client application.
 Talking To The Server From A Thin Client
SERVER FUNDAMENTALS 9
Talking To The Server From A Thin Client
The easiest way to verify that our server is actually Password we can ignore, since we have not imple-
serving this report is to create a thin-client applica- mented a security scheme on the server. Port has
tion. To do that, we’ll need to create a new applica- defaulted to the correct value: 1333 and Timeout is
tion and add a TrsClientReport component to it. set to 60 seconds. Timeout refers to the amount of
The ClientReport component allows us to work time the client will wait for a server response
with a given report as if it were actually inside the before giving up on the request and displaying an
client application. We can use it to “load” reports – error message.
though this process is slightly different from the
The next thing we need to add is a button. To dis-
LoadFromFile or LoadFromDatabase techniques
play the report in the OnClick event, we’ll code
you are used to, and we can use it to preview
this:
reports as well. The ClientReport component has a
lot of network communication stuff crammed rsClientReport.VolumeName := ‘Accounting’;
rsClientReport.ReportName := ‘By Quarter’;
inside of it - but we can mostly ignore that and get rsClientReport.Print;

our app working by configuring the ServerConnec- We know this report exists on the server and so we
tion and then setting the VolumeName and Report- just hard-code the values. When the Print method
Name properties at run-time. is called, the ClientReport component will commu-
nicate with the server, asking for the first page of
the report named “By Quarter” in the “Account-
ing” volume. Using the information we supplied in
the RegisterReport call, the server will instantiate
an instance of our report form and run the report.

Once the first page is generated, the report server

will send it across the wire to ClientReport, where
it will then be displayed in the standard Print Pre-
view form. There is, of course, a lot going on
behind the scenes to make all of this possible, but
that is the gist of it.

So, we’ve got a form based report running across

the wire. That’s great and all, but it’s also pretty
limited. We don’t want to be recompiling and re-
deploying our server application every time we
want to add or change a report. Realistically we
If we expand the ServerConnection property in the need to consider other report configurations:
Object Inspector, we can see several properties reports located in template files, reports saved in
embedded within it. Address refers to the location end-user database tables and reports in archive
of the server: the IP address. Since we are running files. How do we serve these types of reports?
the server application on the same machine as the
client, the default (localhost) will do nicely.
 Registering Reports With The Server
SERVER FUNDAMENTALS 11
Registering Reports With The Server
Registering Report Templates
If you’ve ever worked with report template files, You can certainly view these two alternatives from
then you probably know that there are some impor- the perspective of portability, where the first is the
tant caveats to consider, the first and foremost of maximum portability and the second is the mini-
which is: where are the data access components mum (actually form-based reports should probably
going to reside? Without data access components be considered the minimum, since they are
most reports will not run. Second, where are the “locked” into the executable.) Either way, the
event handlers going to reside? Delphi event han- report server needs to successfully load the tem-
dlers exist within the executable, and any template plate and run the report. To make sure that hap-
which uses them must be loaded in a way that pens, we need to use a ReportTemplateVolume
allows the events to successfully reconnect. Each component, which let’s us specify an operating
of these issues has two basic resolutions: system directory where template files reside. And
we need to place that volume in a Delphi form or
1 When creating the report, use the Data tab
data module which provides a complete, functional
(DADE) and the Calc tab (RAP) to configure the
“habitat” in which the report can generate. If you
data access components and create the event han-
have a functioning report application, then you
dlers.
already have such a habitat somewhere in your app
With this approach the data access components and – but it usually makes sense to break this out as a
the event handlers are saved in the report, provid- separate data module, so that the server does not
ing maximum portability. However, even this con- have to include your entire application. Let’s create
figuration requires a database connection and RAP a typical habitat for set of highly portable (i.e.
pass-thru function availability. DADE and RAP based) report templates.
2 When creating the report, use standard Delphi The first thing we do is open the Server application
data access components and Object Pascal event and add a new data module to it. Make sure the
handlers. data module is auto-created. We create a Report-
TemplateVolume component and set the FileDirec-
Here the entire supporting cast is stored in a Delphi
tory property to the location of our templates. At
form or data module, with the report connected to
this point we can run the server and any templates
them. In order to successfully load such a template,
which appear in the directory will be accessible
we must make sure that the Delphi form or data
from the client app. The problem is, they will not
module is the owner of the report component used
run, because we have not provided a database con-
for the loading process (or at least the data module
nection. Assuming the reports are BDE based, we
is instantiated and “used by” the form or data mod-
add a TDatabase component and TSession compo-
ule containing the report.)
nent to the form. We set the AutoSessionName
property of the TSession to True, so the session
name will remain unique, even in a multi-threaded
environment.
 Registering Reports With The Server
12 SERVER FUNDAMENTALS

Next we add the name of the unit containing the As you can see, there is not much to serving report
DADE plug-in used for these reports to the uses archives, it’s by far the easiest way to get a server
clause of our data module (in this case, up and running. Archives are the best way to serve
daDBBDE.) We compile the Report Server appli- reports when lots of users want to access the same
cation and run. The reports should now function report and interactive search criteria (where the
properly from the client. user enters the search criteria) are not needed.

That is, unless some of them call RAP pass-thru Registering End-User Reports
functions. If this is the case, we need to add the unit The end-user solution provided by ReportBuilder
containing the pass-thru functions to our applica- organizes reports in a folder tree structure. This
tion. If the functions are registered in the initializa- structure is stored in two database tables: a folder
tion section of their unit (which is usually the case) table and an item table. Almost all items are reports
then we are done. Recompile and run. (though some may be exported data modules or
You’ll notice that registering reports is more about code modules.) The trick, of course, is how to
creating a habitat conducive to report generation, serve this more complex structure. It’s not simply a
than it is about understanding the ins and outs of directory with templates or archives in it. This
the volume components. The volume components problem is so fundamental, that the concept of
are actually quite simple, representing little more folders became “the way” to model all volumes.
than a location (and the associated access mecha- Both the TemplateVolume and ArchiveVolume
nism) for a given set of reports. No volume illus- can handle subfolders, and automatically display
trates this more clearly than the subfolders when they are configured. The end-user
ReportArchiveVolume. folder structure can be served via the ReportEx-
plorerVolume. The name refers to the Report
Registering Report Archives Explorer, which normally displays the folders and
Report Archives are reports which have been gen- items in an end-user application. The same config-
erated and saved to a file or to a database BLOB uration conditions apply to end-user reports as to
field. Because the generation cycle is complete, no any template based reports: a database connection
database objects are needed when previewing the is needed, any RAP pass-thru functions which have
reports. This greatly simplifies the task of serving been used in the reports are needed, and the unit
report archives. Assuming we have a system direc- name for the DADE plug-in must be included in
tory stocked with report archive files, we can regis- the uses clause. So let’s configure a
ter these by creating a new data module in the ReportExplorerVolume and see just how easy (or
Server Application, adding a ReportArchiveVol- difficult) it is.
ume and setting the FileDirectory property. Once
First, we open the Server Application and add a
we compile and run these reports will be available
new data module to the project. We place a
from the client app. Also, any archive files we add
ReportExplorerVolume in it. Then we open the
to this directory will appear on the client the next
main form containing our end-user solution. From
time the client takes a fresh look at the given vol-
this we copy the data access components for the
ume. In other words the directory is now “hot”,
folder and item tables.
and anything we add to it will be served to clients.
 Registering Reports With The Server
SERVER FUNDAMENTALS 13
We paste these into the data module. Next we add
database connection objects: for this example we
need a TDatabase and a TSession object. We set
the TSession.AutoSessionName property to True
so that it is thread-safe. We add the unit name for
the DADE plug-in to the uses clause (in this case
daDBBDE) and that’s it. We’re ready to go. The
steps necessary to configure the database connec-
tion for any given database (and database connec-
tivity product) will vary. See the examples in
RBServer\Demos\Explorer Databases for an exam-
ple of your database/data connectivity product.
 Spelunking With The Report Explorer
SERVER FUNDAMENTALS 15
Spelunking With The Report Explorer
We have created quite a collection of reports on the The screen-shot below shows what happens when
server with all of this registration activity. We have we run this application and click the Launch but-
a report on a form, a set of reports in an operating ton. It’s the same old Report Explorer from the
system directory, a set of report archives in an end-user application, only this explorer is running
operating system directory and a set of reports in across the wire, and is displaying reports from a lot
an end-user database. While the report catalog and more sources than just the end-user database
volume naming scheme ensures that we do not tables.
have a report name collision on the server, things
are about as clear as mud on the client side. There
are far too many reports to use the simplistic hard-
coding technique we used earlier. Further, giving a
simple report name will not be sufficient for the
end-user reports – we need a way to specify folder
names too. Fortunately, there is a component
which will give us a nice “bird’s eye view” of all
reports on the server, without forcing us to hard-
code anything: the ClientReportExplorer.

A full-blown Report Explorer may be more than

you really need. If this is the case then rest assured
that the classes used by the Report Explorer to
query the server, discover volumes, folders and
reports are fully available to you. If you need to
implement a custom UI in your thin client app,
check out the TrsClientReportCatalog class for an
easy way to get started.

Let’s modify the thin-client application we created

earlier by adding a ClientReportExplorer compo-
nent to it. This component does not contain a Serv-
erConnection object, but instead relies on a
ClientReport to do its connecting. That means we
simply assign the ClientReport property and away
we go. The ClientReportExplorer works much like
a Delphi System Dialog component; you call the
Execute method and a dialog is displayed. Let’s
code a Launch button:

rsClientReportExplorer1.Execute;
 Publishing Reports to the Web
SERVER FUNDAMENTALS 17
Publishing Reports to the Web
The Server Edition has a special component, called The WebCachePath is the URI to the cache direc-
the WebTier, which converts the information pro- tory. We will create a virtual directory on the
vided by the server into an HTML/JavaScript server which maps to the CacheDirectory on the
application. Let’s configure a web tier and get a PC. The virtual directory describes a path which
feel for how it works. We’ll assume that our web will be accessible from a web browser (i.e. you can
tier will reside on a PC running IIS, and that we type it as an address in a web browser and the
will deploy the web application as an ISAPI DLL. server will return the content of the directory.)

First we create a new Web Server application from The WebModuleURI is an HTTP address which
within Delphi. To do this, select File | New | describes the exact location of the web tier on the
Other... and then select Web Server Application. server. This is the address you type into the
This will create a WebModule, which is a special browser to invoke the web tier.
kind of data module that knows how to talk to an
Next we need to process the requests received from
IIS web server. In the web module we place a
web browsers. To do this, we need to hook the
WebTier component.
Web Module to the Web Tier:

1 Right-click over the Web Module and select

“Action Editor.”

2 Add an action to the list.

3 Use the Object Inspector set the Default prop-

erty of the Action to True.

4 Code the OnAction event of the Action as:

Response.Content := rsWebTier1.ProcessWebRequest(
Request.QueryFields,
Request.Content);

Assuming the web server is running on the same The web tier handles all possible requests through
machine as the report server application, we set the the method: ProcessWebRequest, and so we pass
following three property values: http requests straight through to the web tier, which
in turn provides the appropriate response. For more
CacheDirectory C:\myWebTier\Cache\
ServerConnection {use the default values}
on Web Modules and Actions, see the Delphi help.
WebCachePath http://localhost/myWebTier/Cache/
WebModuleURI http://localhost/myWebTier/myWebTier.dll We can now compile myWebTier and copy the
resulting DLL to C:\myWebTier. That’s all there is
The CacheDirectory names the system directory
to it!
where the WebTier will store the output generated
for a given session (folder/tree structures, page
object files, and images.)
 Publishing Reports to the Web
18 SERVER FUNDAMENTALS

We may be done generating the DLL, but IIS isn’t If we’ve configured everything properly, you
yet configured to use it. We need to create a virtual should see the HTML version of the report
directory, so that IIS can make our new DLL avail- explorer in your web browser. Click on a report
able from a web browser. To do this: and the HTML version of the report viewer should
be displayed.
1 Select Start | Control Panel and double-click
Administrative Tools.

2 Double-click Internet Information Services (if

you can’t find this icon, you probably do not have
IIS installed. Double-click Add/Remove Programs
and then click Add/Remove Windows Components
– from there you can install IIS.)

3 Expand the “Local Computer” entry and find

the Default Web Site entry under Web Sites.

4 Right-click over Default Web Site and select

New | Virtual Directory. The Virtual Directory
Creation Wizard will be displayed.

5 Enter an alias of “myWebTier.”

6 Click Finish, find the new virtual directory and

select it.

7 Right-click over the virtual directory and select

Properties.

8 Locate the Application Settings section at the

bottom of the first tab.

9 Set Application Protection to High (Isolated)

(This will keep the web tier from crashing the web
server and other ISAPI DLLs from crashing the
web tier.)

10 Click OK to exit the dialog.

11 Close the Internet Information Services and

Administrative Tools windows.

We’re now ready to test the web tier! Launch your

web browser and enter the following address:

http://localhost/myWebTier/myWebTier.dll
 Making Web Browser Content Printable With PDF
SERVER FUNDAMENTALS 19
Making Web Browser Content Printable With PDF
If you’re previewing a report in the browser, how
do you print it? Well, we can certainly right-click
over the frame which contains the page, select
Print and we will get “something.” But honestly,
HTML just doesn’t print very well. To get the
high-quality output we normally expect from
ReportBuilder, we’ll need to harness yet another
“web technology,” PDF and the Acrobat Reader.

ReportBuilder Server Edition includes web adap-

ater classes that enable the WebTier to use Report-
Builder's built-in PDF device as well as third-party
add-ons available from Gnostice, Pragnaan, and
Waler. (Note that the third-party web adapters
require that you have the relevant product
installed.)

To add PDF support to your web application, add

the appropriate unit reference to the uses clause of
your web module

PDF Device Web Adapter Unit

ReportBuilder rsWebAdapaterPDF

Gnostice rsWebAdapaterPDFGnostice
Pragnaan rsWebAdapaterPDFPragnaan

Waler rsWebAdapaterPDFWaler

After you have done this, recompile the project and

copy the resulting web tier DLL to the virtual
directory. Test the new DLL from your web
browser. You should now see a printer icon on the
far left of the report viewer. Clicking on this icon
launches a separate browser window with the
entire report in PDF format (of course the Adobe
Acrobat Reader plug-in must be installed in order
to view the report.)
 Troubleshooting the WebTier
SERVER FUNDAMENTALS 21
Troubleshooting the WebTier Where’s my print button?
To use ReportBuilder's built-in PDF support, add
I receive the message “Unable to connect to
rsWebAdapterPDF to the uses clause of the web
server.”
Either the server was not started successfully or the module. To use a PDF add-on product from Gnos-
server has crashed. In the latter case, if the server is tice, Pragnaan, or Waler, first install the add-on
not being deployed as a Windows service it will product and then add rsWebAdapterPDFGnostice,
have to be manually restarted. rsWebAdapterPDFPragnaan, or rsWebAdapterPD-
FWaler to the uses clause of the web module.

I receive the compile error “Could not create

output file C:\Inetpub\wwwroot\rbbin\ I have to wait a really long time to see my
Report.dll” when trying to build the web tier report.
project. There are a number of reasons this could be hap-
Most likely the Report.dll has been loaded by IIS. pening. The first and foremost is that the requested
Access the IIS manager, right click on the virtual report is very complex. That is it either has a query
directory where Report.dll resides, select Proper- that takes a long time to execute or the report has
ties and click Unload. If that fails, restart the web numerous calculations and takes a long time to pro-
server. cess. There are numerous ways to improve the exe-
cution of the report itself which will not be
discussed in this article. There are, however, a
I have LogSettings.EnableLogging set to true on
the web tier but the log file is not being gener- number of options which you could control on the
ated. web tier to help improve performance. Setting the
Make sure that the user account which is being viewer to incremental mode (ViewerSettings.Incre-
used to execute the web tier has permission to write mental Mode) and setting garbage collection to run
to the directory specified by LogSettings.Location. in a separate thread (GargabeCollection.Sepa-
The default user account used by IIS is rateThread) could potentially reduce the latency
IWAM_Machinename. time for receiving the first page of the report.

When I try to bring up the report explorer the

browser cannot load the frames.
There are a few reasons this could be happening.
First, check that the WebCachePath property on
the web tier has been set correctly (should have
machine IP address instead of “localhost”.) Sec-
ond, check if the desired path is set up correctly in
the web server. Third, make sure that the cache
directory is set up for web access. This is usually
done by adding the “Internet Guest Account
(IUSR_MachineName)” account to the access list
for the cache directory.
 Troubleshooting the WebTier
22 SERVER FUNDAMENTALS

The text in the outline is all garbled. In the WebTier Cache directory, none of the
This is simply due to how your browser wraps text. sessions are ever deleted.
Resizing the outline frame should fix the problem. Session folders should be deleted when the session
timeout (WebTier.SessionOptions.SessionTime-
out) is exceeded (i.e. no activity for the session has
When I execute a new report, some of my old
reports are wiped from the cache. occurred in the last five minutes.) However, the
The web tier has a setting which determines the WebTier.dll must have read/write access to the
maximum number of reports which could be cache directory. The WebTier.dll runs under the
present in the cache simultaneously per session account IWAM_<MachineName>. Right-click
(SessionOptions.MaxReportCount). When the over the cache directory, access Properties... and
specified number of reports in the cache has been click the Security tab. Select IWAM_<Machine-
reached, the next incoming request from the same User> and give this user Full Control.
session will cause the least recently viewed report
be wiped from cache.

After having run a report once my data has

changed, but when I return to my report from
the report explorer I see the same old report.
How can I see the new data?
The web tier caches report data to avoid having to
rerun the report and give you better performance.
To force a report to be regenerated click the
Refresh button on the navigation toolbar.

I receive a message telling me that logging has

been disabled. What does this mean?
This is a non-critical error which means that log-
ging has been enabled on the web tier but the web
tier was not able to successfully log its activity in
the specified location. You can continue working
normally but the error will recur every time the
web tier is reloaded. The most likely cause of this
problem is that the directory specified for the web
log either does not exist or the web tier does not
have permission to write to it.
 FAQ
SERVER FUNDAMENTALS 23
FAQ How many users can practically be served at
once?
Do I have to change all of my reports to get
It depends. A report based on a simple query,
them to work on the server?
which retrieves few records and generates few
No. But you do have to provide thread-safe con-
pages can be run by many users at once. A report
tainers for the database connection components
which utilizes multiple complex queries, pulls mil-
needed by your reports. That may sound scary, but
lions of records and generates tens of thousands of
it’s really no big deal.
pages may be all the server can handle at any one
The documentation for the Server Edition will
time. The best way to determine the answer to this
include directions for creating thread-safe contain-
question is to create a report server with your
ers for all of the popular database/connectivity
reports and see how it goes. You have lots of
product combinations. These containers can be
options regarding live report vs. archive report, full
Delphi data modules or invisible forms and should
generation vs. incremental generation and caching
be configured with the appropriate Volume compo-
configuration options on both the report server and
nents or direct registration calls. Through the regis-
the web tier. There is also multiple CPU and multi-
tration process you associate containers with
ple server configurations to consider.
reports so that the reports can successfully connect
to a database when loaded. Report related event-
handler code must also be thread-safe. However, How fast is the server?
unless you are referencing global objects or Just as fast as ReportBuilder, but certainly no
resources that exist outside the context of the con- faster. Remember that directory structures (folder
tainer form or datamodule, then the code is proba- trees), search criteria, and page objects must be
bly thread-safe as is. sent across the wire to the client. This takes addi-
tional time. Yes, the messages are compressed.
Yes, multi-threading means that the messages will
How hard is it to get the server up and running?
be processed in a timely fashion. But there are
It is very easy. The Server component encapsulates
many, many factors which control the performance
all of the functionality required to communicate
any given user may experience. The best bet is to
with clients and execute reports on their behalf.
test the server using your reports and your client
Your primary task will be registering your reports
application.
with the server’s report catalog. If the reports are
deployed as components on Delphi forms or in data
modules, this requires a simple registration call to How do I stop a “runaway report” on the
the report catalog. If the reports are deployed as server?
report templates, as report archives, or as report The Volume.PublishingOptions can be used to
templates in the end-user database structure it is specify the maximum number of pages and maxi-
even simpler. You can connect one of the Volume mum number of seconds for report execution.
components to the file directory structure or the These values can be used as the defaults for all
database tables and it will dynamically generate reports in the volume. The Volume.OnGetPublish-
catalog items for all of the reports residing in the ingOptions event can be used to dynamically set
structure. Using this latter scheme you can add and the publishing options for individual reports.
remove reports without bringing the server down.
 FAQ
24 SERVER FUNDAMENTALS

Proper use of the Volume.PublishingOptions Can I hot-swap reports running on the server?
should prevent runaway reports. However, in the Yes. The Report Server can dynamically discover
event of a runaway report, you will need to stop the the existence of new folders, reports, and archives.
service or (if you are running the server in stand- Thus you can add or replace reports and archives
alone mode) shut down the server application. A that are stored in files or a database. Of course
future version of the Server Edition may contain an changing reports which are compiled directly into
administrative application where you can stop indi- the server application requires that the server be
vidual sessions – but for now we are focused on stopped and replaced with a new executable con-
solidifying a fast, stable and scalable core. taining the new reports. That is why the Templat-
eVolume, ArchiveVolume, and ExplorerVolume
components are preferred - they specify a location
What happens if the server crashes?
where reports are stored.
When configured correctly, the server will simply
clean up after itself and automatically restart. This
is why you should deploy your server application Can I administer the server remotely?
using the Windows Service scheme. Under this Yes, using Windows remote desktop or a product
scheme if the server crashes, the Windows Service such as PCAnyWhere, you can run the RB Ser-
can automatically restart the application. The vices Manager. The RB Services Manager is avail-
server application is running in its own process able from the Start Menu, under ReportBuilder |
space – which means that other applications on the Services Manager. It is a system tray based appli-
same machine should not be affected if the server cation which allows you to start/stop the report
crashes. For reasons of both performance and sta- server or change the location of the server app (if
bility, you should also run your web tier as an Iso- you need to move the app to a different directory.)
lated Process. This keeps other ISAPI DLLs on The RB Services Manager is available only when
your web server from crashing your web tier and the server is deployed as a Windows Service.
vice versa. Of course, when a crash does occur, the
exception will be logged – so you should be able to
isolate the report causing the problem.

Does the server do any kind of logging?

Yes. Both the report server application and the web
tier will automatically log any exceptions (unless
logging is turned off.) The web tier also has a “ver-
bose” mode where it logs every request, every
response, every run of the garbage collector and
every exception. By default this verbose mode is
turned off, because logging adversely affects per-
formance. The log format can be set to ASCII text
or XML.
 FAQ
SERVER FUNDAMENTALS 25
How is printing handled from the web browser? Can Server run on Linux?
The Web Report Previewer includes a Print button No. While the report engine inside the server appli-
on the toolbar. Pressing the Print button generates a cation is functioning without a user-interface,
PDF that is opened on the user's machine by Adobe many dependencies on the Windows Operating
Acrobat Reader. System (and the associated API) still exist. We
consider a Linux server to be a mammoth under-
taking and are not committing to such a project at
Does the server support https?
this time.
Yes. Not only can you secure the web tier so that it
is only accessible via https, you can configure RB
thin-client components so that they talk to the web Can I use the Server Edition to build ISAPI,
tier instead of the report server, making thin-client CGI, ASP, and Apache applications?
communications secure. The Server Edition leverages Delphi’s ability to
build several types of web applications. The WebT-
Does the server provide encryption? ier component can be included in a Delphi Web-
The first version of the server does not include Broker application, WebSnap application, or
encryption. One solution is to use HTTPS to com- Active Server Object. The Server Edition includes
municate between clients and the WebTier. Then examples of using each of these technologies to
deploy the Server and the WebTier on the same build web applications.
machine or perhaps run the Server application on a
separate machine behind your firewall. Can I use the Server Edition with WebBroker,
WebSnap, or IntraWeb?
Yes. We have examples of using the WebTier with
Can I provide a login and user name before WebBroker, ASP, and ASP.NET. We do not cur-
users get access to the reports? rently have an example of using IntraWeb, how-
Yes, an example is installed with RB Server Edi- ever, the WebTier can be included in any web
tion. The example also shows how to allow differ- application as long you forward the web report
ent users to see different sets of reports based upon request to the WebTier by calling its ProcessRe-
login credentials. quest method. The WebTier can handle the rest.
 FAQ
26 SERVER FUNDAMENTALS

Is the Server Edition royalty-free?

No. The Server Edition provides deployment
licenses which allow you to run a server applica-
tion on a single CPU. If you decide to run the
application on a machine with multiple CPUs then
you will need to purchase one deployment license
for each CPU. The Server Edition includes one
server development license and one server deploy-
ment license. Each deployment license is “unlim-
ited-user,” you can run as many users against any
given server as you like.

Do I need to buy both the Server Edition and

the Enterprise Edition?
No. The Server Edition includes the Enterprise
Edition, so you’ll have all of the tools you need to
both create reports and deploy them to the web.

How much does it cost?

The Server Edition is US $999 - and that includes
everything in the Enterprise Edition, the Server
Edition components, one server development
license, and one server deployment license. The
Enterprise Edition already costs $749 – so you are
basically getting all of the Server Edition technol-
ogy for $250. Considering that additional deploy-
ment licenses are only $249, and that each license
allows you to run unlimited users against the
server, it’s probably the most cost effective solu-
tion out there.
TUTORIALS

Building a Report Server Application for Reports on Forms 29

Building a Report Server Application for Reports in Files 33
Building a Report Server Application for Reports in a Database 37
Building a Report Server Application for an Explorer Database 41
Building a Report Server Application for Report Archives 45
Run a Report Server Application from a Windows Service 49
Publish Reports to the Web 53
Scaling the Web Tier with a Server Farm 57
 Building a Report Server Application for Reports on Forms
TUTORIALS
29
Building a Report Server Application for Reports on Forms

Overview Copy Existing Report Application to a

This tutorial will show you how to: New Directory
1 From the Windows desktop, launch the Win-
• Configure Form-based reports for use in a Report
dows Explorer.
Server Application
2 Create the directory:
• Preview Reports from a Thin-Client Application
C:\My RB Tutorials\01. Form-Based Report
Server

3 Copy all of the files in:

…RBServer\Tutorials\Server Projects
\01. Form-Based Report Application

to the new directory.

4 Select File | Open Project from the Delphi

menu, locate the project in the new directory and
open it.

5 Select File | Save Project As from the Delphi

menu and save the project under the name
“rbServer.”

6 Run the project. You should see a single menu

item named “Reports.” Under this menu there
should be five reports listed. You should be able to
preview any of these reports.

7 Close the application and return to the Delphi

IDE.
30 Building a Report Server Application for Reports on Forms
TUTORIALS

Convert the Application to a Server Register the Reports On the Server

1 Select View | Project Manager from the Delphi 1 Select View | Project Manager from the Delphi
menu. menu.

2 Double-click the form named rbMain. 2 Double-click the form named

“rb001CustomerList.”
3 Change the caption of the form to:
3 Scroll to the bottom of the unit, and add the fol-
Form-Based Report Server
lowing code:
4 Select the RBServer tab on the Component
uses
Palette. rsReportCatalog;

initialization
TrsReportCatalog.RegisterReport(‘Examples',
5 Add an rsServer component to the form. ‘CustomerList',
‘ppReport1’,
Tfrm001CustomerList);

6 Select the form. 4 Close the form, saving all changes.

7 Code the OnCreate event of the form as: 5 Add a registration call to each of the remaining
rsServer1.Active := True; forms:

8 Press F12, to display the form. rb002Biolife

rb003OrderList
9 Delete the menu component from the form.
rb004Sections
10 Use the Code Editor to remove all event han- rb005CustomerOrderItem
dlers associated with the menu (This should leave
Note: For reports which contain event handlers,
no code in the main form at all, except the server
the uses clause will need to appear after the imple-
activation in the FormCreate method.)
mentation keyword as opposed to directly before
the initialization keyword.

6 Compile the project to make sure all code is cor-

rect.

Make the Data Access Components

Thread-Safe
1 Select View | Project Manager from the Delphi
menu.

2 Double-click the form named

“rb001CustomerList.”

3 Select the BDE tab of the component palette.

11 Close the Form and the associated unit, saving 4 Place a TDatabase component on the
all changes.
form.

5 Set the AliasName to “DBDemos.”

 Building a Report Server Application for Reports on Forms
TUTORIALS
31
6 Select all dataset components on the form and Create a Thin-Client Application
set the DatabaseName to “Database1.” 1 Select File | New | Application from the Delphi
menu.
7 Place a TSession component on the form.
2 Select File | Save Project As... from the Delphi
8 Set AutoSessionName to True. menu.

9 Select the TDatabase and TSession components 3 Name the form’s unit frmThinClient and save it
and copy them to the clipboard. in the directory with the Server application.

10 Close the form saving all changes. 4 Name the project rbThinClient and save it in the
same directory.
11 Open each of the following forms, and paste the
Database and Session components into them. 5 Select the RBServer tab of the Component
Palette.
rb002Biolife
rb003OrderList
6 Place a rsClientReport component on the
rb004Sections
form.
rb005CustomerOrderItem

12 Select File | Close All from the Delphi menu, 7 Place a rsClientReportExplorer component
saving all changes. on the form.
Run the Server Application 8 Set the ClientReport property to
1 From the Windows desktop, launch a Windows “ClientReport1.”
Explorer.
9 Code the OnCreate event of the form as:
2 Locate the rbServer.exe in the directory you cre-
rsClientReportExplorer1.Execute;
ated for this tutorial.

3 Double-click the EXE to launch the applica- 10 Select File | Save All from the Delphi menu.
tion. 11 Run the application. You should see the Report
Explorer with all of the registered reports in the
“Examples” folder. You should be able to preview
the reports.

4 Minimize the application.

 Building a Report Server Application for Reports in Files
TUTORIALS
33
Building a Report Server Application for Reports in Files

Overview Copy Existing Report Application to a

This tutorial will show you how to: New Directory
1 From the Windows desktop, launch the Win-
• Configure File-based Reports for use in a Report
dows Explorer.
Server Application
2 Create the directory:
• Preview Reports from a Thin-Client Application
C:\My RB Tutorials\02. File-Based Report
• Create a Thread-Safe Data Access Configuration Server

• Use Delphi Event Handlers with Server-based 3 Copy all of the files in:
Reports
…RBuilder\Tutorials\Server Projects\02.
File-Based Report Application

to the new directory.

4 Select File | Open Project from the Delphi
menu, locate the project in the new directory and
open it.

5 Select File | Save Project As... from the Delphi

menu and save the project under the name
“rbServer.”

6 Run the project. You should see a single menu

item named “Reports.” Under this menu there
should be five reports listed. You should be able to
preview any of these reports.

7 Close the application and return to the Delphi

IDE.
34 Building a Report Server Application for Reports in Files
TUTORIALS

Create a Thread-Safe Data Module Move the Report Event Handlers to

1 Select File | New | Data Module from the Delphi the Data Module
menu. 1 Use the Delphi Code Editor to access the unit
for the main form.
2 Save the data module as dmMain.
2 Locate the following event handlers in the class
3 Select View | Project Manager and open the
declaration for the form:
rbMain form.
{rb004Sections}
procedure ppEmpSalesGroupFooterBand1BeforePrint(Sender: TObject);

4 Cut the Database component from the procedure ppLabelContinuedPrint(Sender: TObject);

procedure ppStockListDetailBeforePrint(Sender: TObject);
{rb005CustomerOrderItem}
form and paste it into the data module. procedure varItemTotalCalc(Sender: TObject; var Value: Variant);
procedure varOrderTotalCalc(Sender: TObject; var Value: Variant);
procedure ppDetailBand1BeforePrint(Sender: TObject);.

5 Select the BDE tab of the component palette.

3 Select and cut these event handler declarations
6 Add a TSession component to the data into your clipboard.

module. 4 Click the dmMain tab of the Code Editor and

paste the declarations into the published section of
7 Set the AutoSessionName property to True.
the data module class declaration.
8 Press Ctrl-S to save all changes.
5 Click the rbMain tab of the Code Editor and
Register the File-Based Reports scroll down to the implementations of these meth-
1 Select the RBServer tab of the component ods. Select and cut the implementations into your
palette. clipboard.

2 Add an rsReportTemplateVolume compo- 6 Click the dmMain tab of the Code Editor and
paste the code into the implemementation section
nent to the data module.
of the data module.
3 Set the FileDirectory property to:
7 Scroll to the first method in the data module and
C:\My RB Tutorials\02. File-Based Report place the cursor directly in front of TfrmMain class
Server
name.
4 Set the VolumeName to “Examples.” 8 Press Ctrl-R; the Replace Text dialog is dis-
5 Press Ctrl-S to save all changes. played.

9 Enter “TDataModule1” into the Replace edit

box.
 Building a Report Server Application for Reports in Files
TUTORIALS
35
10 Click the “All” button. 5 Delete the FReport and FPath private variables
and any code associated with them from the main
11 Move the following supporting method from the
form. The unit should look like this:
main form to the private section of the data
module:
function GetDataPipelineForName(aList: TList;
const aComponentName: String
): TppDataPipeline;

12 Declare the following implementation uses in

the data module, so that the report event handlers
will compile:
uses
Graphics,
ppClass, ppCtrls, ppVar, ppBands, ppReport, daDataModule,
daDBBDE;

13 Scroll to the top of the unit and add “ppDB” to

the interface uses clause.
6 Change the Caption of the form to:
14 Right-click over the dmMain tab of the Code
Editor and close the unit, saving all changes. File-Based Report Server

Convert the Application to a Server 7 Add an rsServer component to the form.

1 Select View | Project Manager from the Delphi
8 Code the OnCreate event of the form as:
menu.
rsServer1.Active := True;
2 Double-click rbMain to display the form.
9 Run the application. It should compile and run
3 Delete the Menu component.
with no errors.
4 Remove all event handlers associated with the
10 Shut-down the application.
menu.
11 Select File | Close All from the Delphi menu,
saving all changes.

Run the Server Application

1 From the Windows desktop, launch a Windows
Explorer.

2 Locate the rbServer.exe in the directory you cre-

ated for this tutorial.

3 Double-click the EXE to launch the app.

4 Minimize the app.

36 Building a Report Server Application for Reports in Files
TUTORIALS

Create a Thin-Client Application 11 Run the application. You should see the Report
1 Select File | New | Application from the Delphi Explorer with all of the registered reports in the
menu. “Examples” folder. You should be able to preview
the reports.
2 Select File | SaveProject As... from the Delphi
menu.

3 Name the form’s unit frmThinClient and save it

in the directory with the Server application.

4 Name the project rbThinClient and save it in the

same directory.

5 Select the RBServer tab of the Component

Palette

6 Place a rsClientReport component on the

form.

7 Place a rsClientReportExplorer component

on the form.

8 Set the ClientReport property to

“ClientReport1.”

9 Code the OnCreate event of the form as:

rsClientReportExplorer1.Execute;

10 Select File | Save All from the Delphi menu.

 Building a Report Server Application for Reports in a Database
TUTORIALS
37
Building a Report Server Application for Reports in a Database

Overview Copy Existing Report Application to a

This tutorial will show you how to do the follow- New Directory
ing: 1 From the Windows desktop, launch the Win-
dows Explorer.
• Configure Databased Report Templates for use
in a Report Server Application 2 Create the directory:

• Preview Reports from a Thin-Client Application C:\My RB Tutorials\03. Databased Report

Server
• Create a Thread-Safe Data Access Configuration
3 Copy all of the files in:
• Use Delphi Event Handlers with Server-Based
…RBuilder\Tutorials\Server Projects\03.
Reports Databased Report Application

to the new directory.

4 Select File | Open Project from the Delphi

menu, locate the project in the new directory and
open it.

5 Select File | Save Project As... from the Delphi

menu and save the project under the name
“rbServer.”

Update the Path of the Database

Component
1 Double-click the Database2 database compo-
nent. Locate the PATH setting at the top of the
Parameter overrides list. We need to update this
path with the new location of the reporting tables.

2 From the Windows desktop, launch the Win-

dows Explorer.

3 Navigate to the directory for the application:

C:\My RB Tutorials\03. Databased Report

Server

4 Copy the path from the Address box of the Win-

dows Explorer.

5 Return to the Delphi IDE and replace the data-

base path with the path in your clipboard.

6 Close the Database component window.

38 Building a Report Server Application for Reports in a Database
TUTORIALS

7 Select the Table1 component and set Active to 8 Set the AutoSessionName property of the Ses-
True. This tests the new database path setting. sion component to True.

8 Run the project. You should see a single menu 9 Press Ctrl-S to save all changes.
item named “Reports.” Under this menu there
Register the Databased Reports
should be five reports listed. You should be able to
1 Select the RBServer tab of the Component
preview any of these reports.
Palette.

2 Add an rsReportTemplateVolume compo-

nent to the data module.

3 Expand the DatabaseSettings property and con-

figure:

DataPipeline ppDBPipeline1
9 Close the application and return to the BLOBField Template
Delphi IDE. NameField Name

Create a Thread-Safe Data Module 4 Set Storage Type to stDatabase.

1 Select File | New | Data Module from the Delphi 5 Set the VolumeName to “Examples.”
menu.
6 Press Ctrl-S to save all changes.
2 Save the data module as dmMain.
Move the Report Event Handlers to
3 Select View | Project Manager and open the the Data Module
rbMain form. 1 Use the Code Editor to access the unit for the
4 Select the two database components, the table, main form.
datasource and data pipeline components. 2 Locate the following event handlers in the class
declaration for the form:
{rb004Sections}
procedure ppEmpSalesGroupFooterBand1BeforePrint(Sender: TObject);
procedure ppLabelContinuedPrint(Sender: TObject);
procedure ppStockListDetailBeforePrint(Sender: TObject);

{rb005CustomerOrderItem}
procedure varItemTotalCalc(Sender: TObject; var Value: Variant);
procedure varOrderTotalCalc(Sender: TObject; var Value: Variant);
procedure ppDetailBand1BeforePrint(Sender: TObject);

3 Select and cut these event handler declarations

into your clipboard.
5 Cut the selection and paste it into the data
module. 4 Click the dmMain tab of the Code Editor and
paste the declarations into the published section of
6 Select the BDE tab on the Delphi component
the data module class declaration.
palette.
5 Click the rbMain tab of the Code Editor and
7 Place a TSession component in the data scroll down to the implementations of these meth-
module. ods. Select and cut the implementations into your
clipboard.
 Building a Report Server Application for Reports in a Database
TUTORIALS
39
6 Click the dmMain tab of the Code Editor and 8 Use the Code Editor to remove all event han-
paste the code into the implememntation section of dlers associated for the menu .
the data module.
9 Delete the FReport private variable and any
7 Scroll to the first method in the datamodule and code associated with it from the main form.
place the cursor directly in front of TfrmMain class
This should leave no code in the main form at all,
name.
except the server activation in the FormCreate
8 Press Ctrl-R; the Replace Text dialog is dis- method.
played.

9 Enter “TDataModule1” into the Replace edit

box.

10 Click the “All” button.

11 Move the following supporting method from the

main form to the private section of the data
module:
function GetDataPipelineForName(aList: TList;
const aComponentName: String;
): TppDataPipeline;

12 Declare the following implementation uses in

the data module unit, so that the report event han-
dlers will compile: 10 Run the application. It should compile and run
uses
with no errors.
Graphics,
ppClass, ppCtrls, ppVar, ppBands, ppReport, daDataModule
daDBBDE; 11 Shut-down the application.
13 Right-click over the dmMain tab of the Code
12 Select File | Close All from the Delphi menu,
Editor and close the unit, saving all changes.
saving all changes.
Convert the Application to a Server
Run the Server Application
1 Select View | Project Manager from the Delphi
1 From the Windows desktop, launch a Windows
menu.
Explorer.
2 Double-click rbMain to display the form.
2 Locate the rbServer.exe in the directory you cre-
3 Change the Caption of the form to: ated for this tutorial.

Databased Report Server 3 Double-click the EXE to launch the app.

4 Add an rsServer component to the form.

5 Replace the existing OnCreate event handler

with:

rsServer1.Active := True;

6 Press F12 to display the form.

7 Delete the menu component from the form.

4 Minimize the app.
40 Building a Report Server Application for Reports in a Database
TUTORIALS

Create a Thin-Client Application

1 Select File | New | Application from the Delphi
menu.

2 Select File | Save Project As... from the Delphi

menu.

3 Name the form’s unit frmThinClient and save it

in the directory with the Server application.

4 Name the project rbThinClient and save it in the

same directory.

5 Select the RBServer tab of the Delphi compo-

nent palette

6 Place a rsClientReport component on the

form.

7 Place a rsClientReportExplorer component

on the form.

8 Set the ClientReport property to “ClientReport.”

9 Code the OnCreate event of the form as:

rsClientReportExplorer1.Execute;

10 Select File | Save All from the Delphi menu.

11 Run the application. You should see the Report

Explorer with all of the registered reports in the
“Examples” folder. You should be able to preview
the reports.
 Building a Report Server Application for an Explorer Database
TUTORIALS
41
Building a Report Server Application for an Explorer Database

Overview Copy Existing Report Application to a

This tutorial will show you how to do the New Directory
following: 1 From the Windows desktop, launch the Win-
dows Explorer.
• Configure Explorer Reports for use in a Report
Server Application 2 Create the directory:

• Preview Reports from a Thin-Client Application C:\My RB Tutorials\04. Explorer Database

Report Server
• Create a Thread-Safe Data Access Configuration
3 Copy all of the files in:
• Use RAP Event Handlers with Server-Based
…RBuilder\Tutorials\Server Projects\04.
Reports. Explorer Database Report Application

to the new directory.

1 Select File | Open Project from the Delphi

menu, locate the project in the new directory and
open it.

2 Select File | Save Project As... from the Delphi

menu and save the project under the name
“rbServer.”

3 Double-click the dbSupportingTables database

component. Locate the PATH setting at the top of
the “Parameter overrides” list. We need to update
this path with the new location of the reporting
tables.

4 From the Windows desktop, launch the Win-

dows Explorer.

5 Navigate to the directory for the application:

C:\My RB Tutorials\04. Explorer Database

Report Server
42 Building a Report Server Application for an Explorer Database
TUTORIALS

6 Copy the path from the Address box of the Win- 4 Select all of the components in the groups
dows Explorer. labeled Folders, Items, and Databases.

7 Return to the Delphi IDE and replace the data-

base path with the path in the clipboard.

8 Close the Database component window.

9 Select the “tblFolder” component and set Active

to True. This tests the new database path setting.

10 Run the project, and click the “Launch” button.

You should see the Report Explorer and be able to
preview any of the listed reports.
5 Cut the selection and paste it into the data
module.

6 Select the BDE tab on the Delphi component

palette.

7 Place a TSession component in the data

module.

8 Set the AutoSessionName property to True.

9 Press Ctrl-S to save all changes.

Register the Databased Reports

1 Select the RBServer tab of the Delphi compo-
nent palette.
11 Close the application and return to the Delphi
IDE. 2 Add an rsReportExplorerVolume compo-

Create a Thread-Safe Data Module nent to the data module.

1 Select File | New | Data Module from the Delphi 3 Set the FolderPipeline property to plFolder.
menu.
4 Expand the FolderFieldNames property and
2 Save the Data Module as dmMain. make sure each field name is set as follows:
3 Select View | Project Manager and open the FolderId FolderId
rbMain form. Name Name
ParentId ParentId
 Building a Report Server Application for an Explorer Database
TUTORIALS
43
5 Set the ItemPipeline property to plItem data. 8 Run the application. It should compile and run
with no errors.
6 Expand the ItemFieldNames property and make
sure each field name is set as follows:

Deleted Deleted
FolderId FolderId
ItemId ItemId
ItemType ItemType
Name Name
Size Size
Template Template

7 Close the data module and the associated unit, 9 Shut-down the application.
saving all changes.
10 Select File | Close All from the Delphi menu,
Convert the Application to a Server saving all changes.
1 Select View | Project Manager from the Delphi
Run the Server Application
menu.
1 From the Windows desktop, launch a Windows
2 Double-click rbMain to display the form. Explorer.
3 Change the Caption of the form to: 2 Locate the rbServer.exe in the directory you cre-
Explorer Database Report Server ated for this tutorial.

4 Delete all of the components from the form. The 3 Double-click the EXE to launch the app.
form should now be blank. 4 Minimize the app.
5 Select the RBServer tab of the Delphi compo-
Create a Thin-Client Application
nent palette. 1 Select File | New | Application from the Delphi
menu.
6 Add a rsServer component to the form.
2 Select File | Save Project As... from the Delphi
7 Code the OnCreate event handler of the form as: menu.
rsServer1.Active := True;
3 Name the form’s unit frmThinClient and save it
Delete the event handler for the “Launch” button. in the directory with the Server application.
44 Building a Report Server Application for an Explorer Database
TUTORIALS

4 Name the project rbThinClient and save it in the

same directory.

5 Select the RBServer tab of the component

palette.

6 Place an rsClientReport component on the

form.

7 Place an rsClientReportExplorer compo-

nent on the form.

8 Set the ClientReport property to

“ClientReport1.”

9 Code the OnCreate event handler for the form

as:

rsClientReportExplorer1.Execute;

10 Select File | Save All from the Delphi menu.

11 Run the application. You should see the Report

Explorer with all of the registered reports in the
“Examples” folder. You should be able to preview
the reports.
 Building a Report Server Application for Report Archives
TUTORIALS
45
Building a Report Server Application for Report Archives

Overview Copy Existing Report Application to a

This tutorial will show you how to do the follow- New Directory
ing: 1 From the Windows desktop, launch the Win-
dows Explorer
• Access Report Archives from a Report Server
Application 2 Create the directory:

• Preview Reports from a Thin-Client Application C:\My RB Tutorials\05. Archive Report

Server

3 Copy all of the files in:

…RBuilder\Tutorials\Server Projects\05.
Archive Report Application

to the new directory.

4 Select File | Open Project from the Delphi

menu, locate the project in the new directory and
open it.

5 Select File | Save Project As... from the Delphi

menu and save the project under the name
“rbServer.”

6 Run the project. You should see a single menu

item named “Reports.” Under this menu there
should be five reports listed. You should be able to
preview any of these reports.

7 Close the application and return to the Delphi

IDE.
46 Building a Report Server Application for Report Archives
TUTORIALS

Register the Report Archives 5 Remove all of the event handlers associated
1 Select File | New | Data Module from the Delphi with the Menu from the form’s unit.
menu.

2 Save the data module as dmMain.

3 Select the RBServer tab on the Delphi compo-

nent palette.

4 Add an rsReportArchiveVolume compo-

nent to the data module.

5 Set the FileDirectory property to:

C:\My RB Tutorials\05. Archive Report

Server

6 Set the VolumeName property to “Examples.”

7 Close the data module and the associated unit,

saving all changes. 6 Select the RBServer tab of the Delphi compo-
nent palette.
Convert the Application to a Server
1 Select View | Project Manager from the Delphi
7 Add an rsServer component to the form.
menu.

2 Double-click rbMain to display the form. 8 Code the OnCreate event of the form as:

rsServer1.Active := True;
3 Change the Caption of the form to:
9 Run the application. It should compile and run
Archive Report Server
with no errors.
4 Delete the Menu and Archive Reader compo-
10 Shut-down the application.
nents from the form. The form should now be
blank. 11 Select File | Close All from the Delphi menu,
saving all changes.

Run the Server Application

1 From the Windows desktop, launch a Windows
Explorer.

2 Locate the rbServer.exe in the directory you cre-

ated for this tutorial.

3 Double-click the EXE to launch the app.

4 Minimize the app.

 Building a Report Server Application for Report Archives
TUTORIALS
47
Create a Thin-Client Application
1 Select File | New Application from the Delphi
menu.

2 Select File | Save Project As... from the Delphi

menu.

3 Name the form’s unit frmThinClient and save it

in the directory with the Server application.

4 Name the project rbThinClient and save it in the

same directory.

5 Select the RBServer tab of the Component

Palette

6 Place an rsClientReport component on the

form.

7 Place an rsClientReportExplorer compo-

nent on the form.

8 Set the ClientReport property to

“ClientReport1.”

9 Code the OnCreate event handler of the form as:

rsClientReportExplorer1.Execute;

10 Select File | Save All from the Delphi menu.

11 Run the application. You should see the Report

Explorer with all of the registered reports in the
“Examples” folder. You should be able to preview
the reports.
 Run a Report Server Application from a Windows Service
TUTORIALS
49
Run a Report Server Application from a Windows Service

Overview Install the Windows Service

This tutorial will show you how to do the follow- 1 From the Windows Desktop, launch a Windows
ing: Explorer.

• Install a Windows Service 2 Locate the RBWinService.exe in:

• Use the RB Services Administrator to Designate C:\Program Files\Boland\Delphi6-

\RBServer\Windows Service
a Report Server Application
3 Run this program and accept the default location
In previous tutorials we built a Report Server appli-
for the service application. Once the installation
cation as a stand-alone EXE. While this is certainly
a valid way to run a report server, the Server Edi- process is complete, you should see the following
tion provides for a two-piece server architecture, icon on your system tray:
where a Windows Service hosts a report server
application. This scheme is more robust; if the
report server crashes, the Windows Service can
restart it. This tutorial will show you how to put
such an architecture in place.

4 Double-click this icon to display the RB Ser-

vices dialog:

This dialog shows that the service is up and run-

ning, and that a sample Report Server application
is being hosted from the given location.

5 Close the dialog.

50 Run a Report Server Application from a Windows Service
TUTORIALS

Create a Service Compatible Report 4 Set the FileDirectory property to:

Server Application C:\My RB Tutorials\
1 From the Windows Desktop, launch a Windows 06. Windows Service-Based Server
Explorer and create a new directory: 5 Select Project | Compile from the Delphi menu.
C:\My RB Tutorials\
06. Windows Service-Based Server
6 Select File | Close All from the Delphi menu,
saving all changes.
2 Copy the contents of:
Designate the Report Server
…RBServer\Tutorials\Complete\01. Build a
Report Server Application\05. Reports in Application from the Windows Service
Archives
1 Double-click the ReportBuilder Services
to the new directory.
icon in the system tray.
3 Launch Delphi and open the rbServer project in
2 Click the Stop button. The top part of the dialog
the new directory.
should change to light red, indicating the service is
4 Access the unit for the rbMain form. stopped.

5 In the interface section add “rsServerActiveX” 3 Click the Change button and designate the
to the uses clause. rbServer application in:

6 Select Run | Parameters from the Delphi menu. C:\My RB Tutorials\06. Windows
Service-Based Server
7 In the parameters edit box enter:
4 Click the Start button. The top area of the dialog
/regserver should turn light green, indicating the server is
running.
8 Click OK to close the dialog.
5 Close the dialog.
9 Press F9 to run the project. If the COM server is
registered successfully, no message will be dis- Run the Thin-Client Application
played. 1 Return to the Delphi IDE.

Update the File Directory of the 2 Select File | Open Project from the Delphi
Report Volume Menu.
1 Select View | Project Manager from the Delphi
3 Locate rbThinClient.dpr in the directory for this
menu.
tutorial and open it.
2 Double-click dmMain to display the data
module.

3 Select the rsReportArchiveVolume1 compo-

nent.
 Run a Report Server Application from a Windows Service
TUTORIALS
51
4 Run the application. You should see the Report
Explorer with all of the registered reports in the
“Examples” folder. You should be able to preview
the reports.
 Publish Reports to the Web
TUTORIALS
53
Publish Reports to the Web

Overview Create a Directory for the Web Tier

This tutorial will show you how to do the follow- 1 From the Windows Desktop launch the Win-
ing: dows Explorer.

• Build a WebTier as an ISAPI DLL 2 Create the following directory:

• Configure a Virtual Directory on IIS C:\My RB Tutorials\07. WebTier\Cache

For this tutorial, you will need a machine with IIS 3 Select the “Cache” directory.
5 installed. You will also need a report server 4 Right-click and select Properties.
application running. Therefore, completing the pre-
5 If you see the Securities tab, select this tab and
vious tutorial is recommended before beginning
continue with steps 6-8. If you do not see the Secu-
this tutorial.
rities tab, jump to the next section entitled “Create
Note: This tutorial was created using IIS 5, how- a Virtual Director on IIS.”
ever the steps for IIS 4 are similar. Depending on
6 Select IWAM_<MachineName> user.
your knowledge of IIS, you may be able to suc-
cessfully use this tutorial with IIS 4. 7 Click the “Full Control”checkbox.

8 Close the dialog.

Note: The ISAPI DLL we are about to create

needs full read/write access to the Cache directory
in order to store and remove files as reports are
generated.
54 Publish Reports to the Web
TUTORIALS

Create a Virtual Directory on IIS 12 Click Finish. A new virtual directory will be
1 Access the Control Panel and double-click created and selected.
Administrative Tools.
13 Right-click over the new directory and select
2 Double-click Internet Information Services. Properties.

3 Expand “local computer,” “Web Sites” and 14 Locate the “Application Protection” drop-down
locate the “Default Web Site” entry. list at the bottom of the dialog.

4 Right-click “Default Web Site” and select New |

Virtual Directory.

5 Click Next.

6 Enter “myWebTier” as the alias for the

directory. 15 Change the setting from “Medium (Pooled)” to
7 Click Next. “High (Isolated)”

8 Set the directory to: 16 Click Apply.

C:\My RB Tutorials\07. WebTier 17 Click OK to close the dialog.

9 Click Next. 18 Close the Internet Information Services and

Administrative Tools windows.

Create an ISAPI DLL

1 Launch Delphi.

2 Select File | New | Other… The following dia-

log will be displayed:

10 Check the box labeled “Execute (such as ISAPI

applications or CGI).”

11 Click Next.
 Publish Reports to the Web
TUTORIALS
55
3 Scroll to the bottom row of icons and double- 11 Select the RBServer tab on the Delphi compo-
click “Web Server Application.” nent palette.

A dialog will be displayed requesting the type of

12 Place an rsWebTier component in the web
web application you want to create:
module.

13 Configure as follows:

CacheDirectory C:\My RB Tutorials\

07.WebTier\Cache\
WebCachePath http://localhost/
myWebTier/Cache/
WebModuleURI http://localhost/
myWebTier/myWebTier.dll

Add a Default Action to the

4 Click OK to accept the default. A new web WebModule
module will be created. 1 Right-click over the Web Module and select
5 Select File | Save Project As... from the Delphi “Action Editor.”
menu. 2 Add an Action to the list.
6 Save the web module under the name 3 Use the Object Inspector to set the Default
“wmMain.” property of the Action to True.
7 Save the project under the name “myWebTier.” 4 Select the Events tab of the Object Inspector.
8 Select View | Project Manager from the Delphi 5 Double-click the OnAction event and code the
Menu. following:
9 Right-click myWebTier.dll and select View Response.Content := rsWebTier1.ProcessWebRequest(
Request.QueryFields,
Source. Request.Content);

6 Compile the application. You should now see

10 Change “ISAPIThreadPool” to “rsISAP-
myWebTier.dll in the project directory.
IThreadPool.” This will allow the ISAPI dll to uti-
lize a more optimized thread pool. 7 Launch Internet Explorer and enter the follow-
ing address:

http://localhost/myWebTier/myWebTier.dll
56 Publish Reports to the Web
TUTORIALS

8 Press enter. The Report Explorer is displayed:

9 Single click on a report to preview.

 Scaling the Web Tier with a Server Farm
TUTORIALS
57
Scaling the Web Tier with a Server Farm

Overview Create a Report Server Application

This tutorial will show you how to do the follow- 1 From the Web Server machine, launch Delphi
ing: and select File | Open Project... from the main
menu.
• Use a ServerFarm to increase the number of
users which can be supported by a WebTier. 2 Open the rbServer project in the following
directory:
• Use “Round Robin” or “Minimum Load” load
balancers to assign servers to client sessions. C:\Program Files\Borland\Delphi6-
\RBServer\Tutorials\Complete-
• Track which server has been assigned to a given \01. Build a Report Server Application-
\05. Reports in Archives
client session.
3 Compile the project.
Prerequisites: This tutorial assumes you have com-
pleted at least one of the report server application 4 Select File | Close All from the Delphi menu.
tutorials, the Windows service tutorial and the
Copy the Report Server Application to
“Publish Reports to the Web” tutorial.
a Network Folder
Hardware needed: You will need access to at least 1 From the Windows Desktop, launch a Windows
three machines: Two to be used as report servers Explorer.
and one to be used as the web server/client testing 2 Locate the executable you just created in:
machine. On the first PC (which we will call the
Web Server), you’ll need , IIS 5 (or 4), Delphi and C:\Program Files\Borland\Delphi6-
\RBServer\Tutorials\Complete-
ReportBuilder Server Edition installed. The two \01. Build a Report Server Application-
report server machines need access to the same net- \05. Reports in Archives
work as the Web Server machine. 3 Select the following files and copy them to your
clipboard:

rbServer.exe
rb001CustomerList.raf
rb002Biolife.raf
rb003OrderList.raf
rb004Sections.raf
rb005CustomerOrderItem.raf
58 Scaling the Web Tier with a Server Farm
TUTORIALS

4 Paste these files into a network folder which is 7 Double-click this icon, to display the Report-
accessible from the two report server machines. Builder Services dialog.

5 Copy RBWinService.exe and ReadMe.doc 8 Click the Stop button to stop the sample server.
from:
9 Click the Change button and select rbServer.exe
C:\Program Files\Borland\Delphi6- in C:\Report Server.
\RBServer\Windows Service
10 Click the Start button; the top section of the dia-
To the same network folder in which you saved the
log should turn green after a second or two, indi-
report server application files.
cating that the server is running.
Deploy the Report Server Application
11 Close the dialog.
1 Move to the first report server machine. (You’ll
need to be at the keyboard for this computer.) 12 From the Windows Desktop select Start | Pro-
grams | Accessories | Command Prompt.
2 From the Windows Desktop launch a Windows
Explorer. 13 At the command prompt, type “ipconfig” and
press enter.
3 Create the directory:
14 Write down the IP address of the machine.
C:\Report Server

4 Copy the following files from the network 15 Repeat steps 1-14 on the second report server
folder into this directory: machine. You should now have two active report
server machines and the IP address of each.
rbServer.exe
rb001CustomerList.raf Check Each Server via Thin Client
rb002Biolife.raf 1 Return to the Web Server machine.
rb003OrderList.raf 2 From Delphi, open the project in:
rb004Sections.raf
C:\Program Files\Borland\Delphi6-
rb005CustomerOrderItem.raf
\RBServer\Demos\Clients-
\01. Client Explorer
5 Locate RBWinService.exe in the network
folder. 3 Select the “cbxAddress” combo box.

6 Run this program, accepting the default entries 4 Use the Object Inspector to enter the two IP
(this will install the Windows service that hosts the addresses for the server machines in the Items
report server application.) After the installation is property.
complete, you should see a new icon on your Sys-
5 Press Ctrl-S to save your changes.
tem Tray:
6 Run the application.

7 Select the IP address for the first server and

click the “Explorer” button.
 Scaling the Web Tier with a Server Farm
TUTORIALS
59
8 You should see the main window for the 7 Close the String List Editor.
ClientReportExplorer:
8 Check to make sure that the LoadBalancer prop-
erty is set to “Round Robin.”

9 Press Ctrl-S to save your changes.

10 Select Project | Build All Projects from the Del-

phi menu.

11 Use the Windows Explorer to copy myWebT-

ier.dll to the myWebTier virtual directory. (If you
do not understand this step, please complete the
“Publish Reports to the Web” tutorial before con-
9 Close this window and select the IP address for tinuing.)
the second server.
Note: If myWebTier.dll will not copy success-
10 Click the “Explorer” button; you should see the fully, use Internet Information Services to unload
same ClientReportExplorer window. This confirms the existing DLL.
that both report servers are up and running.
Test via Web Browser
11 Close the application and return to Delphi. 1 From the Windows Desktop, launch an Internet
Configure a Web Tier Using Round Explorer.
Robin 2 Enter the following address:
1 From Delphi, open the myWebTier.dpr project
http://localhost/myWebTier/myWebTier.dll
in:
You should see the ClientReportExplorer (only this
C:\Program Files\Borland\Delphi6-
\RBServer\Tutorials\Complete- time as a JavaScript/HTML application.)
\03. Publish Reports via a Web Server
Note: It would be a good idea to add this link as
2 Select View | Project Manager and double-click one of your “favorite” links, otherwise you will
“wmMain.” end up entering it over and over again in the
3 Select the WebTier component. remainder of this tutorial.

4 Expand the ServerFarmSettings property in the 3 Preview a few of the reports.

Object Inspector. 4 Launch another Internet Explorer and preview
5 Launch the property editor for ServerAddresses. reports with it as well. When you run the second
browser, you’ll actually be running reports on the
6 Enter the IP address for each report server on a
second server. However, from the browser you
separate line.
can’t really tell; it all looks the same. Let’s track
which server is generating the pages for a given
browser.
60 Scaling the Web Tier with a Server Farm
TUTORIALS

5 Return to Delphi and reopen the “myWebTier” 8 Experiment with creating load on a given server
project. and then launching a new web browser to see if the
other server is used. You should be able to get
6 Select the WebTier component and expand the
browsers with reports generated by both servers.
ServerFarmSettings property.

7 Set ColorizedPages to True.

8 Recompile and redeploy myWebTier.dll.

9 Launch two new web browsers and preview

reports in each. You should notice that the report
page color in the first web browser is light red and
the report page color in the second web browser is
light green. This verifies that the reports have been
generated by different servers.

Configure a Web Tier Using Minimum

Load
1 Return to Delphi and reopen the “myWebTier”
project.

2 Select View | Project Manager and double-click

“wmMain.”

3 Select the WebTier component and expand the

ServerFarmSettings property.

4 Set the LoadBalancer property to “Minimum

Load.”

5 Recompile and redeploy myWebTier.dll.

6 Launch a web browser and begin previewing a

report. The report page color should be light red.
Return to the Report Explorer and launch another
report in the same web browser. Continue pre-
viewing different reports for about sixty seconds.

7 Launch another web browser and preview a

report. If your activity on the first browser gener-
ated enough load, the report page color in this sec-
ond browser will be light green (indicating that the
second server was used to generate the pages.)