Web Integration with CE Embedded Edition | Crystal Reports 10: The Complete Reference

Crystal Reports 9 introduced the Report Application Server Edition of Crystal Enterprise. In version 10, this edition has been renamed Crystal Enterprise Embedded Edition (although almost all documentation and supplementary materials in version 10 still refer to this as RAS ). CE Embedded also maintains a certain presence in the Professional and Premium editions of Crystal Enterprise as the Report Application Server. CE Embedded is included with Crystal Reports 10 Developer and Advanced Developer Editions.

Crystal Reports 10 leaves no doubt that the future direction of single- tier or stand-alone Crystal Reports web integration (that is, web applications not using the full multitier version of Crystal Enterprise) is CE Embedded. Support files and documentation describing web integration with the version 10 RDC are almost entirely absent from Crystal Reports 10. There are also technical reasons you should look toward CE Embedded:

Multitier processing capabilities CE Embedded provides the ability to move report processing off the web server to another dedicated computer (the RDC requires the web server to perform all report processing).
Adoption of a Crystal Enterprise “centric object model Code developed with CE Embedded is Crystal Enterprise “ready, requiring little additional effort to move to a full Crystal Enterprise environment (for example, the sample CE Embedded application downloadable from CrystalBook.com can be converted to run under the Crystal Enterprise Professional guest account by changing one line of code). Also, new CE-based features, such as repository report objects and Business Views, are not available in reports integrated with the RDC (nor CE Embedded for that matter ”you must upgrade to full Crystal Enterprise versions to use these features, but your CE Embedded custom coding will require little modification).
On-the-fly report design capability (Crystal Reports Advanced Developer Edition only) The initial purpose of CE Embedded (when it was known as the Report Application Server with earlier versions of Crystal Enterprise) was solely to provide the ability to design a report from scratch using a web browser “based wizard. While the RDC also features the ability to create new reports from scratch, this CE Embedded capability is well developed. While these capabilities are considerable, you still may wish to stay with the RDC in certain circumstances.

A considerable amount of existing RDC code Converting RDC code to CE Embedded is not simple ”the object models are quite different. You ll face a significant conversion hurdle .

Note

While the CE Embedded SDK is the same in Crystal Reports Developer and Advanced Developer Editions, the CE Embedded licensing agreement allows you to use CE Embedded applications in a production environment with Advanced Developer, whereas the Developer Edition license only allows a test environment.

Basic CE Embedded Operation

CE Embedded ships with Crystal Reports on a separate CD. When you install it, a default start page is installed. Browse to http://< Web server >/rassamples10 to view it. The start page will be displayed.

Report Preview Application

Unlike the full versions of Crystal Enterprise, CE Embedded has very little out of the box functionality that can be used right away without custom coding. While the initial release of RAS in Crystal Reports 9 included the ePortfolio Lite application, this has not been included in CE Embedded 10. The one supplied application that may be of limited use is a very simple report preview capability available from the start page. Click the Report Preview link on the left side of the start page to display the Report Preview Sample.

The first time you view this page, you ll be prompted to choose a report name from the list in the left frame. You ll also notice a message indicating that database logon and parameter values will need to be specified before using several of the available report viewers (the available viewer choices will appear in the top frame). Once you initially view a report, cookies will be set and you ll return to the same report the next time you launch the report viewer application.

While this is a very simple application, it may be sufficient for a small, entry-level web reporting environment. You may also be able to harvest some of the ASP code used in this application for your own custom CE Embedded application, perhaps integrated into your own intranet or Internet site. The application consists of several ASPs that gather a list of reports, set several session variables , set cookies, and pass the desired report to an ASP that matches the chosen report viewer.

The Crystal Configuration Manager

As discussed earlier in the chapter, CE Embedded largely consists of the Report Application Server (RAS) portion of the full version of Crystal Enterprise. And as with the full CE version, CE Embedded includes a Windows configuration program to set a small set of configurable items that you may need to adjust, depending on your particular environment. The Crystal Configuration Manager, or CCM, appears on the Crystal Enterprise 10 program group . Once you start it, the main window appears, as shown in Figure 22-1.

Figure 22-1: Crystal Configuration Manager

The CCM will display entries for all your Crystal Enterprise server components (in the case of a CE Embedded-only installation, just the RAS). And, if you have RAS installed on the same machine as a web server, an entry for the IIS web server will also appear in the CCM. You may perform several administrative functions on these server components right in the CCM. As the Report Application Server and IIS are both NT Services, you can stop, pause, start, or restart them from the CCM as well as from the Windows Control Panel Administrative application. However, you must use the CCM to configure other RAS-specific options ”they cannot be specified in Control Panel.

While you can view RAS properties while the RAS service is running, you won t be able to make any changes to them. In order to actually configure RAS, you must first stop the service. Select it and click the Stop toolbar button, or right-click and choose Stop from the pop-up menu.

Once the service is stopped , configure the Report Application Server by selecting it and clicking the properties button in the CCM toolbar. You may also double-click the entry in the CCM or right-click and choose Properties from the pop-up menu.

The CCM will display the RAS Properties dialog box, which will contain three tabs: Properties, Dependency, and Parameters.

Properties Tab

The Properties tab largely mimics the capabilities found in the Control Panel Administrative Tools Services option. Here, you can change the Windows user ID and password the NT Service uses when starting, whether the service starts automatically when the computer is booted , and so forth.

One exception is the command used to start the service. By modifying this entry in the CCM, you can add or modify command line switches that modify the behavior of the RAS when the service starts. For example, you can add switches to change the IP port the service uses, to restart the service automatically if it fails, to control how many entries the RAS will place in the audit log, and so forth. Make any changes to the command in the Command text box.

Tip	Complete details on all available RAS command line switches can be found in CCM help. Click the Index tab and search for command-line options.

Dependency Tab

Similar to the Properties tab, settings in the Dependency tab largely mimic settings you can make in the Windows Control Panel. Items displayed in the Dependency indicate other NT services that must be running before the Report Application Server will run. Normally, you needn t make any changes to this list of services. However, if you have a unique server environment that requires that additional services be running prior to RAS start up, add them using the Add button in the Dependency tab.

Parameters Tab

The Parameters tab is where most of the RAS-specific configuration takes place. When CE Embedded is initially installed, most of the options in this tab are set to reasonable defaults that shouldn t typically require change (with one notable exception: the Report Directory entry under the Servers option). However, if you detect performance problems that you think may be reduced by modifying some options, you may try various settings in the Parameters tab to attempt a performance improvement.

The Parameters tab actually contains two separate screens that you use to configure the RAS. Choose between the Database and Server options by making the desired choice in the Option type drop-down list. When you choose Database options, several options that determine how CE Embedded interacts with productions databases appear.

Max Number of Records If you choose the Records Limited To radio button, you may specify the maximum number of records you wish CE Embedded to send to a web browser. You may wish to specify a finite number to avoid large amounts of data being sent over your network.
Batch Size CE Embedded communicates with the database in record batches. Depending on the database you are using and your network environment, you may see improved performance by enlarging or reducing the size of the record batch.
Browse Data Size CE Embedded features the ability to request a batch of sample data to be returned from the database when browsing data (much as Crystal Reports does). This setting allows you to specify the number of distinct values that will be returned from the database for the browse. Adjusting this number may improve browse performance.
Data Refresh CE Embedded keeps sets of retrieved database data in a temporary location for possible use in later queries. Therefore, if two report viewers request the same set of data within the time specified in this parameter, the second viewer gets the data from RAS memory rather than from the production database. While this can improve performance, it also presents the possibility that old data may be presented to a viewer if CE Embedded is accessing a very fluid database. If this is of concern, lower this value, or set it to zero to disable the memory storage of recent data requests .
Report Job Database Connection This option determines when CE Embedded will close its connection to the production database. The first option will cause the RAS to disconnect when an initial set of records has been read when processing a report request, even before the browser containing the report is closed. While this reduces the time that RAS is connected to the database (perhaps you need to reduce the number of database connections for network performance or database licensing reasons), it does require the RAS to reconnect to the database in case additional records are required (for example, to process an on-demand subreport). The second choice will leave RAS connected to the database for the entire time the report job is active (typically, until a browser window is closed or a report object or database object in a custom CE application is destroyed ).

When you choose Server options, several options that determine how the RAS behaves when accessing report files and processing reports appear.

Minutes Before an Idle Connection Is Closed This setting determines how long the RAS waits before explicitly closing an open report job that hasn t had any activity (if you ve created a custom application, a job is considered open if a ReportClientDocument object is instantiated ). Normally, you won t need to change this setting. However, if you have certain viewers who leave browser windows open for long periods of time, you may wish to increase this number to accommodate them (but, at the expense of RAS scalability).
Maximum Simultaneous Report Jobs This is the number of report requests that the RAS will process simultaneously . A report request might consist of an initial page view, a report drill-down, an on-demand subreport request, and so forth. Typically, the default setting of 100 will be sufficient. However, if your particular reporting environment places a heavier demand on the RAS, you may wish to change this number depending on your hardware and operating system environment.
Report Directory This is probably the most common setting you ll need to change immediately upon installing CE Embedded. In fact, many of the sample applications available from the CE Embedded start page won t even work properly without changing this setting. By default, CE Embedded will access only reports in a certain directory, and any directory below that directory. This is provided as a security measure. Set the top-level directory with this option. To be able to process reports from any directory on the machine, place an asterisk (*) in this field.
Temp Directory CE Embedded creates temporary files as part of normal operation. If you wish to specify a particular location for these files, place a pathname in this field.

Once you ve made changes to various options to the dialog box, click OK to save the settings and return to the main Crystal Management Console screen. The changes will take effect when you restart the Report Application Server.

Customizing CE Embedded at Run Time with the RAS SDK

While the Report Viewer application discussed earlier in the chapter may be adequate for simpler integration requirements, you may wish to take fuller control of your web-based integration, much as you may have done with the RDC. The Report Application Server Software Development Kit (RAS SDK) provides a very involved object model to allow this. Just be aware: if you are used to the RDC object model, give yourself some extra time to adjust to the new approach the RAS SDK object model requires.

Note

You ll probably want to have the RAS SDK online help document handy while coding your custom application. This is contained within the Zip file available via the Developer Documentation item in the Crystal Enterprise 10 program group. Note that CE Embedded Edition is generally referred to simply as RAS within this documentation.

RAS SDK Model/View/Controller Architecture

The RAS SDK object model differs substantially from the RDC in both architecture and syntax. The first substantial difference is the way objects are organized and exposed. While the RDC is relatively flat, exposing only a few high-level objects, such as the Application object and the Report object, CE Embedded takes a different view of object orientation by introducing a Model/View/Controller (or MVC) architecture. MVC is a design paradigm often applied to application or development environments that separates application elements into three parts : model, view, and controller.

When attempting to fit the RAS SDK into this architecture, you can consider the three members of MVC to approximate to CE Embedded in this way:

View The end-user view of the report, this is designed by you (the developer) and presented to the end user in the user s browser.
Model All possible properties of a report, generally available in a read-only mode. The model exposes the names of fields, groups, formulas, report objects and sections, and so forth.
Controller All report objects that can be deleted, added, or modified. For the most part, however, you cannot query a controller to find out the existing status of a report object.

To put the MVC architecture in more of a real-world perspective for the CE Embedded developer, the view is the custom application, the model is where you get existing report properties, and the controller is where you change report properties. Probably the most important point here is that you must use a controller to modify report properties ”you can t do it with the model.

To further define the RAS SDK architecture, look at Table 22-2. This table breaks down the object models in the RAS SDK and their associated controllers. As you begin to work with CE Embedded, you ll soon discover the relationship between each as you modify reports at run time: get an existing value from the object model, make some changes to it, then pass it to a controller to actually modify the report. Or in the case of adding new report objects, create a new object, set its properties, then add it to the report via a controller.

Table 22-2: RAS SDK Object Models and Controllers
Types of Report Items	Object Model	Controller
Database connections, tables, links	Database Object	DatabaseController
Database fields, groups, record selection (filters), and so forth	DataDefinition Object	DataDefController
Report areas, sections, charts , cross-tabs, and so forth	ReportDefinition Object	ReportDefController
Unformatted flat data within the report	Rowset Object	RowsetController

In greatly simplified form, then, you could retrieve the second formula object in an existing report with

 DataDefinition.FormulaFields(2)

and you could update the contents of the same formula with

 DataDefController.FormulaFieldController.Modify 2, NewFormula

The ObjectFactory

While perusing sample applications included with CE Embedded, or the sample application from this book s web site (www.CrystalBook.com), you will encounter reference to the ObjectFactory. The Object Factory is simply a wrapper around other CE Embedded objects that appends a version number onto any objects you create from within it. This is an innovative approach to version control that will help you immensely when upgrading to later versions of CE Embedded, or when working with multiple versions of Crystal Enteprise on the same computer.

With Crystal Reports versions 8.5 and earlier, newer versions of Crystal tools that were installed on a computer replaced any previous versions that may have existed. This made it difficult, if not impossible , to support multiple versions of the same Crystal product on the same computer. However, Crystal version 9 and later largely eliminates this restriction. The RAS SDK is designed to allow easy version changes in just one place, the declaration of the ObjectFactory.

Compare the following two pieces of sample CE Embedded code:

 Set rptAppSession = _ 
 CreateObject("CrystalReports.ReportAppSession.2")

This piece of code creates a new object called rptAppSession using the Prog ID of CrystalReports.ReportAppSession.2 (this was a RAS version 9 Prog ID). This gets the object definition from one of the RAS SDK object libraries, in particular, the version 2 library. Contrast this with the following, which instantiates a version 10 ObjectFactory:

 Set objFactory = CreateObject("CrystalReports10.ObjectFactory.1") 
 Set rptAppSession = _ 
 objFactory.CreateObject("CrystalReports.ReportAppSession")

Initially, you d think the first option would be more efficient, as it requires only one line of code. However, if you subsequently need to create many additional objects throughout the remainder of the project, you can use the objFactory CreateObject method to create them, rather than creating them with direct Prog IDs from the RAS SDK libraries. The result: when CE Embedded version 11 is released, you need only change one reference in the code (the original CreateObject function that instantiates the original objFactory object). All remaining object creation statements may be left as is, and they ll automatically be adjusted to the new version of CE Embedded!

ReportAppSession

If you ve developed applications with the RDC, you re probably familiar with the Application object, which is the first object that you must declare in the RDC. The RAS SDK has a similar requirement to use the ReportAppSession object. This object establishes a session with the actual Report Application Server itself (remember from earlier discussions that the RAS SDK and Report Application Server can reside on separate computers). The ReportAppSession object establishes a connection with the Report Application Server prior to opening an existing report or creating a new report.

Examine the following sample code:

 Set rptAppSession = _ 
 objFactory.CreateObject("CrystalReports.ReportAppSession") 
 
 ' RAS Server name is taken from clientSDKOptions.XML, 
 ' or can be specified by setting ReportAppServer property 
 ' rptAppSession.ReportAppServer = "AblazeServer" 
 
 rptAppSession.Initialize

A rptAppSession object is created, using the Object Factory s CreateObject method. Optionally, the rptAppSession object s ReportAppServer property can be set to point this particular session to a specific RAS server computer. If this property is not set within your code (notice that the line is commented out in this sample), then the RAS SDK uses the RAS server specified in the file clientSDKOptions.XML located in the folder \Program Files\Crystal Decisions\Report Application Server 10 to determine which CE Embedded server to use. The file looks similar to this:

You may edit this file with a text editor, changing the value between the <Server> and </Server> tags. Also, if you wish to connect to the RAS server via something other than the default TCP/IP port, you may add a colon , followed by the port number, after the server name within these tags.

By separating the RAS server computer from the web server (where the RAS SDK libraries are typically located), you can generally improve overall performance by eliminating the report processing tasks from the web server (a limitation imposed by the RDC).

Once you ve declared the rptAppSession object, execute its Initialize method to actually commence communications with the RAS server before proceeding.

ReportClientDocument

Continuing the comparison to the RDC, the RAS SDK also establishes an initial object to refer to a specific report that you will use throughout the remainder of your application. The report object can be either an existing .RPT file that already exists on disk or a new report object definition that you will continue to build as your application proceeds.

This object is known as a ReportClientDocument object, as is created using the following example:

 'Create a new ReportClientDocument object for this reportAppSession 
 Set oClientDoc = _ 
 rptAppSession.CreateService("CrystalClientDoc.ReportClientDocument")

The ReportClientDocument is created with the ReportAppSession s CreateObject method, with the prog ID CrystalClientDoc.ReportClientDocument supplied as the argument.

Once this object has been created, however, you must execute a method that it exposes to either open an existing report or create a new report. Examine the following:

 Dim ReportName 
 
 ' Turn virtual directory into physical pathname 
 ReportName = MID(request.ServerVariables("PATH_TRANSLATED"), 1, _ 
 (LEN(request.ServerVariables("PATH_TRANSLATED"))-18)) 
 
 ' Append report name to it 
 ReportName = ReportName & "Last Year's Sales.rpt" 
 
 'Open the report 
 oClientDoc.Open ReportName

This code uses the ReportName variable to initially store the physical pathname to the calling ASP. In the preceding example, the calling ASP is LastYearsSales.ASP, the name of the ASP being 18 characters long. By using the PATH_TRANSLATED member of the Request object s ServerVariables collection, you can obtain the actual physical path to LastYearsSales.ASP. By using Mid and Len functions, the preceding sample strips off the rightmost 18 characters, returning just the physical pathname. The actual .RPT filename is then appended to the ReportName variable to derive the entire physical path/filename for the report. This, in turn, is supplied to the ReportClientDocument (oClientDoc) open method to actually open the Crystal Report.

Tip	The entire process of deriving the physical pathname is unnecessary if you have a fixed location for your reports, such as C:\Reports. In that case, simply provide the actual physical path/filename to the Open method, as in: oClientDoc.Open "C:\Reports\Last Years Sales.rpt"

Because of the multi-server nature of CE Embedded, the possibility exists that the report file you are trying to open may be on a different computer than the actual RAS Server itself. By default, the ReportClientDocument object Open method will open the report on the RAS Server machine. If the RAS Server and RAS SDK are being run on the same single computer, this is a straightforward process.

However, if you ve separated the two portions of CE Embedded on two separate computers, you may need to think carefully about where the report .RPT file actually resides. CE Embedded documentation recommends storing .RPT files on the computer that is operating as the RAS Server. Since this computer is the machine to actually process the report, including making the database connection, it is more efficient to have the report file reside on this machine. However, if for some reason or another this isn t practical, you can store .RPT files on the RAS SDK computer. When you execute the ReportClientDocument Open method, the .RPT file will be copied to the RAS Server machine prior to report processing (this copy operation is where the efficiency issue comes into play).

To indicate that the report file is located on the RAS SDK computer, preface the report filename argument with the characters rassdk:// (note that this prefix is case-sensitive ” don t use uppercase letters ). Thus, the previous Open method example would look like this, if the report file were located on the RAS SDK computer:

 oClientDoc.Open "rassdk://C:\Reports\Last Years Sales.rpt"

Caution

Report path names supplied to RAS SDK calls are relative to the report pathname set in the Crystal Configuration Manager (CCM) Report Directory property. If you want the RAS SDK to be able to access a report anywhere on a drive, supply an asterisk as the Report Directory in the CCM. Otherwise, you will only be able to access reports in (or below) the supplied directory.

Controlling General Report Behavior with the RAS SDK

The sample application available on this book s web site (visit www.CrystalBook.com to download the application) provides a moderate level of report customization at run time. By gathering several items from the end user in an initial web form and passing them to the report at run time, the application demonstrates how to customize a report from within a CE Embedded application, much as a similar application (discussed earlier in the chapter, and also available from the book s web site) performs customization with the RDC. Some of the more common report customization procedures follow.

Report Database Login

If you ve designed a report against a secure database, either you or your report user must provide login credentials before the report will process. You may either do this within your code or let the chosen Crystal Report viewer prompt the user directly.

In many cases, you may have already gathered login credentials from the user earlier in your application, or they are provided as an internal part of the application automatically. In either of these cases, you ll probably not want to pester the user again by allowing the report viewer to prompt for login credentials. While there are several ways to supply this information from within the RAS SDK, one of the simplest is the DatabaseController s logon method, demonstrated here:

 'Logon to database, if necessary 
 oClientDoc.DatabaseController.Logon "DBReader", "DBReader"

This simple method takes two parameters: a user ID and a password. The Logon method will pass this logon information to every table in the report (with the assumption that all tables came from the same database with the same login credentials). If you need to supply individual login credentials for certain tables, use the DatabaseController s SetConectionInfos or ModifyTableConnectionInfo methods .

Record Selection

One of the major features of integrated Crystal reporting, no matter what the method or environment, is controlling report record selection from within your application. You ll often want to change report record selection according to some object on a web form, or according to some other logic within the application. Accordingly, one of the first RAS SDK processes you ll want to learn about is controlling record selection.

While there are several ways of modifying the report s record selection formula at run time, modification of a filter object s FreeEditingText property is the most straightforward. Similar to the RecordSelectionFormula property exposed by other Crystal object models (such as the RDC and Visual Stuio.NET), the FreeEditingText property consists of the actual Crystal Reports record selection formula, which is applied when the report is run. Consider the following sample code:

 Dim filter 
 ' Get existing filter object from DataDefController 
 Set filter = _ 
 oClientDoc.DataDefController.DataDefinition.RecordFilter 
 
 ' Set record selection formula via FreeEditingText property 
 filter.FreeEditingText = "{Customer.Country} = 'USA'" 
 ' Apply the new filter via the Record Filter Controller 
 oClientDoc.DataDefController.RecordFilterController.modify filter

Here, a filter object is instantiated from the ReportClientDocument s DataDefController DataDefinition RecordFilter. Keeping with the Model/View/Controller architecture discussed earlier, you cannot modify the record selection formula directly with this object, however. You must set the FreeEditingText property of the filter to your new record selection formula, and then pass it to the report by way of the ReportClientDocument DataDefController RecordFilterController s Modify method, passing the filter you changed earlier as the argument.

Note

While modification of the FreeEditingText property is a simple, straightforward method of setting record selection at run time, an alternative method is available in the RAS SDK. You may build a series of individual filter parts and then create a collection of filter items. This collection is then eventually passed to the report via the RecordFilterController s modify method. An example of this approach is discussed in the CE SDK online help, as well as illustrated in the RAS SDK sample application from CrystalBook.com.

Controlling Groups

You may also find a need to change, remove, or add report grouping within your CE Embedded code. This is a fairly straightforward process (at least once you ve mastered the general Model/View/Controller approach of get the existing information from the model, update it, and update the report via a controller ).

Examine the following sample code:

 'Create a new group 
 Dim NewGroup 
 Set NewGroup = oClientDoc.DataDefinition.Groups(0).Clone

First, declare an object to hold a single object from the DataDefinition object s Groups collection. The Clone method can then be used to copy an existing group object, including all its current properties and values, from the report.

Next, add the new field you wish to base the group on:

 'Set the field that will define how data is grouped. 
 NewGroup.ConditionField = _ 
 oClientDoc.Database.Tables.Item(0).DataFields.Item(12) 
 'Customer.Country is the 13th field in the first table

The group object s ConditionField property is set to the field that you wish to now base that group on. Note that additional information about the group, such as Specified Order and Date grouping information, is specified with SpecifiedGroupOptions and DateGroupOptions objects.

Also of note in the RAS SDK is the closer connection between grouping and sorting. If you wish to change the sort direction of the group (from ascending to descending), you must actually make this specification in a separate Sorts collection within the DataDefinition object.

In this example, you can now remove the existing group and add the newly defined group object in its place, using controllers:

 'Remove the existing group 
 oClientDoc.DataDefController.GroupController.Remove 0 
 
 'Add the new group to the end of the groups collection 
 oClientDoc.DataDefController.GroupController.Add -1, NewGroup

The Remove method removes an existing group, taking one parameter: the zero-based index of the group to remove. Then, the Add method is executed to add the new group to the report. The Add method takes two parameters: the location in the Groups collection where you wish the new group to be placed ( “1 adds to the end of the collection, making it the innermost group), and the group object to add.

Caution

The RAS 10 SDK GroupController s Modify method does not allow a group object to be supplied with a different field than the original group. Instead, the existing group must be removed and a new group added in its place (as the preceding code illustrates). While this does, in fact, change the grouping, it also removes any summary or subtotal objects from the group footer, as well as the group name field from the group header. When the process is complete, you have a properly grouped report, but no objects in the group header or footer. While you could take this approach and then programmatically add new objects into these sections, you may find an alternative way of changing grouping without destroying all group header/footer objects to be more palatable. The sample CE Embedded application from www.CrystalBook.com instead modifies a formula that the report group is based on.

Modifying Parameter Fields

Probably one of the most common requirements of integrating Crystal Reports into custom applications is supplying parameter field values from within your code. Again, following the get data from the model, update, change the report with controller approach, this is straightforward.

Examine the following code gleaned from the sample application from www.CrystalBook.com:

 'Copy existing parameter to NewParam object 
 Set NewParam = oClientDoc.DataDefinition.ParameterFields(0).Clone

Use the DataDefinition object s ParameterFields collection to get the value and properties (data type, and so on) of an existing parameter field. This is accomplished with the Clone method, which creates a mirror-image object from the desired parameter field.

Depending on the type of parameter field (discrete value, range value, multi-value ), you ll need to create an additional object to hold the parameter field s value, as in

 'Create new "DiscreteValue" object to hold new parameter's value 
 Set NewValue = _ 
 objFactory.CreateObject("CrystalReports.ParameterFieldDiscreteValue")

In this case, a discrete (single) value is required for this parameter field, which is used to calculate a sales tax rate within the report. The NewValue object is created by calling the ObjectFactory s CreateObject method.

Then, you need to supply the actual value to the NewValue object.

 If Trim(Request.Form("txtTaxRate")) = "" Then 
 NewValue.Value = 0 
 Else 
 NewValue.Value = CDbl(Request.Form("txtTaxRate")) 
 End If  'Request.Form("txtTaxRate") = ""

In this example, an If-Then-Else construct is used to set the Value property of the DiscreteValue object, based on a control on the originating web form.

Tip	Notice how VBScript s CDbl typecast function is used when setting the Value property of the NewValue object. It s important in the RAS SDK to ensure that data is properly typed when supplying it to CE Embedded properties. Use VBScript s typecasting functions, such as CStr and CDbl, to ensure this.

Before actually updating the report with the new parameter field, you must add the DiscreteValue object to the actual parameter field object, as in:

 'Set the new value for the parameter 
 NewParam.CurrentValues.Add(NewValue)

Execute the parameter field object s CurrentValues collection s Add method, supplying the parameter field value object created earlier (it may be a discrete value, a range value, or a multi-value object, depending on how it was originally defined).

Then, actually update the report with the new parameter field object.

 'Modify the first parameter field with the NewParam object 
 oClientDoc.DataDefController.ParameterFieldController.Modify 0, NewParam

As in previous examples, you must use a controller to actually modify the report. In this case, the ParameterFieldController s Modify method will, in essence, replace the parameter field specified in the first argument with the parameter field object supplied via the second argument.

Changing Report Formulas

Another way of performing many run-time modifications to a report, in addition to or instead of using parameter fields, is modifying report formulas within your code. The RAS SDK continues the get from model, update, modify with controller approach to formula modifications.

Examine the following sample code:

 'Copy the first existing Formula 
 Set NewFormula = oClientDoc.DataDefinition.FormulaFields(0).Clone 
 
 'Set text of new formula 
 NewFormula.Text = chr(34) & SelectionText & chr(34) 
 
 'Update first formula in report with new formula 
 oClientDoc.DataDefController.FormulaFieldController.Modify 0, NewFormula

Much as with parameter fields, an existing formula is extracted from the DataDefinition object FormulaFields collection using the Clone method. The new formula field object s Text property is changed to reflect the new desired formula (in the case of the preceding code, a variable set earlier in the code that simply contains literal text, surrounded by quotation marks). In this case, everything else about the formula remains as it was when originally cloned (field heading, syntax, and so on). If you wish to change these items, or if you are creating a new formula from scratch, you ll find other FormulaField object properties you can set, such as Syntax and HeadingText.

Viewing the Report

Once you ve finished manipulating the ReportClientDocument, you need to display it to the viewer in the viewer s web browser. As with the RDC, there are several viewing options available to you, depending on how much interactivity you wish to provide to the viewer, whether you ll be showing the entire report or just report parts, and whether you still need the completely integrated solution provided by the ActiveX thin-client viewer.

Available CE Embedded Viewers

As when using the Report Designer Component, you can use the legacy ActiveX and Java thin-client viewers with CE Embedded. And in some cases, you ll find the best combination of performance, true format report viewing, and integrated functionality with these viewers. However, Business Objects has been very creative in maximizing the use of DHTML (Dynamic Hypertext Markup Language) and a flexible COM object model in CE Embedded. This creativity, along with Crystal Reports report part capabilities, Office XP smart tags, and the advent of wireless web technology (in web-enabled cell phones and Personal Digital Assistants) has led to HTML-based report viewers being the desired direction with CE Embedded.

Note

The terms thin client, thick client, and zero client are often confused when referring to an application s footprint. In the case of the CE Embedded report viewers, this book refers to HTML-based viewers as zero client and ActiveX- or Java applet “based viewers as thin client. This contrasts with thick client, which the book considers to be a full-fledged, PC-based Windows application.

Available report viewers for use in Active Server Pages include the following:

COM Report Page Viewer This HTML-based viewer provides good basic report viewing capabilities, including the ability to export to another file format and print paginated text to your local printer, via a downloaded Portable Document Viewer file.
COM Interactive Viewer This HTML-based viewer largely duplicates the features of the Report Page Viewer, while also adding a new Boolean search capability that allows a user to display a search wizard to apply sophisticated searching against the data in the report.
COM Report Part Viewer This new HTML-based subset of the Report Page Viewer provides new Report Part capabilities to show only certain parts of a report (such as charts, text, and fields) in a browser. The Report Part Viewer is helpful when integrating Crystal Reports into portal applications when you desire only a specific part of a report to appear in a portal page. The Report Part Viewer can be further enhanced with special drill-down capabilities to allow a fuller view of a report part to be displayed when the report part is clicked.
COM Grid Viewer An HTML-based viewer that display report data in a row/column style independent of any report formatting actually specified in the report. This viewer may be handy for export or data extraction requirements where data requirements don t rely on (and may be hindered by) embedded formatting from within the report.
ActiveX Viewer A legacy report viewer also available with the RDC, this viewer displays native Crystal Reports formatting in a thin-client ActiveX control. The control allows exporting and printing to the locally attached printer without an intermediate .PDF file download. This viewer requires an ActiveX-capable browser, such as Microsoft Internet Explorer.

Java Viewer Another legacy report viewer also available with the RDC, this viewer displays native Crystal Reports formatting in a thin-client Java applet. The applet allows exporting and printing to the locally attached printer without an intermediate .PDF file download. This viewer requires a Java-capable browser, such as Netscape Navigator, or a locally installed Java Virtual Machine.

Tip	Complete object models and sample code for all viewers are included with the RAS SDK online documentation. In particular, the Report_Viewers.chm help file, extracted from the RAS SDK ZIP file, contains thorough documentation on the HTML-based RAS SDK report viewers.

Passing a Report to the Viewer

There are several ways of viewing a report with one of the available report viewers. For example, you may wish to look at some simple viewing ASPs that can be redirected to from your ASP code to view reports. Look for these ASPs (such as CrystalReportPageViewer.ASP) in Program Files\Crystal Decisions\Report Application Server 10\Samples\< language >\ASP\RDCMigration.

Using one of these supplied viewer ASPs, viewing a report object that you ve modified with the RAS SDK is as simple as the following code:

 'Call the viewer to display the new report 
 Set Session("oClientDoc") = oClientDoc 
 Response.Redirect("CrystalReportPageViewer.ASP")

In the preceding code fragment, a session object variable is next created to contain the ReportClientDocument that has already been manipulated, as described earlier in the chapter. Then, control is redirected to the CrystalReportPageViewer.ASP file, which follows :

 <%@CodePage=65001%> 
 <% 
 Response.ContentType = "text/html; charset=utf-8" 
 
 'Define ObjectFactory 
 Dim ObjectFactory 
 Set ObjectFactory = CreateObject("CrystalReports10.ObjectFactory.1") 
 
 Set HTMLViewer = _ 
 ObjectFactory.CreateObject("CrystalReports.CrystalReportViewer")

The code page and content type are set to allow Unicode display for multi-language web pages. The next step (as described earlier in the chapter) is to declare an ObjectFactory object to control versioning of subsequent object definitions. This ObjectFactory capability extends to the COM Viewer SDK, as well as the RAS SDK. Then, a new object is created via the ObjectFactory CreateObject method, using the CrystalReportViewer class from the COM Viewer SDK. This is the instance of the COM Page Viewer described previously.

Finally, the report is viewed with the following code:

 With HTMLViewer 
 .ReportSource = session("oClientDoc").ReportSource 
 .Name = "Crystal Reports Preview" 
 .IsDisplayGroupTree = False 
 End With 
 
 response.write(HTMLViewer.ProcessHTTPRequest(Request, Response, Session)) 
 %>

The Viewer object s ReportSource property is set to the ReportClientDocument session object variable that was set in the calling ASP. The Name property is used to differentiate between multiple Viewer objects in the same HTML page. And, the Viewer object s IsDisplayGroupTree property is set to false to hide the group tree. Finally, a Response.Write statement routes the Viewer object s ProcessHTTPRequest method to actually render the report in HTML and return it to the browser. The three parameters being passed to this method are standard Active Server Page Request, Response, and Session objects. The resulting report looks similar to this inside a web browser:

Another viewer that s available is the COM Interactive Viewer. This viewer, which is similar to the COM Page Viewer, includes additional capabilities to query and manipulate the data returned by a report. An example of an ASP that calls this viewer can be found in Program Files\Crystal Decisions\Report Application Server 10\Samples\< language >\ASP\RDCMigration. CrystalReportInteractiveViewer.asp, which is similar to the CrystalReportViewer.asp file described previously, instantiates the Interactive Viewer and displays a report passed in a session variable.

Examining this ASP will show an additional BooleanSearchControl object that can be defined to provide the advanced search capability. By clicking the Show/Hide Advanced Search Wizard link at the top of the viewer, you are presented with the Advanced Search Wizard (enabled with the BooleanSearchControl object).

This wizard is designed to perform an additional detailed query on the data contained in the report. The wizard consists of three tabs: Fields, Conditions, and Results.

On the Fields tab, choose the result fields from the report that you wish to see in the query s resulting display. One or more fields can be selected by CTRL-clicking on the desired fields and then clicking the single right arrow (or all fields can be added with the double right arrow).

The Conditions tab is where the Boolean part of the search comes into play. Choose a particular field you wish to use to filter the report s data. Then, choose the search criterion in the Filter Type list. Finally, type in a value for the comparison in the Value text box. You may add more than one criterion by clicking the Add More Filters button, as well as typing in a Crystal Reports selection formula directly by clicking the Free Form button.

Once you ve completed the Fields and Conditions tabs, click the Results tab. The resulting subset of the report data will appear in a small row/column grid at the top of the Interactive Viewer.