Crystal Reports 9 The Complete Reference PHẦN 8 doc

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, RAS 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 RAS 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 RAS 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 21-2. This table breaks down the object models in the RAS SDK and their associated controllers. As you begin to work with RAS, 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. 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 594 Crystal Reports 9: The Complete Reference Chapter 21: Crystal Reports and Microsoft Active Server Pages 595 CRYSTAL REPORTS 9 ON THE WEB The ObjectFactory While perusing sample applications included with RAS, or the sample application from this book’s Web site (www.CrystalBook.com), you will encounter reference to the ObjectFactory, which you have not seen previously with the RDC or even with earlier versions of Crystal Enterprise. The ObjectFactory is simply a “wrapper” around other RAS 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 RAS, or when working with multiple versions of RAS on the same computer. Typically, when newer versions of Crystal Decisions tools have been installed on a computer, they replace any previous versions that may have existed—it’s often been difficult, if not impossible, to support multiple versions of the same Crystal Decisions product on the same computer. Not only does Crystal Reports 9 share a computer nicely with an earlier version, but 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 RAS code: Set rptAppSession = _ CreateObject("CrystalReports.ReportAppSession.2") 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 Table 21-2. RAS SDK Object Models and Controllers This piece of code creates a new object called rptAppSession using the Prog ID of “CrystalReports.ReportAppSession.2.” This gets the object definition from one of the RAS object libraries, in particular, the “version 2” library. Contrast this with Set objFactory = CreateObject("CrystalReports.ObjectFactory.2") 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 libraries. The result: when RAS version 3 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 RAS! 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. RAS 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 RAS 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 596 Crystal Reports 9: The Complete Reference Chapter 21: Crystal Reports and Microsoft Active Server Pages 597 CRYSTAL REPORTS 9 ON THE WEB folder \Program Files\Crystal Decisions\Report Application Server 9 to determine which RAS 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 also establishes an initial object to refer to a specific report object 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 (don’t forget that the ability to create a new report from within your custom application is available only if you’ve purchased Crystal Reports Advanced Edition). 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") 598 Crystal Reports 9: The Complete Reference 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. 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 multiserver nature of RAS, 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 RAS on two separate computers, you may need to think carefully about where the report .RPT file actually resides. Crystal Decisions 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" 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 RAS 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 RAS, one of the simplest is the DatabaseController’s logon method, demonstrated here: 'Logon to database, if necessary oClientDoc.DatabaseController.Logon "DBReader", "DBReader" Chapter 21: Crystal Reports and Microsoft Active Server Pages 599 CRYSTAL REPORTS 9 ON THE WEB 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 SetConnectionInfos 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. As such, one of the first RAS processes you’ll want to learn about is controlling record selection. If you’ve used the RDC in the past, you’ll discover that changing record selection at run time isn’t nearly as straightforward with RAS as it was with the RDC. As opposed to simply modifying the record selection property of the Report object, RAS requires a more complex approach, based on the concept of filters and primitive expressions. Take, for example, the following common Crystal Reports record selection formula in Crystal syntax: {Customer.Country} = "USA" and {Orders.Order Amount} >= 1000 If this selection formula has already been added to the report before being opened, the report is considered by RAS to contain the following objects: A FieldRangeFilterItem containing the following properties: ■ RangeField The Customer.Country database field object ■ Operation The number 1 (for Equal To) ■ Inclusive False (not applicable to an Equal To operator) ■ Values Another collection of individual Value objects—in this case, a single ConstantValue object with the Value property containing “USA” Another FieldRangeFilterItem containing the following properties: ■ RangeField The Orders.Order Amount database field object ■ Operation The number 4 (for Greater Than) ■ Inclusive True, indicating the “or equal to” addition to the greater-than operator ■ Values Another collection of individual Value objects—in this case, a single ConstantValue object with the Value property containing 1000 600 Crystal Reports 9: The Complete Reference Both of these FieldRangeFilterItem objects are included in the DataDefinition Object’s FilterItems collection. Each is said to represent a “primitive expression,” or a Field- Operator-Value expression. In addition, the collection contains a third element known as an OperatorFilterItem object (in actuality, this item is the second element in the collection, between the two FieldRangeFilterItem objects). The OperatorFilterItem ties the two FieldRangeFilterItem objects together (in this case, the “And” which connects the two primitive expressions in the selection formula). The OperatorFilterItem’s Operator property can be set to the string AND, the string OR, a left parenthesis, or a right parenthesis. In the case of the previously discussed record selection formula, the property equates to AND. RAS proceeds through a process of parsing, or “picking apart” the various pieces of the record selection formula set in the report and loading the FilterItems collection with the combinations of primitive expressions and OperatorFilterItem objects. If the record selection formula is too complex to parse (it contains complex built-in Crystal Reports formula functions, or similar items), the FilterItems collection won’t be populated and the original record selection formula will appear in the Filter objects FreeEditingText property. If you think that this entire process unduly complicates the record selection process (especially when compared to the previous single RecordSelectionFormula property of the RDC’s report object), you may be right. This new architecture is no doubt the result of the redesigned Query Engine in Crystal Reports 9. However, with some examination of sample code and some experimenting, you’ll eventually be able to navigate this rather complex object model to control record selection within your RAS code. Examine the following: 'Create a new filter object Set NewFilter = objFactory.CreateObject("CrystalReports.Filter") 'FieldRangeFilterItem is used to store the filter info Set NewFilterItem = _ objFactory.CreateObject("CrystalReports.FieldRangeFilterItem") 'ConstantValue object is used by the FieldRangeFilterItem 'to store the comparison value Set NewConstantValue = _ objFactory.CreateObject("CrystalReports.ConstantValue") 'Build the NewFilterItem object NewFilterItem.RangeField = _ oClientDoc.Database.Tables.Item(0).DataFields.Item(12) 'Customer.Country is the 13th field in the first table NewConstantValue.Value = CStr("USA") Chapter 21: Crystal Reports and Microsoft Active Server Pages 601 CRYSTAL REPORTS 9 ON THE WEB TEAMFLY Team-Fly ® NewFilterItem.Values.Add NewConstantValue NewFilterItem.Operation = 1 'Number 1 is Equal To 'The completed NewFilterItem object is added into 'the NewFilter object NewFilter.FilterItems.Add NewFilterItem 'The new filter is assigned to the Report Document oClientDoc.DataDefController.RecordFilterController.Modify NewFilter The purpose of this entire block of code is to add the {Customer.Country} = “USA” filter to a report at run time (this code fragment is from the sample application on this book’s Web site and is based on a control on the original Web form). In this example, there is no reason to get the existing contents of the record selection formula, so it is not initially retrieved from the DataDefinition Object. Instead, new objects representing a Filter, a single FieldRangeFilterItem, and ConstantValue are defined. Then, the FieldRangeFilterItem object’s RangeField property is set to Customer.Country (the twelfth field in the report), the Operation property is set to 1 (for Equal To), and the ConstantValue object’s Value property is set to the string USA. The ConstantValue object is then added to the FieldRangeFilterItem object’s Values collection (there can be more than one member of this collection, in the case of many “One Of” values, for example). Then, the FieldRangeFilterItem object is added to the Filter object’s FilterItems collection. Since there is only one primitive expression in this situation, no additional FieldRangeFilterItems objects, or any OperatorFilterItem objects, are added. Finally, two controllers are used to modify the existing filter in the report with this new one. Again, be patient when you attempt to follow this logic and object model approach to record selection—it takes time to make complete sense of it. Controlling Groups You may also find a need to change, remove, or add report grouping within your RAS 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 602 Crystal Reports 9: The Complete Reference Chapter 21: Crystal Reports and Microsoft Active Server Pages 603 CRYSTAL REPORTS 9 ON THE WEB 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. Somewhat new in RAS 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. At the time of this book’s printing, the GroupController’s Modify method did not operate properly, requiring that an existing group 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 RAS application from www.CrystalBook.com instead modifies a formula that the report group is based on. [...]... of this book, Crystal Reports 9 does not work with the most recent release of Crystal Enterprise, version 8. 5 In order to take advantage of Crystal Enterprise, you’ll have to stick with Crystal Reports 8. 5 Therefore, all material in this chapter refers to Crystal Reports 8. 5 only However, Crystal Reports 9 includes a “sneak preview” of some of the upcoming features of Crystal Enterprise 9 For more information... FL Y Crystal Reports 9 is not compatible with Crystal Enterprise 8. 0 or 8. 5 The new RPT file format of version 9 cannot be read by older Enterprise versions You’ll need to use techniques discussed in Chapters 20 and 21, or wait for the release of the next version of Crystal Enterprise to make use of Crystal Reports 9 reports in Crystal Enterprise TE As an end user, you’ll normally start using Crystal. .. navigate to the proper location Chapter 22: Introduction to Crystal Enterprise 6 29 What Is the Crystal eBusiness Framework? The Crystal Management Console can be chosen as a link from the Crystal Enterprise Launchpad, or navigated to directly with the following URL: http:// /crystal/ enterprise/admin CRYSTAL REPORTS 9 ON THE WEB As you peruse marketing materials and documentation for Crystal. .. yourself working to justify the investment (To upgrade, you’ll need to contact Crystal Decisions or a limited set of key resellers, as Crystal Enterprise is not for sale in the same retail channel as Crystal Reports. ) 6 18 Crystal Reports 9: The Complete Reference There are several significant differences between the features offered in Standard Edition versus Professional Edition These differences revolve... 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 CRYSTAL REPORTS 9 ON THE WEB 'Modify the first parameter field with the NewParam object oClientDoc.DataDefController.ParameterFieldController.Modify 0, NewParam 606 Crystal Reports 9: The Complete Reference Viewing the Report Once... logical APS to the entire Crystal Enterprise system They share processing load, sending processing requests to the least-busy machine in the cluster If one machine should fail, the remaining APS machines pick up the load and continue to operate the end user will not even know that one of the APS machines has failed 625 626 Crystal Reports 9: The Complete Reference I Apache, Linux, Solaris (and other servers... included as a “free bundle” with Crystal Reports 8. 5 As of this publication, Crystal Enterprise (which was initially released at Version 8. 0) is available in two versions: Crystal Enterprise 8 Standard Edition and Crystal Enterprise 8. 5 Professional Edition If you received the Crystal Enterprise CD bundled with your copy of Crystal Reports 8. 5, you received Crystal Enterprise 8 Standard Edition Standard... Terms of Use 614 Crystal Reports 9: The Complete Reference he Crystal Reports 8. 5 release marked the introduction of a new Web-based report distribution system named Crystal Enterprise Since that time, the new framework has gained wide acceptance as organizations large and small realize the benefits of Crystal Enterprise’s scalability, security, and customization possibilities T As of the publication... Crystal Reports 9: The Complete Reference has been viewed By clicking the “Show/Hide Advanced Search Wizard” link at the top of the viewer (you’ll often need to scroll the bottom scroll bar all the way to the right to see this button), 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. .. with the majority of Crystal Enterprise features is a standard Web browser (a newer browser that supports HTML Version 4 and JavaScript is required) The only exception to the Web browser rule is for designing reports Crystal Reports 8. 5 is used to design reports and must run in a Windows environment And, there are several ways of publishing reports to Crystal Enterprise One way, the Crystal- supplied Crystal . _ rptAppSession.CreateService("CrystalClientDoc.ReportClientDocument") 5 98 Crystal Reports 9: The Complete Reference The ReportClientDocument is created with the ReportAppSession’s CreateObject method, with the prog ID “CrystalClientDoc.ReportClientDocument”. ObjectFactory Chapter 21: Crystal Reports and Microsoft Active Server Pages 607 CRYSTAL REPORTS 9 ON THE WEB 6 08 Crystal Reports 9: The Complete Reference Set ObjectFactory = CreateObject("CrystalReports.ObjectFactory.2") 'Call. NewGroup = oClientDoc.DataDefinition.Groups(0).Clone 602 Crystal Reports 9: The Complete Reference Chapter 21: Crystal Reports and Microsoft Active Server Pages 603 CRYSTAL REPORTS 9 ON THE WEB First,