The Report Designer Component and Active Server Pages

The legacy choice for Active Server Page integration of Crystal Reports is the Report Designer Component, or RDC. The RDC, originally introduced as an add-on to Crystal Reports 7, is a Component Object Model (COM) “compliant set of objects that expose almost every feature of a report to a COM-compliant development environment, such as Visual Basic or ASP. While Business Objects has relegated this interface to legacy status, the RDC is still a very valid development choice for ASP-based applications.

As the RDC is a COM-based interface, its primary focus will lie with web-based applications utilizing Active Server Pages (ASPs) on a Microsoft web server. This technology, which is the predecessor to the current state-of-the-art ASP.NET web environment, can be coded using either VBScript or JavaScript server-side development languages. This chapter concentrates on the Visual Basic, or VBScript, approach.

Active Server Pages and VBScript Overview

The original language of the Web, Hypertext Markup Language (HTML), can be used to create attractive, hyperlinked pages with graphics, various font sizes, and (with the advent of newer HTML extensions, such as dynamic HTML) more interactivity and multimedia features. However, being a markup language instead of a true procedural or event-driven development language, HTML falls far short of providing all the flexibility you may need to create full web-based custom applications. To help fill this void, the industry has adopted scripting languages that allow browsers to perform much more sophisticated and intricate procedures. Two scripting languages are established: JavaScript is a scripting language based on Java, and VBScript is a scripting language based on Microsoft s Visual Basic for Applications (VBA). JavaScript is supported by both major browser vendors , Microsoft and Netscape. VBScript, generally , is limited to versions of Microsoft Internet Explorer (IE).

JavaScript and VBScript are client-side scripting languages ”both being interpreted by the browser after being downloaded in a web page. The scripts are not compiled into machine-executable code and generally cannot make database connections to a corporate database. And because these scripts execute on a browser that can be affected by any number of client-side variables , a developer cannot always expect consistent results.

To provide more flexibility and offer connectivity to corporate databases, Microsoft also implements server-side scripting on its Internet Information Server for Windows NT Server, Windows 2000, Windows XP Professional, and Windows Server 2003. In this instance, the scripting language is interpreted by the web server instead of the web browser client. The results of the server-executed script are then sent to the web browser as HTML. Because the script is executed on the server, you can create much more robust and flexible applications that are browser-independent ”all that is sent to the browser is HTML. Microsoft s implementation of server-side scripting is called Active Server Pages (ASP). When a web server has ASP support installed, pages scripted with ASP are given a file extension of .ASP instead of .HTM. The web server will then scan the .ASP file for server-side script and execute any it finds, sending the results of the script to the browser.

To enhance ASP even more, Microsoft extends the Component Object Model (COM), which is discussed in more detail in the Visual Basic chapters in Part III of this book, to its web server platform. Because of this, the RDC and CE Embedded can both be integrated with server-side scripts to create extensive reporting flexibility in web applications. By using the full VBA power of ASP, combined with the ability of the RDC and CE Embedded COM object models to control almost every aspect of a report at run time, you can create VB-like applications that integrate reports in a web browser.

Note  

CE Embedded provides support for Java Server Pages on Java-oriented, non-Microsoft web servers. And, both VBScript and JScript (Microsoft s version of JavaScript) can be executed in ASP on a Microsoft web server. However, only VBScript within Microsoft ASP is discussed in this chapter. Java-oriented web developing, using the new Java Reporting Component, is discussed in Chapter 23.

Preparing for RDC-based ASP Applications

When you install Crystal Reports 9 Developer or Advanced Developer editions, the RDC is installed and registered automatically (the RDC is not included with Standard or Professional Editions). However, sample ASP pages that demonstrate RDC integration with ASP are no longer included with Crystal Reports 10. In fact, some critical support ASPs that handle the various web viewing options and report processing tasks (such as page-on-demand architecture over the web) are not even included in the CE 10 package (probably in a concerted effort to move developers toward CE Embedded for their web reporting integration).

Note  

A sample RDC-based ASP application, including several critical support ASPs, can be downloaded from this book s companion web site. Visit www.CrystalBook.com to get these samples. You may also get samples from the Business Objects web site. Browse to support.BusinessObjects.com and search for aspxmps10.exe.

Once you ve created any necessary virtual directories and copied the sample applications, you may use Visual InterDev, Notepad, or another editor to view the HTML and ASP code in these applications.

What Is RPTSERVER.ASP?

As you look through the ASP example files downloaded from CrystalBook.com, you ll notice that ASP web reports are displayed in one of several Crystal Report Viewers. Note that the report viewers are always pointed to another file, called RPTSERVER.ASP. This support ASP is a very important part of Crystal Reports integration with the RDC (a starkly different version of the file is included with CE Embedded ”the logic demonstrated is entirely different between the RDC and CE Embedded).

When you integrate a report with the RDC and Visual Basic (as covered in Chapter 27), you use the separate Report Viewer ActiveX control to show the report in a VB window. However, because integrating with the Web means your eventual display target is a web browser, you need to consider some other viewing alternatives when using ASPs. The available web report viewers ”ActiveX, Java for Browser JVM, Java Plug-In, Netscape Plug-In, HTML Frames, and HTML Page ”can all be used with ASPs. In fact, the report viewer for ActiveX is the same CRVIEWER.DLL module used to display reports with the RDC in Visual Basic.

Because these viewers use Crystal Reports page-on-demand architecture, they expect report pages to be fed to them by the RDC s PageEngine object. This rather complicated logic and interaction, including all the necessary post back processing to support page-on- demand, is handled by RPTSERVER.ASP. Although you might be able to write your own ASP code to replace the function of RPTSERVER.ASP, one look at the ASP code in this file will probably convince you that it won t be worth the effort.

The RDC Object Model in ASPs

Because Active Server Pages support COM automation servers, you can implement Crystal Reports integration in ASP in much the same way as you do in Visual Basic. The complete RDC object model is available for you to use in your Active Server Pages. You can set properties and execute methods for different objects to customize report behavior. Typically, you ll use controls your user has completed on a form, or perhaps values your ASP is retrieving from a database, to control report appearance at run time.

The Application and Report Objects

As with Visual Basic, two base-level objects must be initially declared in your web project: the Application object and the Report object (the Application object is used in VB only if you are integrating an external .RPT file). The Application object needs to be declared only once, at the beginning of a project. Because Crystal Reports 10 continues the recent Crystal Reports tradition of side-by-side installations (more than one Crystal Reports version being installed on the same computer), you need to add a version identifier to the ProgID when declaring the Application object.

Once declared, the Application object is then used to open a Report object; it is generally not used again throughout the rest of the project until it is handed off to RPTSERVER.ASP. Because these objects must remain in scope throughout the project and all associated ASP files, they are declared as session variables, which retain their values and remain in scope throughout an entire ASP project. Here s sample ASP code to declare them:

 ' CREATE THE APPLICATION OBJECT 
 If Not IsObject (session("oApp")) Then 
 Set session("oApp") = _ 
 Server.CreateObject("CrystalRuntime.Application.10") 
 End If 
 
 ' CREATE THE REPORT OBJECT 
 reportname = Path & "Xtreme Orders.rpt" 
 'Path must be physical path, not virtual path 
 If IsObject(session("oRpt")) then 
 Set session("oRpt") = nothing 
 End If 
 Set session("oRpt") = session("oApp").OpenReport(reportname, 1) 
 
 ' Disable error prompts on the Web server 
 session("oRpt").EnableParameterPrompting = False 

A few notes about this sample VBScript code:

• Variables don t need to be identified with DIM or declared before use. In VB terms, no Option Explicit statement has been executed. While this may seem to ease your coding requirements, you need to remember that this means that all variables used in this fashion are variants. Some RDC methods require that variables be passed with a specific data type. In those cases, use VBScript typecasting functions, such as CStr and CInt, to correctly cast variables when passing them.

• The report file has been preceded with a Path variable, which is assigned in previous VBScript not shown here (the Request.ServerVariables( PATH_TRANSLATED ) value can be queried for an actual physical pathname to the current ASP). The path must be the physical path to the report file (for example, C:\REPORTS) because the RDC can t resolve web server virtual paths. If you know that the .RPT file will be in a fixed, known location, you can skip this entire section of code and simply supply a physical path and filename to the OpenReport method.

• The Application object is declared only once. To ensure that you use version 10 of the RDC (since more than one version can now reside on a single computer), you should add .10 at the end of the ProgID. If this section of VBScript is executed again, the previous declaration of oApp will remain. However, if there is a previous declaration of the Report object (presumably for a different report that may have been processed in a previous pass through this code), it will be set to Nothing before being set to the new report with the Application object s OpenReport method.

• The EnableParameterPrompting property of the Report object is set to false. This reduces the chances of any prompts appearing on the web server if not supplied by your code. If the RDC displays a prompt on the web server screen while a browser is waiting for a report request, the webmaster likely won t be sitting nearby, waiting to respond to the web server message. The browser session will hang, or eventually time out, if this happens.

  Caution  

  You may see line continuation underlines in the sample code in this book to indicate that a line of code continues from the previous line (this is a Visual Basic standard). However, this is only supported in Visual Basic and is not supported in Active Server Pages. If you type this code in directly, you ll need to keep both lines of code on the same physical line in your ASP.

Manipulating the Report Object

Once the Report object has been assigned to an .RPT file by setting it to the Application object s OpenReport method, you can use your user interface elements, such as controls on the calling form, to customize the way the report behaves. Use objects, collections, methods, and properties for the Report object to control report behavior. You can also pass logon information for the report (using the RDC connection property bag properties) from within your code.

Here are some examples:

 ' Log On to report database connection 
 
 Session("oRpt").Database.Tables(1).ConnectionProperties("User ID")_ 
 = "DBReader" 
 Session("oRpt").Database.Tables(1).ConnectionProperties("Password")_ 
 = "DBPassword" 

This code supplies logon information to the first table of the report (if there is more than one table, you ll need to supply logon information to each table within the tables collection). This makes use of the ConnectionProperties Property Bag collection of the RDC. These various property bags contain variable numbers and types of properties, depending on the particular database connection used for that particular table.

Tip  

Specific information on these property bags, as well as the complete RDC object model reference, can be found in Crystal Reports Developer s Help. Navigate to Program Files\Crystal Decisions\Crystal Reports 10\Developer Files\Help\<language> and open DevHelp.CHM. Note that the version of this help file installed from the original Crystal Reports 10 CD may refer to Crystal Reports 9. Download and install the latest hotfix from support.BusinessObjects.com to get updated help files.

 session("oRpt").DiscardSavedData 
 session("oRpt").RecordSelectionFormula = "{Customer.Country} = 'USA'" 

This code first discards any saved data records that may exist within the .RPT file. It then sets the Report object s RecordSelectionFormula property to limit the report to customers in the U.S.A. You could just as easily use some form element or other variable from within your ASP to set the record selection formula.

The following sample code is used to pass a value to a report parameter field:

 session("oRpt").ParameterFields(1).AddCurrentValue _ 
 CInt(Request.Form("txtTaxRate"))) 

Again, this code is passing the value from the calling form object txtTaxRate to the AddCurrentValue method. This method applies to a member of the ParameterFields collection of the Report object. Note that it s a good idea to use a type declaration function (such as CInt) to ensure that the proper data type is being passed to the RDC.

Tip  

These are just a few examples of how to manipulate the Report object within your code. For additional RDC object model methods and property examples, refer to Chapter 27. Or, look through Crystal Reports Developer s Help.

After you set all necessary properties for the report object and are ready to process the report, you may need to execute the Report object s ReadRecords method to actually populate the report with data from the database. If the report is based on a PC-style database or an ODBC connection that the web server can reach during the report process, this step may not be necessary. However, if you ve used the DataBase object s SetDataSource method to change the datasource of the report to an ADO recordset or some other datasource that s only in scope in the current VBScript procedure, you need to execute ReadRecords so that the report won t fail. If you don t, and the Report object is used in another VBScript procedure (such as RPTSERVER.ASP) when the recordset is no longer in scope, the report won t be able to read records from the recordset. Here s sample code to execute ReadRecords:

 On Error Resume Next 
 session("oRpt").ReadRecords 
 If Err.Number <> 0 Then Response.Write _ 
 "A server error occurred when trying to access the datasource" 

The PageEngine Object

The RDC exposes a PageEngine object that you normally don t need to worry about in Visual Basic applications because of the report viewer s ViewReport method. However, since you need to pass the Report object to RPTSERVER.ASP to page out to a Crystal Report Viewer, you need to declare the PageEngine object so that RPTSERVER.ASP can use it to communicate with the report viewers. If you look at RPTSERVER.ASP, you ll be able to get an idea (probably after a significant amount of poking around, though) of how the PageEngine works. Declare it with code similar to the following:

 If IsObject(session("oPageEngine")) Then 
 set session("oPageEngine") = Nothing 
 End If 
 Set session("oPageEngine") = session("oRpt").PageEngine 

Caution  

Because RPTSERVER.ASP is the ultimate ASP that processes the report, you need to think about it when you declare session variables. It expects three session variables to be declared with specific names: session( oApp ), which is the Application object; session( oRpt ), which is the Report object; and session( oPageEngine ), which is the PageEngine object. Don t use alternative variable names for these session variables, or RPTSERVER.ASP will fail.